From 8c2107cd35ad4846649d783ac76bef2e2607da72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Torkel=20=C3=96degaard?= <torkel@grafana.com>
Date: Fri, 21 Feb 2020 15:23:20 +0100
Subject: [PATCH] Docs: New doc pages for panels Stat, Gauge & Bar Gauge
 (#22335)

* Initial take

* inital gauge docs

* Updated and added bar gauge docs

* Updated based on feedback
---
 docs/sources/features/panels/bar_gauge.md | 60 +++++++++++++++++
 docs/sources/features/panels/gauge.md     | 50 ++++++++++++++
 docs/sources/features/panels/graph.md     | 59 +----------------
 docs/sources/features/panels/stat.md      | 80 +++++++++++++++++++++++
 docs/sources/menu.yaml                    | 26 +++++---
 docs/sources/reference/datalinks.md       | 69 +++++++++++++++++++
 6 files changed, 279 insertions(+), 65 deletions(-)
 create mode 100644 docs/sources/features/panels/bar_gauge.md
 create mode 100644 docs/sources/features/panels/gauge.md
 create mode 100644 docs/sources/features/panels/stat.md
 create mode 100644 docs/sources/reference/datalinks.md

diff --git a/docs/sources/features/panels/bar_gauge.md b/docs/sources/features/panels/bar_gauge.md
new file mode 100644
index 00000000000..edafc4c8884
--- /dev/null
+++ b/docs/sources/features/panels/bar_gauge.md
@@ -0,0 +1,60 @@
++++
+draft = "false"
+date = "2020-02-19"
+title = "Bar gauge panel"
+description = "Bar gauge panel docs"
+keywords = ["grafana", "enter", "keywords", "here"]
+type = "docs"
++++
+
+# Bar gauge panel
+
+{{< docs-imagebox img="/img/docs/v66/bar_gauge_cover.png" max-width="1025px" caption="Stat panel" >}}
+
+This panel can show one or more bar gauges depending on how many series, rows or columns your query returns. The
+thresholds control the bar & value color.
+
+## Display options
+
+* Show
+  * `Calculation` - Show a calculated value like min or max based on all rows.
+  * `All values` - Show a separate stat for every row.
+* Calc
+  * Specify calculation / reducer function. Since this panel is designed to only show a single value Grafana needs to
+    know how to reduce a fields many values to a single value.
+* Orientation
+  * `Horizontal` - The bar will stretch horizontally from left to right.
+  * `Vertical` - The bar will stretch vertically from top to bottom.
+* Mode
+  * `Gradient` - The threshold levels define a gradient.
+  * `Retro LCD` - The gauge is split up in small cells that are lit or unlit.
+  * `Basic` - Single color based on the matching threshold.
+
+Retro LCD example:
+
+{{< docs-imagebox img="/img/docs/v66/bar_gauge_lcd.png" max-width="1025px" caption="Stat panel" >}}
+
+### Field
+
+* `Title` - When multiple stats are shown this field controls the title in each stat. By default this is the series name
+ and field name. You can use expressions like `${__series.name}` or `${__field.name}` to use only series name or field
+ name in title or `${__cell_2}` to refer to other fields (2 being field/column with index 2).
+* `Min` - The minimum value, leave blank for auto calculation based on all series & fields. Used by Graph to set y-axis min.
+* `Max` - The maximum value, leave blank for auto calculation based on all series & fields. Used by Graph to set y-axis max.
+* `Decimals` - Number of decimals to render value with. Leave empty for Grafana to automatically figure out the best
+ number of decimals to use.
+
+### Thresholds
+
+Define thresholds that will set the color of either the value or the background depending on your `Color` display option. The
+thresholds are automatically sorted from lowest value to highest. The `Base` value represents minus infinity.
+
+
+### Value mappings
+
+Map a number or a range of numbers to a text value.
+
+### Data links
+
+Data links allow you add dynamic URL links to your visualizations, [read more on data links]({{< relref "../../reference/datalinks.md" >}}).
+
diff --git a/docs/sources/features/panels/gauge.md b/docs/sources/features/panels/gauge.md
new file mode 100644
index 00000000000..fb1583708cc
--- /dev/null
+++ b/docs/sources/features/panels/gauge.md
@@ -0,0 +1,50 @@
++++
+draft = "false"
+date = "2020-02-19"
+title = "Gauge panel"
+description = "Gauge panel docs"
+keywords = ["grafana", "enter", "keywords", "here"]
+type = "docs"
++++
+
+# Gauge panel
+
+{{< docs-imagebox img="/img/docs/v66/gauge_panel_cover.png" max-width="1025px" caption="Stat panel" >}}
+
+The Gauge is a single value panel that can repeat a gauge for every series, column or row.
+
+## Display options
+
+* Show
+  * `Calculation` - Show a calculated value like min or max based on all rows.
+  * `All values` - Show a separate stat for every row.
+* Calc
+  * Specify calculation / reducer function. Since this panel is designed to only show a single value Grafana needs to
+    know how to reduce a fields many values to a single value.
+** Labels - Controls if thresholds values are shown.
+** Markers - Controls if a thresholds band is shown outside the inner gauge value band.
+
+## Field
+
+* `Title` - When multiple stats are shown this field controls the title in each stat. By default this is the series name
+ and field name. You can use expressions like `${__series.name}` or `${__field.name}` to use only series name or field
+ name in title or `${__cell_2}` to refer to other fields (2 being field/column with index 2).
+* `Min` - The minimum value, leave blank for auto calculation based on all series & fields. Used by Graph to set y-axis min.
+* `Max` - The maximum value, leave blank for auto calculation based on all series & fields. Used by Graph to set y-axis max.
+* `Decimals` - Number of decimals to render value with. Leave empty for Grafana to automatically figure out the best
+ number of decimals to use.
+
+### Thresholds
+
+Define thresholds that will set the color of either the value or the background depending on your `Color` display option. The
+thresholds are automatically sorted from lowerst value to highest. The `Base` value represents minus infinity.
+
+
+### Value mappings
+
+Map a number or a range of numbers to a text value.
+
+### Data links
+
+Data links allow you add dynamic URL links to your visualizations, [read more on data links]({{< relref "../../reference/datalinks.md" >}}).
+
diff --git a/docs/sources/features/panels/graph.md b/docs/sources/features/panels/graph.md
index aadf6faca88..a37929018d8 100755
--- a/docs/sources/features/panels/graph.md
+++ b/docs/sources/features/panels/graph.md
@@ -189,62 +189,9 @@ The time range tab allows you to override the dashboard time range and specify a
 Either through a relative from now time option or through a timeshift.
 Panel time overrides and timeshift are described in more detail [here]({{< relref "../../reference/timerange.md#panel-time-overrides-timeshift" >}}).
 
-### Data link
+### Data links
 
-> Only available in Grafana v6.3+.
+{{< docs-imagebox img="/img/docs/v66/datalinks_graph.png" max-width="1025px" caption="Data links" >}}
 
-Data link allows adding dynamic links to the visualization. Those links can link to either other dashboard or to an external URL.
+Data links allow you add dynamic URL links to your visualizations, [read more on data links]({{< relref "../../reference/datalinks.md" >}}).
 
-{{< docs-imagebox img="/img/docs/data_link.png"  max-width= "800px" >}}
-
-Data link is defined by title, URL and a setting whether or not it should be opened in a new window.
-
-**Title** is a human readable label for the link that will be displayed in the UI. The link itself is accessible in the graph's context menu when user **clicks on a single data point**:
-
-{{< docs-imagebox img="/img/docs/data_link_tooltip.png"  max-width= "800px" >}}
-
-**URL** field allows the URL configuration for a given link. Apart from regular query params it also supports built-in variables and dashboard variables that you can choose from
-available suggestions:
-
-{{< docs-imagebox img="/img/docs/data_link_typeahead.png"  max-width= "800px" >}}
-
-
-#### Built-in variables
-
-> These variables changed in 6.4 so if you have an older version of Grafana please use the version picker to select
-docs for an older version of Grafana.
-
-``__url_time_range`` - current dashboard's time range (i.e. ``?from=now-6h&to=now``)
-``__from`` - current dashboard's time range from value
-``__to`` - current dashboard's time range to value
-
-#### Series variables
-Series specific variables are available under ``__series`` namespace:
-
-``__series.name`` - series name to the URL
-
-``__series.labels.<LABEL>`` - label's value to the URL. If your label contains dots use ``__series.labels["<LABEL>"]`` syntax
-
-#### Field variables
-Field specific variables are available under ``__field`` namespace:
-
-``__field.name`` - field name to the URL
-
-#### Value variables
-Value specific variables are available under ``__value`` namespace:
-
-``__value.time`` - value's timestamp (Unix ms epoch) to the URL (i.e. ``?time=1560268814105``)
-
-``__value.raw`` - raw value
-
-``__value.numeric`` - numeric representation of a value
-
-``__value.text`` - text representation of a value
-
-``__value.calc`` - calculation name if the value is result of calculation
-
-
-#### Template variables
-
-When linking to another dashboard that uses template variables, you can use ``var-myvar=${myvar}`` syntax (where ``myvar`` is a name of template variable)
-to use current dashboard's variable value. If you want to add all of the current dashboard's variables to the URL use  ``__all_variables`` variable.
diff --git a/docs/sources/features/panels/stat.md b/docs/sources/features/panels/stat.md
new file mode 100644
index 00000000000..7f3da35dec9
--- /dev/null
+++ b/docs/sources/features/panels/stat.md
@@ -0,0 +1,80 @@
++++
+draft = "false"
+date = "2020-02-19"
+title = "Stat panel"
+description = "Stat panel documentation"
+keywords = ["grafana", "docs", "stat panel"]
+type = "docs"
++++
+
+# Stat panel
+
+{{< docs-imagebox img="/img/docs/v66/stat_panel_dark3.png" max-width="1025px" caption="Stat panel" >}}
+
+The stat panel is designed to show a big single stat values with an optional graph sparkline. You can control
+background or value color using thresholds.
+
+## Display options
+
+* Show
+  * `Calculation` - Show a calculated value like min or max based on all rows.
+  * `All values` - Show a separate stat for every row.
+* Calc
+  * Specify calculation / reducer function. Since this panel is designed to only show a single value Grafana needs to
+    know how to reduce a fields many values to a single value.
+* Orientation
+  * If your query returns multiple series or you have set **Show** to `All values` then the visualization
+    will repeat for every series or row. This orientation option will control in what direction it will repeat.
+** Color
+  * `Value` - Color the value and graph area only.
+  * `Background` - Color the background.
+** Graph
+  * `None` - Disable the graph / sparkline
+  * `Area graph` - Show area graph below value. This requires that your query returns a time column.
+** Justify
+  * `Auto` - If only a single value is shown (no repeat) the value is centered. If multiple series or rows the value is
+  * left aligned.
+  * `Center` - Force center alignment.
+
+
+### Auto layout
+
+The panel will try to auto adjust layout depending on width & height. The graph will also hide if the panel becomes
+to small.
+
+Example of stacked layout where graph is automatically hidden due to each stat being too small:
+
+{{< docs-imagebox img="/img/docs/v66/stat_panel_stacked.png" max-width="405px" caption="Stat panel" >}}
+
+### Color mode
+
+Example of value color mode:
+
+{{< docs-imagebox img="/img/docs/v66/stat_panel_dark4.png" max-width="900px" caption="Stat panel" >}}
+
+### Field
+
+* `Title` - When multiple stats are shown this field controls the title in each stat. By default this is the series name
+ and field name. You can use expressions like `${__series.name}` or `${__field.name}` to use only series name or field
+ name in title or `${__cell_2}` to refer to other fields (2 being field/column with index 2).
+* `Min` - The minimum value, leave blank for auto calculation based on all series & fields. Used by graph/sparkline
+* (when enabled) to set y-axis min.
+* `Max` - The maximum value, leave blank for auto calculation based on all series & fields. Used by graph/sparkline
+* (when enabled) to set y-axis max.
+* `Decimals` - Number of decimals to render value with. Leave empty for Grafana to automatically figure out the best
+ number of decimals to use.
+
+### Thresholds
+
+Define thresholds that will set the color of either the value or the background depending on your `Color` display option. The
+thresholds are automatically sorted from lowerst value to highest. The `Base` value represents minus infinity.
+
+
+### Value mappings
+
+Map a number or a range of numbers to a text value.
+
+### Data links
+
+Data links allow you add dynamic URL links to your visualizations, [read more on data links]({{< relref "../../reference/datalinks.md" >}}).
+
diff --git a/docs/sources/menu.yaml b/docs/sources/menu.yaml
index e79de52b664..6e846766110 100644
--- a/docs/sources/menu.yaml
+++ b/docs/sources/menu.yaml
@@ -87,12 +87,18 @@
       name: Overview
     - link: /features/panels/graph/
       name: Graph
+    - link: /features/panels/table_panel/
+      name: Table
+    - link: /features/panels/stat/
+      name: Stat
+    - link: /features/panels/gauge/
+      name: Gauge
+    - link: /features/panels/bar_gauge/
+      name: Bar gauge
     - link: /features/panels/logs/
       name: Logs
     - link: /features/panels/singlestat/
       name: Singlestat
-    - link: /features/panels/table_panel/
-      name: Table
     - link: /features/panels/heatmap/
       name: Heatmap
     - link: /features/panels/alertlist/
@@ -117,19 +123,21 @@
     - link: /reference/search/
       name: Search
     - link: /reference/share_dashboard/
-      name: Sharing a Dashboard
+      name: Sharing a dashboard
     - link: /reference/share_panel/
-      name: Sharing a Panel
+      name: Sharing a panel
     - link: /reference/timerange/
-      name: Time Range
+      name: Time range
     - link: /reference/export_import/
-      name: Export and Import
-    - link: /reference/scripting/
-      name: Scripted Dashboards
+      name: Export and import
+    - link: /reference/datalinks/
+      name: Data links
     - link: /reference/dashboard_history/
-      name: Dashboard Version History
+      name: Dashboard version history
     - link: /reference/dashboard/
       name: JSON Model
+    - link: /reference/scripting/
+      name: Scripted dashboards
   - name: Data Sources
     link: /features/datasources/
     children:
diff --git a/docs/sources/reference/datalinks.md b/docs/sources/reference/datalinks.md
new file mode 100644
index 00000000000..dc97727e4cb
--- /dev/null
+++ b/docs/sources/reference/datalinks.md
@@ -0,0 +1,69 @@
++++
+title = "Data links"
+keywords = ["grafana", "data links", "documentation", "playlist"]
+type = "docs"
++++
+
+# Data links
+
+{{< docs-imagebox img="/img/docs/v66/datalinks_graph.png" max-width="1025px" caption="Data links" >}}
+
+Data link allows adding dynamic links to the visualization. Those links can link to either another dashboard or to an external URL.
+
+{{< docs-imagebox img="/img/docs/v66/datalinks.png" max-width="1025px" caption="Data links" >}}
+
+Data link is defined by title, URL and a setting whether or not it should be opened in a new window.
+
+* **Title** is a human readable label for the link that will be displayed in the UI.
+* **URL** field allows the URL configuration for a given link. Apart from regular query params it also supports built-in variables and dashboard variables that you can choose from
+available suggestions:
+
+The link itself is accessible in different ways depending on the visualization. For the graph you need to click on a data point or line, for a panel like
+Stat, Gauge or Bar Gauge you can click anywhere on the visualization to open the context menu.
+
+Example with Bar Gauge panel
+{{< docs-imagebox img="/img/docs/v66/datalinks_cover.png" max-width="1025px" caption="Data links" >}}
+
+## Variables to use in your URL
+
+> These variables changed in 6.4 so if you have an older version of Grafana please use the version picker to select
+docs for an older version of Grafana.
+
+* ``__url_time_range`` - current dashboard's time range (i.e. ``?from=now-6h&to=now``)
+* ``__from`` - current dashboard's time range from value
+* ``__to`` - current dashboard's time range to value
+
+### Series variables
+
+Series specific variables are available under ``__series`` namespace:
+
+* ``__series.name`` - series name to the URL
+* ``__series.labels.<LABEL>`` - label's value to the URL. If your label contains dots use ``__series.labels["<LABEL>"]`` syntax
+
+### Field variables
+
+Field specific variables are available under ``__field`` namespace:
+
+* ``__field.name`` - field name to the URL
+
+### Value variables
+Value specific variables are available under ``__value`` namespace:
+
+* ``__value.time`` - value's timestamp (Unix ms epoch) to the URL (i.e. ``?time=1560268814105``)
+* ``__value.raw`` - raw value
+* ``__value.numeric`` - numeric representation of a value
+* ``__value.text`` - text representation of a value
+* ``__value.calc`` - calculation name if the value is result of calculation
+
+### Template variables
+
+When linking to another dashboard that uses template variables, you can use ``var-myvar=${myvar}`` syntax (where ``myvar`` is a name of template variable)
+to use current dashboard's variable value. If you want to add all of the current dashboard's variables to the URL use  ``__all_variables`` variable.
+
+## Typeahead suggestions
+
+Hit CMD or CTRL space on your keyboard to open the typeahead suggestions to more easily add variables to your URL.
+
+{{< docs-imagebox img="/img/docs/data_link_typeahead.png"  max-width= "800px" >}}
+
+