From 376749ee3281e483b90af72c735c8ff05475c4ba Mon Sep 17 00:00:00 2001 From: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> Date: Tue, 5 May 2020 15:23:30 -0700 Subject: [PATCH] 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 --- docs/sources/_index.md | 6 +- docs/sources/getting-started/_index.md | 9 +++ .../getting-started.md} | 4 +- .../{guides => getting-started}/glossary.md | 3 +- .../getting-started/intro-histograms.md | 58 +++++++++++++++++++ .../{guides => getting-started}/timeseries.md | 1 + .../what-is-grafana.md | 5 +- docs/sources/installation/_index.md | 2 +- docs/sources/installation/debian.md | 2 +- docs/sources/installation/docker.md | 2 +- docs/sources/installation/rpm.md | 2 +- docs/sources/installation/windows.md | 8 +-- docs/sources/menu.yaml | 12 ++-- 13 files changed, 93 insertions(+), 21 deletions(-) create mode 100644 docs/sources/getting-started/_index.md rename docs/sources/{guides/getting_started.md => getting-started/getting-started.md} (95%) mode change 100755 => 100644 rename docs/sources/{guides => getting-started}/glossary.md (97%) create mode 100644 docs/sources/getting-started/intro-histograms.md rename docs/sources/{guides => getting-started}/timeseries.md (99%) mode change 100755 => 100644 rename docs/sources/{guides => getting-started}/what-is-grafana.md (97%) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 99bf35c18c7..71b9959136f 100755 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -45,11 +45,11 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin", ## Guides
- }}" class="nav-cards__item nav-cards__item--guide"> + }}" class="nav-cards__item nav-cards__item--guide">

What is Grafana?

Get an overview of Grafana's key features.

 - }}" class="nav-cards__item nav-cards__item--guide"> + }}" class="nav-cards__item nav-cards__item--guide">

Getting started

Learn the basics of using Grafana.

 @@ -57,7 +57,7 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin",

Configure Grafana

Review the configuration and setup options.

- }}" class="nav-cards__item nav-cards__item--guide"> + }}" class="nav-cards__item nav-cards__item--guide">

Intro to time series

Learn about time series data.

 diff --git a/docs/sources/getting-started/_index.md b/docs/sources/getting-started/_index.md new file mode 100644 index 00000000000..c6018dc7dc0 --- /dev/null +++ b/docs/sources/getting-started/_index.md @@ -0,0 +1,9 @@ ++++ +title = "Getting started" +type = "docs" +[menu.docs] +name = "Getting started" +identifier = "getting-started" +weight = 100 ++++ + diff --git a/docs/sources/guides/getting_started.md b/docs/sources/getting-started/getting-started.md old mode 100755 new mode 100644 similarity index 95% rename from docs/sources/guides/getting_started.md rename to docs/sources/getting-started/getting-started.md index 97c3755281c..a657d9b031d --- a/docs/sources/guides/getting_started.md +++ b/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 diff --git a/docs/sources/guides/glossary.md b/docs/sources/getting-started/glossary.md similarity index 97% rename from docs/sources/guides/glossary.md rename to docs/sources/getting-started/glossary.md index b2a43e09777..f649fc99c24 100644 --- a/docs/sources/guides/glossary.md +++ b/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 diff --git a/docs/sources/getting-started/intro-histograms.md b/docs/sources/getting-started/intro-histograms.md new file mode 100644 index 00000000000..7aaeec1b948 --- /dev/null +++ b/docs/sources/getting-started/intro-histograms.md @@ -0,0 +1,58 @@ ++++ +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. diff --git a/docs/sources/guides/timeseries.md b/docs/sources/getting-started/timeseries.md old mode 100755 new mode 100644 similarity index 99% rename from docs/sources/guides/timeseries.md rename to docs/sources/getting-started/timeseries.md index 7a91d779c95..93bce8fc4a1 --- a/docs/sources/guides/timeseries.md +++ b/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" diff --git a/docs/sources/guides/what-is-grafana.md b/docs/sources/getting-started/what-is-grafana.md similarity index 97% rename from docs/sources/guides/what-is-grafana.md rename to docs/sources/getting-started/what-is-grafana.md index 02f8cc9d1d7..862c1743993 100644 --- a/docs/sources/guides/what-is-grafana.md +++ b/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. diff --git a/docs/sources/installation/_index.md b/docs/sources/installation/_index.md index 606482fea44..27c63f7ec3e 100644 --- a/docs/sources/installation/_index.md +++ b/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 diff --git a/docs/sources/installation/debian.md b/docs/sources/installation/debian.md index f7c4a430fe3..78b21855d63 100644 --- a/docs/sources/installation/debian.md +++ b/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 diff --git a/docs/sources/installation/docker.md b/docs/sources/installation/docker.md index 287df0dceba..d22eba2293f 100755 --- a/docs/sources/installation/docker.md +++ b/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 diff --git a/docs/sources/installation/rpm.md b/docs/sources/installation/rpm.md index 10e4f8cf756..f6a413dce1c 100755 --- a/docs/sources/installation/rpm.md +++ b/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 diff --git a/docs/sources/installation/windows.md b/docs/sources/installation/windows.md index df0865d9bf6..08ea4f6156f 100644 --- a/docs/sources/installation/windows.md +++ b/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. > diff --git a/docs/sources/menu.yaml b/docs/sources/menu.yaml index 20f631e3778..f521d5a746d 100644 --- a/docs/sources/menu.yaml +++ b/docs/sources/menu.yaml @@ -1,14 +1,16 @@ - 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: