Docs: Added Intro to histograms and heatmaps (#24174)

* Moved files

Moved files from guides folder into getting-started folder, added aliases, added Intro to histograms topic

* Updated links

* Update intro-histograms.md

Co-authored-by: Daniel Lee <dan.limerick@gmail.com>

docs/sources/_index.md

@@ -45,11 +45,11 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin",
 ## Guides
 
 <div class="nav-cards">
-    <a href="{{< relref "guides/what-is-grafana.md" >}}" class="nav-cards__item nav-cards__item--guide">
+    <a href="{{< relref "getting-started/what-is-grafana.md" >}}" class="nav-cards__item nav-cards__item--guide">
         <h4>What is Grafana?</h4>
         <p>Get an overview of Grafana's key features.</p>
     </a>
-    <a href="{{< relref "guides/getting_started.md" >}}" class="nav-cards__item nav-cards__item--guide">
+    <a href="{{< relref "getting-started/getting-started.md" >}}" class="nav-cards__item nav-cards__item--guide">
         <h4>Getting started</h4>
         <p>Learn the basics of using Grafana.</p>
     </a>
@@ -57,7 +57,7 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin",
         <h4>Configure Grafana</h4>
         <p>Review the configuration and setup options.</p>
     </a>
-    <a href="{{< relref "guides/timeseries.md" >}}" class="nav-cards__item nav-cards__item--guide">
+    <a href="{{< relref "getting-started/timeseries.md" >}}" class="nav-cards__item nav-cards__item--guide">
         <h4>Intro to time series</h4>
         <p>Learn about time series data.</p>
     </a>

docs/sources/getting-started/_index.md

++++
+title = "Getting started"
+type = "docs"
+[menu.docs]
+name = "Getting started"
+identifier = "getting-started"
+weight = 100
++++
+

docs/sources/guides/getting_started.md → docs/sources/getting-started/getting-started.md

@@ -3,12 +3,12 @@ title = "Getting started"
 description = "Guide for getting started with Grafana"
 keywords = ["grafana", "intro", "guide", "started"]
 type = "docs"
-aliases = ["/docs/grafana/latest/guides/gettingstarted"]
+aliases = ["/docs/grafana/latest/guides/gettingstarted","/docs/grafana/latest/guides/getting_started"]
 [menu.docs]
 name = "Getting started"
 identifier = "getting_started_guide"
 parent = "guides"
-weight = 100
+weight = 200
 +++
 
 # Getting started

docs/sources/guides/glossary.md → docs/sources/getting-started/glossary.md

@@ -3,11 +3,12 @@ title = "Glossary"
 description = "Grafana glossary"
 keywords = ["grafana", "intro", "glossary", "dictionary"]
 type = "docs"
+aliases = ["/docs/grafana/latest/guides/glossary"]
 [menu.docs]
 name = "Glossary"
 identifier = "glossary"
 parent = "guides"
-weight = 400
+weight = 500
 +++
 
 # Glossary

docs/sources/getting-started/intro-histograms.md

++++
+title = "Histograms and heatmaps"
+description = "An introduction to histograms and heatmaps"
+keywords = ["grafana", "heatmap", "panel", "documentation", "histogram"]
+type = "docs"
+[menu.docs]
+name = "intro-to-histograms"
+parent = "panels"
+weight = 400
++++
+
+# Introduction to histograms and heatmaps
+
+A histogram is a graphical representation of the distribution of numerical data. It groups values into buckets
+(sometimes also called bins) and then counts how many values fall into each bucket.
+
+Instead of graphing the actual values, histograms graph the buckets. Each bar represents a bucket,
+and the bar height represents the frequency (such as count) of values that fell into that bucket's interval.
+
+## Histogram example
+
+This histogram shows the value distribution of a couple of time series. You can easily see that
+most values land between 240-300 with a peak between 260-280.
+
+![](/img/docs/v43/heatmap_histogram.png)
+
+Histograms only look at _value distributions_ over a specific time range. The problem with histograms is you cannot see any trend or changes in the distribution over time.
+This is where heatmaps become useful.
+
+## Heatmaps
+
+A _heatmap_ is like a histogram, but over time where each time slice represents its own histogram. Instead of using bar height as a representation of frequency, it uses cells and colors the cell proportional to the number of values in the bucket.
+
+In this example, you can clearly see what values are more common and how they trend over time.
+
+![](/img/docs/v43/heatmap_histogram_over_time.png)
+
+## Pre-bucketed data
+
+There are a number of data sources supporting histogram over time like Elasticsearch (by using a Histogram bucket
+aggregation) or Prometheus (with [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) metric type
+and *Format as* option set to Heatmap). But generally, any data source could be used if it meets the requirements:
+returns series with names representing bucket bound or returns series sorted by the bound in ascending order.
+
+## Raw data vs aggregated
+
+If you use the heatmap with regular time series data (not pre-bucketed), then it's important to keep in mind that your data
+is often already aggregated by your time series backend. Most time series queries do not return raw sample data
+but include a group by time interval or maxDataPoints limit coupled with an aggregation function (usually average).
+
+This all depends on the time range of your query of course. But the important point is to know that the histogram bucketing
+that Grafana performs might be done on already aggregated and averaged data. To get more accurate heatmaps it is better
+to do the bucketing during metric collection or store the data in Elasticsearch, or in the other data source which
+supports doing histogram bucketing on the raw data.
+
+If you remove or lower the group by time (or raise maxDataPoints) in your query to return more data points your heatmap will be
+more accurate but this can also be very CPU and memory taxing for your browser and could cause hangs and crashes if the number of
+data points becomes unreasonably large.

docs/sources/guides/timeseries.md → docs/sources/getting-started/timeseries.md

@@ -4,6 +4,7 @@ description = "Introduction to time series"
 keywords = ["grafana", "intro", "guide", "concepts", "timeseries"]
 type = "docs"
 [menu.docs]
+aliases = ["/docs/grafana/latest/guides/timeseries"]
 name = "Time series"
 identifier = "time_series"
 parent = "guides"

docs/sources/guides/what-is-grafana.md → docs/sources/getting-started/what-is-grafana.md

@@ -4,6 +4,7 @@ description = "Overview of Grafana and features"
 keywords = ["grafana", "intro", "guide", "started"]
 type = "docs"
 [menu.docs]
+aliases = ["/docs/grafana/latest/guides/what-is-grafana"]
 name = "What is Grafana?"
 identifier = "what_is_grafana"
 parent = "guides"
@@ -12,11 +13,11 @@ weight = 200
 
 # What is Grafana?
 
-This topic provides a high-level look at Grafana, the Grafana process, and Grafana features. It's a good place to start if you want to learn more about Grafana software. To jump right in, refer to [Getting started]({{< relref "getting_started.md" >}}).
+This topic provides a high-level look at Grafana, the Grafana process, and Grafana features. It's a good place to start if you want to learn more about Grafana software. To jump right in, refer to [Getting started]({{< relref "getting-started.md" >}}).
 
 Grafana is open source visualization and analytics software. It allows you to query, visualize, alert on, and explore your metrics no matter where they are stored. In plain English, it provides you with tools to turn your time-series database (TSDB) data into beautiful graphs and visualizations.
 
-After creating a dashboard like you do in [Getting started]({{< relref "getting_started.md" >}}), there are many possible things you might do next. It all depends on your needs and your use case. 
+After creating a dashboard like you do in [Getting started]({{< relref "getting-started.md" >}}), there are many possible things you might do next. It all depends on your needs and your use case. 
 
 For example, if you want to view weather data and statistics about your smart home, then you might create a playlist. If you are the administrator for a corporation and are managing Grafana for multiple teams, then you might need to set up provisioning and authentication.
 

docs/sources/installation/_index.md

@@ -7,7 +7,7 @@ aliases = ["/docs/grafana/latest/installation/installation/", "/docs/grafana/v2.
 [menu.docs]
 name = "Installation"
 identifier = "installation"
-weight = 1
+weight = 200
 +++
 
 ## Install Grafana

docs/sources/installation/debian.md

@@ -164,7 +164,7 @@ Start Grafana by running:
 
 ## Next steps
 
-Refer to the [Getting Started]({{< relref "../guides/getting_started/" >}}) guide for information about logging in, setting up data sources, and so on.
+Refer to the [Getting Started]({{< relref "../getting-started/getting-started/" >}}) guide for information about logging in, setting up data sources, and so on.
 
 ## Configure Grafana
 

docs/sources/installation/docker.md

@@ -217,7 +217,7 @@ chown -R grafana:grafana /usr/share/grafana
 
 ## Next steps
 
-Refer to the [Getting Started]({{< relref "../guides/getting_started/" >}}) guide for information about logging in, setting up data sources, and so on.
+Refer to the [Getting Started]({{< relref "../getting-started/getting-started/" >}}) guide for information about logging in, setting up data sources, and so on.
 
 ## Configure Docker image
 

docs/sources/installation/rpm.md

@@ -202,7 +202,7 @@ Start Grafana by running:
 
 ## Next steps
 
-Refer to the [Getting Started]({{< relref "../guides/getting_started/" >}}) guide for information about logging in, setting up data sources, and so on.
+Refer to the [Getting Started]({{< relref "../getting-started/getting-started/" >}}) guide for information about logging in, setting up data sources, and so on.
 
 ## Configure Grafana
 

docs/sources/installation/windows.md

@@ -31,19 +31,19 @@ You can either use the Windows installer or you can install a standalone Windows
 1. Click **Download the installer**.
 1. Open and run the installer. 
 
-To run Grafana, open your browser and go to the Grafana port (http://localhost:3000/ is default) and then follow the instructions in [Getting Started]({{< relref "../guides/getting_started/" >}}).
+To run Grafana, open your browser and go to the Grafana port (http://localhost:3000/ is default) and then follow the instructions in [Getting Started]({{< relref "../getting-started/getting-started/" >}}).
 
 ## Install standalone Windows binary
 
 1. Click **Download the zip file**.
    **Important:** After you've downloaded the zip file and before extracting it, make sure to open the properties for that file (right-click **Properties**) and select the `unblock` check box and then click `Ok`.
 
-2. Extract this folder to anywhere you want Grafana to run from. 
+1. Extract this folder to anywhere you want Grafana to run from. 
 
-3. Start Grafana by executing `grafana-server.exe`, located in the `bin` directory, preferably from the command line. If you want to run Grafana as a Windows service, then download
+1. Start Grafana by executing `grafana-server.exe`, located in the `bin` directory, preferably from the command line. If you want to run Grafana as a Windows service, then download
 [NSSM](https://nssm.cc/). It is very easy to add Grafana as a Windows service using that tool.
 
-To run Grafana, open your browser and go to the Grafana port (http://localhost:3000/ is default) and then follow the instructions in [Getting Started]({{< relref "../guides/getting_started/" >}}).
+To run Grafana, open your browser and go to the Grafana port (http://localhost:3000/ is default) and then follow the instructions in [Getting Started]({{< relref "../getting-started/getting-started/" >}}).
 
 > **Note:** The default Grafana port is `3000`. This port might require extra permissions on Windows. If it does not appear in the default port, you can try changing to a different port.
 >

docs/sources/menu.yaml

 - name: Getting started
-  link: /guides/
+  link: /getting-started/
   children:
     - name: What is Grafana?
-      link: /guides/what-is-grafana/
+      link: /getting-started/what-is-grafana/
     - name: Getting started
-      link: /guides/getting_started/
+      link: /getting-started/getting-started/
     - name: Intro to time series
-      link: /guides/timeseries/
+      link: /getting-started/timeseries/
+    - name: Intro to histograms
+      link: /getting-started/intro-histograms/
     - name: Glossary
-      link: /guides/glossary/
+      link: /getting-started/glossary/
 - name: Installation
   link: /installation/
   children: