From 3a8db4bffd0d3e2c1308592861d7e091d133d636 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Wed, 1 Sep 2021 17:38:52 +0200 Subject: [PATCH 1/7] Docs: Improve v8 upgrade notes for SQL data sources --- docs/sources/datasources/mssql.md | 2 ++ docs/sources/datasources/mysql.md | 6 ++++-- docs/sources/datasources/postgres.md | 6 ++++-- docs/sources/installation/upgrading.md | 24 ++++++++++++++++++++++-- 4 files changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/sources/datasources/mssql.md b/docs/sources/datasources/mssql.md index 542446f67c05..ca23c154b214 100644 --- a/docs/sources/datasources/mssql.md +++ b/docs/sources/datasources/mssql.md @@ -171,6 +171,8 @@ The resulting table panel: If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must have a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. You may return a column named `metric` that is used as metric name for the value column. Any column except `time` and `metric` is treated as a value column. If you omit the `metric` column, the name of the value column will be the metric name. You may select multiple value columns, each will have its name as metric. If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+). +If you're not satisfied with the default series name formatting, please use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to customize it. + Result sets of time series queries need to be sorted by time. **Example database table:** diff --git a/docs/sources/datasources/mysql.md b/docs/sources/datasources/mysql.md index 0a1736fd6bdb..dd9a254f6a4c 100644 --- a/docs/sources/datasources/mysql.md +++ b/docs/sources/datasources/mysql.md @@ -185,6 +185,8 @@ Any column except `time` and `metric` is treated as a value column. You may return a column named `metric` that is used as metric name for the value column. If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+). +If you're not satisfied with the default series name formatting, please use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to customize it. + Resultsets of time series queries need to be sorted by time. **Example with `metric` column:** @@ -206,11 +208,11 @@ ORDER BY time SELECT $__timeGroup(createdAt,'5m',0), sum(value_double) as value, - measurement + measurement as metric FROM test_data WHERE $__timeFilter(createdAt) -GROUP BY time, measurement +GROUP BY time, metric ORDER BY time ``` diff --git a/docs/sources/datasources/postgres.md b/docs/sources/datasources/postgres.md index 4726676b89ab..5d729b82fdaf 100644 --- a/docs/sources/datasources/postgres.md +++ b/docs/sources/datasources/postgres.md @@ -190,6 +190,8 @@ Any column except `time` and `metric` are treated as a value column. You may return a column named `metric` that is used as metric name for the value column. If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+). +If you're not satisfied with the default series name formatting, please use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to customize it. + Resultsets of time series queries need to be sorted by time. **Example with `metric` column:** @@ -211,11 +213,11 @@ ORDER BY time SELECT $__timeGroup("createdAt",'5m',0), sum(value) as value, - measurement + measurement as metric FROM test_data WHERE $__timeFilter("createdAt") -GROUP BY time, measurement +GROUP BY time, metric ORDER BY time ``` diff --git a/docs/sources/installation/upgrading.md b/docs/sources/installation/upgrading.md index 096f736a03d6..7bddb9a3711a 100755 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -347,12 +347,32 @@ Grafana v8.0 changes the underlying data structure to [data frames]({{< relref " For any existing panels/visualizations using a _Time series_ query, where the time column is only needed for filtering the time range, for example, using the bar gauge or pie chart panel, we recommend that you use a _Table query_ instead and exclude the time column as a field in the response. Refer to this [issue comment](https://github.com/grafana/grafana/issues/35534#issuecomment-861519658) for detailed instructions and workarounds. +#### Prefix added to legend/alias + +Given you have a query similar to below, where there's a time value and a numeric value selected together with a string value that's not named `metric`. Then you might notice that the graph panel renders series legends/aliases as `value ` rather than just `` which was the case before Grafana 8. + +```sql +SELECT + $__timeGroup("createdAt",'10m'), + avg(value) as "value", + hostname +FROM grafana_metric +WHERE $__timeFilter("createdAt") +GROUP BY time, hostname +ORDER BY time +``` + +There's two possible workarounds to resolve this problem: + +1. Starting from Grafana v8.0.3 you should alias the string column selected as `metric`, i.e. `hostname as metric`. +2. Use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to format the alias. Given example query above you would use `${__field.labels.hostname}`. + ## Upgrading to v8.1 ### Use of unencrypted passwords for data sources no longer supported As of Grafana v8.1, we no longer support unencrypted storage of passwords and basic auth passwords. ->**Note":** Since Grafana v6.2, new or updated data sources store passwords and basic auth passwords encrypted. See [upgrade note]({{< relref "#ensure-encryption-of-data-source-secrets" >}}) for more information. However, unencrypted passwords and basic auth passwords were also allowed. - +> **Note":** Since Grafana v6.2, new or updated data sources store passwords and basic auth passwords encrypted. See [upgrade note]({{< relref "#ensure-encryption-of-data-source-secrets" >}}) for more information. However, unencrypted passwords and basic auth passwords were also allowed. + To migrate to encrypted storage, follow the instructions from the [v6.2 upgrade notes]({{< relref "#ensure-encryption-of-data-source-secrets" >}}). You can also use a `grafana-cli` command to migrate all of your data sources to use encrypted storage of secrets. See [migrate data and encrypt passwords]({{< relref "../administration/cli.md#migrate-data-and-encrypt-passwords" >}}) for further instructions. From 9b4c71fbffab331dac52860dddade553f237d5f0 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 2 Sep 2021 10:35:21 +0200 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/datasources/mssql.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/sources/datasources/mssql.md b/docs/sources/datasources/mssql.md index ca23c154b214..1d2599b98135 100644 --- a/docs/sources/datasources/mssql.md +++ b/docs/sources/datasources/mssql.md @@ -168,10 +168,9 @@ The resulting table panel: ## Time series queries -If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must have a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. You may return a column named `metric` that is used as metric name for the value column. Any column except `time` and `metric` is treated as a value column. If you omit the `metric` column, the name of the value column will be the metric name. You may select multiple value columns, each will have its name as metric. -If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+). +If you set Format as to Time series, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. You can additionally return a column named metric that represents the metric type for the value column, for example, seconds. Any column except time and metric is treated as a value column. If you omit the metric column, then the title of the value column is treated as its metric type. When you select multiple value columns without a column named metric, then each column's title is treated as its metric type. -If you're not satisfied with the default series name formatting, please use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to customize it. +If you return multiple value columns and a column named metric, then the metric column is used as a prefix for the series name. You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). Result sets of time series queries need to be sorted by time. From af1e2fdc557898ffa7bcaad39051d03fa86714ba Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 2 Sep 2021 12:45:29 +0200 Subject: [PATCH 3/7] Trying to improve mysql docs --- docs/sources/datasources/mysql.md | 54 ++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/docs/sources/datasources/mysql.md b/docs/sources/datasources/mysql.md index dd9a254f6a4c..91e7d540e49b 100644 --- a/docs/sources/datasources/mysql.md +++ b/docs/sources/datasources/mysql.md @@ -180,14 +180,13 @@ The resulting table panel: ## Time series queries -If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must return a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch. -Any column except `time` and `metric` is treated as a value column. -You may return a column named `metric` that is used as metric name for the value column. -If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+). +If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result. -If you're not satisfied with the default series name formatting, please use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to customize it. +A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result. -Resultsets of time series queries need to be sorted by time. +> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. + +You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). **Example with `metric` column:** @@ -202,20 +201,46 @@ GROUP BY time ORDER BY time ``` +Data frame result: + +```text ++---------------------+-----------------+ +| Name: time | Name: min | +| Labels: | Labels: | +| Type: []time.Time | Type: []float64 | ++---------------------+-----------------+ +| 2020-01-02 03:05:00 | 3 | +| 2020-01-02 03:10:00 | 6 | ++---------------------+-----------------+ +``` + **Example using the fill parameter in the $\_\_timeGroup macro to convert null values to be zero instead:** ```sql SELECT $__timeGroup(createdAt,'5m',0), sum(value_double) as value, - measurement as metric + hostname FROM test_data WHERE $__timeFilter(createdAt) -GROUP BY time, metric +GROUP BY time, hostname ORDER BY time ``` +Data frame result: + +```text ++---------------------+---------------------------+---------------------------+ +| Name: time | Name: value | Name: value | +| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 | +| Type: []time.Time | Type: []float64 | Type: []float64 | ++---------------------+---------------------------+---------------------------+ +| 2020-01-02 03:05:00 | 3 | 4 | +| 2020-01-02 03:10:00 | 6 | 7 | ++---------------------+---------------------------+---------------------------+ +``` + **Example with multiple columns:** ```sql @@ -229,6 +254,19 @@ GROUP BY time ORDER BY time ``` +Data frame result: + +```text ++---------------------+-----------------+-----------------+ +| Name: time | Name: min_value | Name: max_value | +| Labels: | Labels: | Labels: | +| Type: []time.Time | Type: []float64 | Type: []float64 | ++---------------------+-----------------+-----------------+ +| 2020-01-02 03:04:00 | 3 | 4 | +| 2020-01-02 03:05:00 | 6 | 7 | ++---------------------+-----------------+-----------------+ +``` + Currently, there is no support for a dynamic group by time based on time range and panel width. This is something we plan to add. From 2f86ad4cba4e147f9c20a387ea080b0a555529cb Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 10 Sep 2021 10:37:20 +0200 Subject: [PATCH 4/7] Updates --- docs/sources/datasources/mssql.md | 149 ++++++++++--------------- docs/sources/datasources/mysql.md | 2 + docs/sources/datasources/postgres.md | 56 ++++++++-- docs/sources/installation/upgrading.md | 6 +- 4 files changed, 115 insertions(+), 98 deletions(-) diff --git a/docs/sources/datasources/mssql.md b/docs/sources/datasources/mssql.md index 1d2599b98135..11966bb3551a 100644 --- a/docs/sources/datasources/mssql.md +++ b/docs/sources/datasources/mssql.md @@ -168,123 +168,96 @@ The resulting table panel: ## Time series queries -If you set Format as to Time series, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. You can additionally return a column named metric that represents the metric type for the value column, for example, seconds. Any column except time and metric is treated as a value column. If you omit the metric column, then the title of the value column is treated as its metric type. When you select multiple value columns without a column named metric, then each column's title is treated as its metric type. +If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result. -If you return multiple value columns and a column named metric, then the metric column is used as a prefix for the series name. You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). +A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result. -Result sets of time series queries need to be sorted by time. +> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. -**Example database table:** - -```sql -CREATE TABLE [event] ( - time_sec bigint, - description nvarchar(100), - tags nvarchar(100), -) -``` - -```sql -CREATE TABLE metric_values ( - time datetime, - measurement nvarchar(100), - valueOne int, - valueTwo int, -) - -INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric A', 62, 6) -INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric B', 49, 11) -... -INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric A', 14, 25) -INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric B', 48, 10) +You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). -``` - -{{< figure src="/static/img/docs/v51/mssql_time_series_one.png" class="docs-image--no-shadow docs-image--right" >}} - -**Example with one `value` and one `metric` column.** +**Example with `metric` column:** ```sql SELECT - time, - valueOne, - measurement as metric -FROM - metric_values -WHERE - $__timeFilter(time) + $__timeGroup(time_date_time, '5m') as time, + min("value_double"), + 'min' as metric +FROM test_data +WHERE $__timeFilter(time_date_time) +GROUP BY $__timeGroup(time_date_time, '5m') ORDER BY 1 ``` -When the above query is used in a graph panel, it will produce two series named `Metric A` and `Metric B` with the values `valueOne` and `valueTwo` plotted over `time`. - -
- -{{< figure src="/static/img/docs/v51/mssql_time_series_two.png" class="docs-image--no-shadow docs-image--right" >}} - -**Example with multiple `value` columns:** - -```sql -SELECT - time, - valueOne, - valueTwo -FROM - metric_values -WHERE - $__timeFilter(time) -ORDER BY 1 +Data frame result: + +```text ++---------------------+-----------------+ +| Name: time | Name: min | +| Labels: | Labels: | +| Type: []time.Time | Type: []float64 | ++---------------------+-----------------+ +| 2020-01-02 03:05:00 | 3 | +| 2020-01-02 03:10:00 | 6 | ++---------------------+-----------------+ ``` -When the above query is used in a graph panel, it will produce two series named `Metric A` and `Metric B` with the values `valueOne` and `valueTwo` plotted over `time`. - -
- -{{< figure src="/static/img/docs/v51/mssql_time_series_three.png" class="docs-image--no-shadow docs-image--right" >}} - -**Example using the \$\_\_timeGroup macro:** +**Example using the fill parameter in the $\_\_timeGroup macro to convert null values to be zero instead:** ```sql SELECT - $__timeGroup(time, '3m') as time, - measurement as metric, - avg(valueOne) -FROM - metric_values + $__timeGroup(createdAt, '5m', 0) as time, + sum(value) as value, + hostname +FROM test_data WHERE - $__timeFilter(time) + $__timeFilter(createdAt) GROUP BY - $__timeGroup(time, '3m'), - measurement + $__timeGroup(createdAt, '5m', 0), + hostname ORDER BY 1 ``` -When the above query is used in a graph panel, it will produce two series named `Metric A` and `Metric B` with the values `valueOne` and `valueTwo` plotted over `time`. -Any two series lacking a value in a three-minute window will render a line between those two lines. You'll notice that the graph to the right never goes down to zero. +Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. -
+Data frame result: -{{< figure src="/static/img/docs/v51/mssql_time_series_four.png" class="docs-image--no-shadow docs-image--right" >}} +```text ++---------------------+---------------------------+---------------------------+ +| Name: time | Name: value | Name: value | +| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 | +| Type: []time.Time | Type: []float64 | Type: []float64 | ++---------------------+---------------------------+---------------------------+ +| 2020-01-02 03:05:00 | 3 | 4 | +| 2020-01-02 03:10:00 | 6 | 7 | ++---------------------+---------------------------+---------------------------+ +``` -**Example using the \$\_\_timeGroup macro with fill parameter set to zero:** +**Example with multiple columns:** ```sql SELECT - $__timeGroup(time, '3m', 0) as time, - measurement as metric, - sum(valueTwo) -FROM - metric_values -WHERE - $__timeFilter(time) -GROUP BY - $__timeGroup(time, '3m'), - measurement + $__timeGroup(time_date_time, '5m'), + min(value_double) as min_value, + max(value_double) as max_value +FROM test_data +WHERE $__timeFilter(time_date_time) +GROUP BY $__timeGroup(time_date_time, '5m') ORDER BY 1 ``` -When the above query is used in a graph panel, the result is two series named `Metric A` and `Metric B` with a sum of `valueTwo` plotted over `time`. -Any series lacking a value in a 3 minute window will have a value of zero which you'll see rendered in the graph to the right. +Data frame result: + +```text ++---------------------+-----------------+-----------------+ +| Name: time | Name: min_value | Name: max_value | +| Labels: | Labels: | Labels: | +| Type: []time.Time | Type: []float64 | Type: []float64 | ++---------------------+-----------------+-----------------+ +| 2020-01-02 03:04:00 | 3 | 4 | +| 2020-01-02 03:05:00 | 6 | 7 | ++---------------------+-----------------+-----------------+ +``` ## Templating diff --git a/docs/sources/datasources/mysql.md b/docs/sources/datasources/mysql.md index 91e7d540e49b..aa021c6f99d8 100644 --- a/docs/sources/datasources/mysql.md +++ b/docs/sources/datasources/mysql.md @@ -228,6 +228,8 @@ GROUP BY time, hostname ORDER BY time ``` +Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. + Data frame result: ```text diff --git a/docs/sources/datasources/postgres.md b/docs/sources/datasources/postgres.md index 5d729b82fdaf..8e1d54b9bde5 100644 --- a/docs/sources/datasources/postgres.md +++ b/docs/sources/datasources/postgres.md @@ -185,14 +185,13 @@ The resulting table panel: ## Time series queries -If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must return a column named `time` that returns either a SQL datetime or any numeric datatype representing Unix epoch. -Any column except `time` and `metric` are treated as a value column. -You may return a column named `metric` that is used as metric name for the value column. -If you return multiple value columns and a column named `metric` then this column is used as prefix for the series name (only available in Grafana 5.3+). +If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result. -If you're not satisfied with the default series name formatting, please use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to customize it. +A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result. -Resultsets of time series queries need to be sorted by time. +> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. + +You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). **Example with `metric` column:** @@ -207,20 +206,48 @@ GROUP BY time ORDER BY time ``` +Data frame result: + +```text ++---------------------+-----------------+ +| Name: time | Name: min | +| Labels: | Labels: | +| Type: []time.Time | Type: []float64 | ++---------------------+-----------------+ +| 2020-01-02 03:05:00 | 3 | +| 2020-01-02 03:10:00 | 6 | ++---------------------+-----------------+ +``` + **Example using the fill parameter in the $\_\_timeGroup macro to convert null values to be zero instead:** ```sql SELECT $__timeGroup("createdAt",'5m',0), sum(value) as value, - measurement as metric + hostname FROM test_data WHERE $__timeFilter("createdAt") -GROUP BY time, metric +GROUP BY time, hostname ORDER BY time ``` +Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. + +Data frame result: + +```text ++---------------------+---------------------------+---------------------------+ +| Name: time | Name: value | Name: value | +| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 | +| Type: []time.Time | Type: []float64 | Type: []float64 | ++---------------------+---------------------------+---------------------------+ +| 2020-01-02 03:05:00 | 3 | 4 | +| 2020-01-02 03:10:00 | 6 | 7 | ++---------------------+---------------------------+---------------------------+ +``` + **Example with multiple columns:** ```sql @@ -234,6 +261,19 @@ GROUP BY time ORDER BY time ``` +Data frame result: + +```text ++---------------------+-----------------+-----------------+ +| Name: time | Name: min_value | Name: max_value | +| Labels: | Labels: | Labels: | +| Type: []time.Time | Type: []float64 | Type: []float64 | ++---------------------+-----------------+-----------------+ +| 2020-01-02 03:04:00 | 3 | 4 | +| 2020-01-02 03:05:00 | 6 | 7 | ++---------------------+-----------------+-----------------+ +``` + ## Templating Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard. diff --git a/docs/sources/installation/upgrading.md b/docs/sources/installation/upgrading.md index 7bddb9a3711a..12414ec18f22 100755 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -347,9 +347,9 @@ Grafana v8.0 changes the underlying data structure to [data frames]({{< relref " For any existing panels/visualizations using a _Time series_ query, where the time column is only needed for filtering the time range, for example, using the bar gauge or pie chart panel, we recommend that you use a _Table query_ instead and exclude the time column as a field in the response. Refer to this [issue comment](https://github.com/grafana/grafana/issues/35534#issuecomment-861519658) for detailed instructions and workarounds. -#### Prefix added to legend/alias +#### Prefix added to series names -Given you have a query similar to below, where there's a time value and a numeric value selected together with a string value that's not named `metric`. Then you might notice that the graph panel renders series legends/aliases as `value ` rather than just `` which was the case before Grafana 8. +Given you have a query similar to below, where there's a time value and a numeric value selected together with a string value that's not named _metric_. Then you might notice that the graph panel renders series names as `value ` rather than just `` which was the case before Grafana 8. ```sql SELECT @@ -367,6 +367,8 @@ There's two possible workarounds to resolve this problem: 1. Starting from Grafana v8.0.3 you should alias the string column selected as `metric`, i.e. `hostname as metric`. 2. Use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to format the alias. Given example query above you would use `${__field.labels.hostname}`. +For more information please refer to the documentation of [Postgres]({{< relref "../datasources/postgres.md#time-series-queries" >}}), [MySQL]({{< relref "../datasources/mysql.md#time-series-queries" >}}), [Microsoft SQL Server]({{< relref "../datasources/mssql.md#time-series-queries" >}}). + ## Upgrading to v8.1 ### Use of unencrypted passwords for data sources no longer supported From f28bae48b058137f41fff3d7ff4e5bd0044024b2 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 10 Sep 2021 16:59:58 +0200 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> --- docs/sources/datasources/mssql.md | 8 ++++---- docs/sources/datasources/mysql.md | 8 ++++---- docs/sources/datasources/postgres.md | 6 +++--- docs/sources/installation/upgrading.md | 12 ++++++------ 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/sources/datasources/mssql.md b/docs/sources/datasources/mssql.md index 11966bb3551a..c17da7d81ce8 100644 --- a/docs/sources/datasources/mssql.md +++ b/docs/sources/datasources/mssql.md @@ -168,11 +168,11 @@ The resulting table panel: ## Time series queries -If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result. +If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result. -A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result. +A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result. -> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. +> For backward compatibility, there's an exception to the above rule for queries that return three columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below. You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). @@ -218,7 +218,7 @@ GROUP BY ORDER BY 1 ``` -Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. +Given the data frame result in the following example and using the graph panel, you will get two series named _value 10.0.1.1_ and _value 10.0.1.2_. To render the series with a name of _10.0.1.1_ and _10.0.1.2_ , use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. Data frame result: diff --git a/docs/sources/datasources/mysql.md b/docs/sources/datasources/mysql.md index aa021c6f99d8..fb3398d73959 100644 --- a/docs/sources/datasources/mysql.md +++ b/docs/sources/datasources/mysql.md @@ -180,11 +180,11 @@ The resulting table panel: ## Time series queries -If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result. +If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result. -A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result. +A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result. -> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. +> For backward compatibility, there's an exception to the above rule for queries that return three columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below. You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). @@ -228,7 +228,7 @@ GROUP BY time, hostname ORDER BY time ``` -Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. +Given the data frame result in the following example and using the graph panel, you will get two series named _value 10.0.1.1_ and _value 10.0.1.2_. To render the series with a name of _10.0.1.1_ and _10.0.1.2_ , use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. Data frame result: diff --git a/docs/sources/datasources/postgres.md b/docs/sources/datasources/postgres.md index 8e1d54b9bde5..bfc90c0b6e47 100644 --- a/docs/sources/datasources/postgres.md +++ b/docs/sources/datasources/postgres.md @@ -185,9 +185,9 @@ The resulting table panel: ## Time series queries -If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, resultsets of time series queries must be sorted by time for panels to properly visualize the result. +If you set Format as to _Time series_, then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result. -A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time and those of type string is transformed to value fields in the data frame query result. Any string column is transformed into field labels in the data frame query result. +A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result. > **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. @@ -233,7 +233,7 @@ GROUP BY time, hostname ORDER BY time ``` -Given the data frame result below and using the graph panel you'll get 2 series named _value 10.0.1.1_ and _value 10.0.1.2_ given the name of the field and its labels. If you would like to render the series with a name of _10.0.1.1_ and _10.0.1.2_ you could use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. +Given the data frame result in the following example and using the graph panel, you will get two series named _value 10.0.1.1_ and _value 10.0.1.2_. To render the series with a name of _10.0.1.1_ and _10.0.1.2_ , use a [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) value of `${__field.labels.hostname}`. Data frame result: diff --git a/docs/sources/installation/upgrading.md b/docs/sources/installation/upgrading.md index 12414ec18f22..b660f043ebd5 100755 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -349,7 +349,7 @@ Refer to this [issue comment](https://github.com/grafana/grafana/issues/35534#is #### Prefix added to series names -Given you have a query similar to below, where there's a time value and a numeric value selected together with a string value that's not named _metric_. Then you might notice that the graph panel renders series names as `value ` rather than just `` which was the case before Grafana 8. +When you have a query where there's a time value and a numeric value selected together with a string value that's not named _metric_, the graph panel renders series names as `value ` rather than just `` which was the case before Grafana 8. ```sql SELECT @@ -362,12 +362,12 @@ GROUP BY time, hostname ORDER BY time ``` -There's two possible workarounds to resolve this problem: +There are two possible workarounds to resolve this problem: -1. Starting from Grafana v8.0.3 you should alias the string column selected as `metric`, i.e. `hostname as metric`. -2. Use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to format the alias. Given example query above you would use `${__field.labels.hostname}`. +1. In Grafana v8.0.3, use an alias of the string column selected as `metric`. for example, `hostname as metric`. +2. Use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to format the alias. For the preceeding example query, you would use `${__field.labels.hostname}` option. -For more information please refer to the documentation of [Postgres]({{< relref "../datasources/postgres.md#time-series-queries" >}}), [MySQL]({{< relref "../datasources/mysql.md#time-series-queries" >}}), [Microsoft SQL Server]({{< relref "../datasources/mssql.md#time-series-queries" >}}). +For more information, refer to the our relational databases documentation of [Postgres]({{< relref "../datasources/postgres.md#time-series-queries" >}}), [MySQL]({{< relref "../datasources/mysql.md#time-series-queries" >}}), [Microsoft SQL Server]({{< relref "../datasources/mssql.md#time-series-queries" >}}). ## Upgrading to v8.1 @@ -375,6 +375,6 @@ For more information please refer to the documentation of [Postgres]({{< relref As of Grafana v8.1, we no longer support unencrypted storage of passwords and basic auth passwords. -> **Note":** Since Grafana v6.2, new or updated data sources store passwords and basic auth passwords encrypted. See [upgrade note]({{< relref "#ensure-encryption-of-data-source-secrets" >}}) for more information. However, unencrypted passwords and basic auth passwords were also allowed. +> **Note":** In Grafana v6.2.x stored passwords of new or updated data sources and basic auth passwords encrypted. See [upgrade note]({{< relref "#ensure-encryption-of-data-source-secrets" >}}) for more information. However, unencrypted passwords and basic auth passwords were also allowed. To migrate to encrypted storage, follow the instructions from the [v6.2 upgrade notes]({{< relref "#ensure-encryption-of-data-source-secrets" >}}). You can also use a `grafana-cli` command to migrate all of your data sources to use encrypted storage of secrets. See [migrate data and encrypt passwords]({{< relref "../administration/cli.md#migrate-data-and-encrypt-passwords" >}}) for further instructions. From 667b05a547779aee0963cb8b1392413bd8d71910 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 10 Sep 2021 17:00:24 +0200 Subject: [PATCH 6/7] Apply suggestions from code review --- docs/sources/datasources/postgres.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/datasources/postgres.md b/docs/sources/datasources/postgres.md index bfc90c0b6e47..3800cc33d962 100644 --- a/docs/sources/datasources/postgres.md +++ b/docs/sources/datasources/postgres.md @@ -189,7 +189,7 @@ If you set Format as to _Time series_, then the query must have a column named t A time series query result is returned in a [wide data frame format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result. -> **Note:** For pre-v8 backward-compatibility there's an exception to the above rule when a query returns 3 columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, which makes the series name be formatted as the value of the metric column. See example with metric column below. +> For backward compatibility, there's an exception to the above rule for queries that return three columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below. You can optionally customize the default series name formatting using instructions in [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}). From 4baeef483dee1a0e8146e0879833af380542ac32 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 10 Sep 2021 17:11:30 +0200 Subject: [PATCH 7/7] Fix spelling --- docs/sources/installation/upgrading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/installation/upgrading.md b/docs/sources/installation/upgrading.md index 2fcf9d92a089..7c37551472d0 100755 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -365,7 +365,7 @@ ORDER BY time There are two possible workarounds to resolve this problem: 1. In Grafana v8.0.3, use an alias of the string column selected as `metric`. for example, `hostname as metric`. -2. Use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to format the alias. For the preceeding example query, you would use `${__field.labels.hostname}` option. +2. Use the [Standard field options/Display name]({{< relref "../panels/standard-options.md#display-name" >}}) to format the alias. For the preceding example query, you would use `${__field.labels.hostname}` option. For more information, refer to the our relational databases documentation of [Postgres]({{< relref "../datasources/postgres.md#time-series-queries" >}}), [MySQL]({{< relref "../datasources/mysql.md#time-series-queries" >}}), [Microsoft SQL Server]({{< relref "../datasources/mssql.md#time-series-queries" >}}).