diff --git a/docs/sources/auth/overview.md b/docs/sources/auth/overview.md index 0d8f1d4f5f12..02c7a095478b 100644 --- a/docs/sources/auth/overview.md +++ b/docs/sources/auth/overview.md @@ -123,8 +123,8 @@ oauth_auto_login = true ### Avoid automatic OAuth login -To sign in with a username and password and avoid automatic OAuth login, add the `disableAutoLogin` parameter to your login URL. -For example: `grafana.example.com/login?disableAutoLogin` or `grafana.example.com/login?disableAutoLogin=true` +To sign in with a username and password and avoid automatic OAuth login, add the `disableAutoLogin` parameter to your login URL. +For example: `grafana.example.com/login?disableAutoLogin` or `grafana.example.com/login?disableAutoLogin=true` ### Hide sign-out menu diff --git a/docs/sources/datasources/mssql.md b/docs/sources/datasources/mssql.md index 542446f67c05..c17da7d81ce8 100644 --- a/docs/sources/datasources/mssql.md +++ b/docs/sources/datasources/mssql.md @@ -168,122 +168,96 @@ 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. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result. -Result sets of time series queries need to be sorted by time. +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. -**Example database table:** +> 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. -```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 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: -{{< 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 3c54c231f8f5..4f9a70610f4f 100644 --- a/docs/sources/datasources/mysql.md +++ b/docs/sources/datasources/mysql.md @@ -177,12 +177,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, result sets of time series queries must be sorted by time for panels to properly visualize the result. -Resultsets of time series queries need to be sorted by time. +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. + +> 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" >}}). **Example with `metric` column:** @@ -197,20 +198,48 @@ GROUP BY time ORDER BY time ``` -**Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:** +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 + hostname FROM test_data WHERE $__timeFilter(createdAt) -GROUP BY time, measurement +GROUP BY time, hostname ORDER BY time ``` +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: + +```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 @@ -224,6 +253,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. diff --git a/docs/sources/datasources/postgres.md b/docs/sources/datasources/postgres.md index 3088151d0ef7..808359774d9e 100644 --- a/docs/sources/datasources/postgres.md +++ b/docs/sources/datasources/postgres.md @@ -183,12 +183,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, result sets of time series queries must be sorted by time for panels to properly visualize the result. -Resultsets of time series queries need to be sorted by time. +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. + +> 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" >}}). **Example with `metric` column:** @@ -203,20 +204,48 @@ GROUP BY time ORDER BY time ``` -**Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:** +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 + hostname FROM test_data WHERE $__timeFilter("createdAt") -GROUP BY time, measurement +GROUP BY time, hostname ORDER BY time ``` +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: + +```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 @@ -230,6 +259,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 c5ba863ebd15..fb5225bf65f5 100755 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -342,5 +342,27 @@ Refer to [Grafana Live configuration]({{< relref "../live/configure-grafana-live Grafana v8.0 changes the underlying data structure to [data frames]({{< relref "../developers/plugins/data-frames.md" >}}) for the Postgres, MySQL, Microsoft SQL Server data sources. As a result, a _Time series_ query result gets returned in a [wide format]({{< relref "../developers/plugins/data-frames.md#wide-format" >}}). To make the visualizations work as they did before, you might have to do some manual migrations. 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 series names + +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 + $__timeGroup("createdAt",'10m'), + avg(value) as "value", + hostname +FROM grafana_metric +WHERE $__timeFilter("createdAt") +GROUP BY time, hostname +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 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" >}}).