From 8a1bd2ee223410b09fe0833f9de2749bb74c9776 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Tue, 6 Mar 2018 09:24:36 +0100 Subject: [PATCH 01/39] docs: fill for mysql/postgres ref #10138 --- docs/sources/features/datasources/mysql.md | 14 ++++++++++++++ docs/sources/features/datasources/postgres.md | 15 +++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/docs/sources/features/datasources/mysql.md b/docs/sources/features/datasources/mysql.md index 7fae7441b6d..6c15006949e 100644 --- a/docs/sources/features/datasources/mysql.md +++ b/docs/sources/features/datasources/mysql.md @@ -50,6 +50,7 @@ Macro example | Description *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *FROM_UNIXTIME(1494410783)* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *FROM_UNIXTIME(1494497183)* *$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed) as time_sec,* +*$__timeGroup(dateColumn,'5m',0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). *$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* *$__unixEpochTo()* | Will be replaced by the end of the currently active time selection as unix timestamp. For example, *1494497183* @@ -119,6 +120,19 @@ GROUP BY 1, metric_name ORDER BY 1 ``` +Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead: + +```sql +SELECT + $__timeGroup(atimestamp,'24h',0) as time_sec, + avg(afloat) as value, + avarchar as metric +FROM testdata.grafana_metrics +WHERE $__timeFilter(atimestamp) +GROUP BY 1, avarchar +ORDER BY 1 +``` + Currently, there is no support for a dynamic group by time based on time range & panel width. This is something we plan to add. diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index 7d52df2fd3e..270640a93dc 100644 --- a/docs/sources/features/datasources/postgres.md +++ b/docs/sources/features/datasources/postgres.md @@ -49,6 +49,7 @@ Macro example | Description *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *to_timestamp(1494410783)* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *to_timestamp(1494497183)* *$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *(extract(epoch from dateColumn)/300)::bigint*300 AS time* +*$__timeGroup(dateColumn,'5m', 0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). *$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* *$__unixEpochTo()* | Will be replaced by the end of the currently active time selection as unix timestamp. For example, *1494497183* @@ -103,6 +104,20 @@ GROUP BY time ORDER BY time ``` +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 +FROM public.grafana_metric +WHERE + $__timeFilter("createdAt") +GROUP BY time, measurement +ORDER BY time +``` + Example with multiple columns: ```sql From 1f8a2a67bff9ed3cd25312f4617198bdb4b4927a Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Mon, 19 Mar 2018 11:06:10 +0100 Subject: [PATCH 02/39] docs: Using Microsoft SQL Server in Grafana --- docs/sources/features/datasources/index.md | 1 + docs/sources/features/datasources/mssql.md | 229 +++++++++++++++++++++ 2 files changed, 230 insertions(+) create mode 100644 docs/sources/features/datasources/mssql.md diff --git a/docs/sources/features/datasources/index.md b/docs/sources/features/datasources/index.md index 54606d20988..a892f38a448 100644 --- a/docs/sources/features/datasources/index.md +++ b/docs/sources/features/datasources/index.md @@ -30,6 +30,7 @@ The following datasources are officially supported: * [Prometheus]({{< relref "prometheus.md" >}}) * [MySQL]({{< relref "mysql.md" >}}) * [Postgres]({{< relref "postgres.md" >}}) +* [Microsoft SQL Server (MSSQL)]({{< relref "mssql.md" >}}) ## Data source plugins diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md new file mode 100644 index 00000000000..2bcfd9dc59c --- /dev/null +++ b/docs/sources/features/datasources/mssql.md @@ -0,0 +1,229 @@ ++++ +title = "Using Microsoft SQL Server in Grafana" +description = "Guide for using Microsoft SQL Server in Grafana" +keywords = ["grafana", "MSSQL", "Microsoft", "SQL", "guide"] +type = "docs" +[menu.docs] +name = "Microsoft SQL Server" +parent = "datasources" +weight = 7 ++++ + +# Using Microsoft SQL Server in Grafana + +Grafana ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer. + +## Adding the data source + +1. Open the side menu by clicking the Grafana icon in the top header. +2. In the side menu under the `Configuration` link you should find a link named `Data Sources`. +3. Click the `+ Add data source` button in the top header. +4. Select *Microsoft SQL Server* from the *Type* dropdown. + +### Database User Permissions (Important!) + +The database user you specify when you add the data source should only be granted SELECT permissions on +the specified database & tables you want to query. Grafana does not validate that the query is safe. The query +could include any SQL statement. For example, statements like `DELETE FROM user;` and `DROP TABLE user;` would be +executed. To protect against this we **Highly** recommmend you create a specific MSSQL user with restricted permissions. + +Example: + +```sql + CREATE USER grafanareader WITH PASSWORD 'password' + GRANT SELECT ON dbo.YourTable3 TO grafanareader +``` + +Make sure the user does not get any unwanted privileges from the public role. + +## Macros + +To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros. + +Macro example | Description +------------ | ------------- +*$__time(dateColumn)* | Will be replaced by an expression to rename the column to `time`. For example, *`dateColumn as time`* +*$__utcTime(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to UTC depending on the server's local timeoffset and rename it to `time`. For example, *`DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time`* +*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to `time`. For example, *`DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time`* +*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *`dateColumn >= DATEADD(s, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01') AND dateColumn <= DATEADD(s, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')`* +*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *`DATEADD(second, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')`* +*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *`DATEADD(second, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')`* +*$__timeGroup(dateColumn,'5m', NULL)* | Will be replaced by an expression usable in GROUP BY clause. For example, *`cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumns))/300 as int)*300 as int)`* +*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *`dateColumn > 1494410783 AND dateColumn < 1494497183`* +*$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *`1494410783`* +*$__unixEpochTo()* | Will be replaced by the end of the currently active time selection as unix timestamp. For example, *`1494497183`* + +We plan to add many more macros. If you have suggestions for what macros you would like to see, please [open an issue](https://github.com/grafana/grafana) in our GitHub repo. + +The query editor has a link named `Generated SQL` that shows up after a query has been executed, while in panel edit mode. Click on it and it will expand and show the raw interpolated SQL string that was executed. + +## Table queries + +If the `Format as` query option is set to `Table` then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns & rows your query returns. + +Query editor with example query: + +![](/img/docs/v47/mssql_table_query.png) + + +The query: + +```sql +SELECT COLUMN_NAME AS [Name], + DATA_TYPE AS [Type], + CHARACTER_OCTET_LENGTH AS [Length], + NUMERIC_PRECISION as [Precisopn], + NUMERIC_PRECISION_RADIX AS [Radix], + NUMERIC_SCALE AS [Scale] +FROM INFORMATION_SCHEMA.COLUMNS +WHERE TABLE_NAME = 'mssql_types'; +``` + +You can control the name of the Table panel columns by using regular `AS ` SQL column selection syntax. + +The resulting table panel: + +![](/img/docs/v47/mssql_table.png) + +### Time series queries + +If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must 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 ommit the `metric` column, tha 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 select multiple value columns along with a `metric` column, the names ("MetircName - ColumnName") will be combined to make the metric name. + +Example with `metric` column + +```sql +SELECT + [time_date_time] as [time], + [value_double] as [value], + [metric1] as [metric] +FROM [test_data] +WHERE $__timeFilter([time_date_time]) +ORDER BY [time_date_time] +``` + +Example with multiple `value` culumns + +```sql +SELECT + [time_date_time] as [time], + [value_double1] as [metric_name1], + [value_int2] as [metric_name2] +FROM [test_data] +WHERE $__timeFilter([time_date_time]) +ORDER BY [time_date_time] +``` + +Example with multiple `value` culumns combined with a `metric` column + +```sql +SELECT + [time_date_time] as [time], + [value_double1] as [value1], + [value_int2] as [value2], + [metric_col] as [metric] +FROM [test_data] +WHERE $__timeFilter([time_date_time]) +ORDER BY [time_date_time] +``` +The result of the above query would look something like the below + +![](/img/docs/v47/mssql_metric_value.png) + +Currently, there is no support for a dynamic group by time based on time range & panel width. +This is something we plan to add. + +## Templating + +Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard. + +Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. + +### Query Variable + +If you add a template variable of the type `Query`, you can write a MSSQL query that can +return things like measurement names, key names or key values that are shown as a dropdown select box. + +For example, you can have a variable that contains all values for the `hostname` column in a table if you specify a query like this in the templating variable *Query* setting. + +```sql +SELECT hostname FROM host +``` + +A query can return multiple columns and Grafana will automatically create a list from them. For example, the query below will return a list with values from `hostname` and `hostname2`. + +```sql +SELECT [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city] +``` + +Another option is a query that can create a key/value variable. The query should return two columns that are named `__text` and `__value`. The `__text` column value should be unique (if it is not unique then the first value is used). The options in the dropdown will have a text and value that allows you to have a friendly name as text and an id as the value. An example query with `hostname` as the text and `id` as the value: + +```sql +SELECT hostname __text, id __value FROM host +``` + +You can also create nested variables. For example if you had another variable named `region`. Then you could have +the hosts variable only show hosts from the current selected region with a query like this (if `region` is a multi-value variable then use the `IN` comparison operator rather than `=` to match against multiple values): + +```sql +SELECT hostname FROM host WHERE region IN ($region) +``` + +### Using Variables in Queries + +From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically so if it is a string value do not wrap them in quotes in where clauses. + +From Grafana 4.7.0, template variable values are only quoted when the template variable is a `multi-value`. + +If the variable is a multi-value variable then use the `IN` comparison operator rather than `=` to match against multiple values. + +There are two syntaxes: + +`$` Example with a template variable named `hostname`: + +```sql +SELECT + atimestamp time, + aint value +FROM table +WHERE $__timeFilter(atimestamp) and hostname in($hostname) +ORDER BY atimestamp +``` + +`[[varname]]` Example with a template variable named `hostname`: + +```sql +SELECT + atimestamp as time, + aint as value +FROM table +WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) +ORDER BY atimestamp +``` + +## Annotations + +[Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. + +An example query: + +```sql +SELECT + DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time_column) ) as [time], + metric1 as [text], + convert(varvhar, metric1) + ',' + convert(varchar, metric2) as [tags] +FROM + test_data +WHERE + $__timeFilter(time_column) +``` + +Name | Description +------------ | ------------- +time | The name of the date/time field. could be in a native sql time datatype +text | Event description field. +tags | Optional field name to use for event tags as a comma separated string. + +## Alerting + +Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule +conditions. From 74c3f732c15df7e59a587f12f98bdce2af3bb505 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Mon, 19 Mar 2018 22:08:10 +0100 Subject: [PATCH 03/39] docs: update using mssql in grafana --- docs/sources/features/datasources/mssql.md | 430 +++++++++++++++++---- 1 file changed, 363 insertions(+), 67 deletions(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 2bcfd9dc59c..325e1fe3596 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -11,6 +11,8 @@ weight = 7 # Using Microsoft SQL Server in Grafana +> Only available in Grafana v5.1+. + Grafana ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer. ## Adding the data source @@ -20,6 +22,17 @@ Grafana ships with a built-in Microsoft SQL Server (MSSQL) data source plugin th 3. Click the `+ Add data source` button in the top header. 4. Select *Microsoft SQL Server* from the *Type* dropdown. +### Data source options + +Name | Description +------------ | ------------- +*Name* | The data source name. This is how you refer to the data source in panels & queries. +*Default* | Default data source means that it will be pre-selected for new panels. +*Host* | The IP address/hostname and optional port of your MSSQL instance. If port is omitted, default 1443 will be used. +*Database* | Name of your MSSQL database. +*User* | Database user's login/username +*Password* | Database user's password + ### Database User Permissions (Important!) The database user you specify when you add the data source should only be granted SELECT permissions on @@ -36,101 +49,213 @@ Example: Make sure the user does not get any unwanted privileges from the public role. +## Query Editor +{{< docs-imagebox img="/img/docs/v51/mssql_query_editor.png" class="docs-image--no-shadow" >}} + +You find the MSSQL query editor in the metrics tab in Graph, Singlestat or Table panel's edit mode. You enter edit mode by clicking the +panel title, then edit. The editor allows you to define a SQL query to select data to be visualized. + +1. Select *Format as* `Time series` (for use in Graph or Singlestat panel's among others) or `Table` (for use in Table panel among others). +2. This is the actual editor where you write your SQL queries. +3. Show help section for MSSQL below the query editor. +4. Show actual executed SQL query. Will be available first after a successful query has been executed. +5. Add an additional query where an additional query editor will be displayed. + +
+ ## Macros To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros. Macro example | Description ------------ | ------------- -*$__time(dateColumn)* | Will be replaced by an expression to rename the column to `time`. For example, *`dateColumn as time`* -*$__utcTime(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to UTC depending on the server's local timeoffset and rename it to `time`. For example, *`DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time`* -*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to `time`. For example, *`DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time`* -*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *`dateColumn >= DATEADD(s, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01') AND dateColumn <= DATEADD(s, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')`* -*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *`DATEADD(second, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')`* -*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *`DATEADD(second, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')`* -*$__timeGroup(dateColumn,'5m', NULL)* | Will be replaced by an expression usable in GROUP BY clause. For example, *`cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumns))/300 as int)*300 as int)`* -*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *`dateColumn > 1494410783 AND dateColumn < 1494497183`* -*$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *`1494410783`* -*$__unixEpochTo()* | Will be replaced by the end of the currently active time selection as unix timestamp. For example, *`1494497183`* +*$__time(dateColumn)* | Will be replaced by an expression to rename the column to *time*. For example, *dateColumn as time* +*$__utcTime(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to UTC depending on the server's local timeoffset and rename it to *time*.
For example, *DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time* +*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to *time*.
For example, *DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time* +*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name.
For example, *dateColumn >= DATEADD(s, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01') AND dateColumn <= DATEADD(s, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* +*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *DATEADD(second, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* +*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *DATEADD(second, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* +*$__timeGroup(dateColumn,'5m'[, fillvalue])* | Will be replaced by an expression usable in GROUP BY clause. Providing a *fillValue* of *NULL* or *floating value* will automatically fill empty series in timerange with that value.
For example, *cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second, GETDATE(), GETUTCDATE()), column))/300 as int)*300 as int)*. +*$__timeGroup(dateColumn,'5m', 0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). +*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* +*$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* +*$__unixEpochTo()* | Will be replaced by the end of the currently active time selection as unix timestamp. For example, *1494497183* We plan to add many more macros. If you have suggestions for what macros you would like to see, please [open an issue](https://github.com/grafana/grafana) in our GitHub repo. The query editor has a link named `Generated SQL` that shows up after a query has been executed, while in panel edit mode. Click on it and it will expand and show the raw interpolated SQL string that was executed. ## Table queries - If the `Format as` query option is set to `Table` then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns & rows your query returns. +**Example database table:** + +```sql +CREATE TABLE [event] ( + time_sec bigint, + description nvarchar(100), + tags nvarchar(100), +) +``` + +```sql +CREATE TABLE [mssql_types] ( + c_bit bit, c_tinyint tinyint, c_smallint smallint, c_int int, c_bigint bigint, c_money money, c_smallmoney smallmoney, c_numeric numeric(10,5), + c_real real, c_decimal decimal(10,2), c_float float, + c_char char(10), c_varchar varchar(10), c_text text, + c_nchar nchar(12), c_nvarchar nvarchar(12), c_ntext ntext, + c_datetime datetime, c_datetime2 datetime2, c_smalldatetime smalldatetime, c_date date, c_time time, c_datetimeoffset datetimeoffset +) + +INSERT INTO [mssql_types] +SELECT + 1, 5, 20020, 980300, 1420070400, '$20000.15', '£2.15', 12345.12, + 1.11, 2.22, 3.33, + 'char10', 'varchar10', 'text', + N'☺nchar12☺', N'☺nvarchar12☺', N'☺text☺', + GETDATE(), CAST(GETDATE() AS DATETIME2), CAST(GETDATE() AS SMALLDATETIME), CAST(GETDATE() AS DATE), CAST(GETDATE() AS TIME), SWITCHOFFSET(CAST(GETDATE() AS DATETIMEOFFSET), '-07:00')) +``` + Query editor with example query: -![](/img/docs/v47/mssql_table_query.png) +{{< docs-imagebox img="/img/docs/v51/mssql_table_query.png" max-width="500px" class="docs-image--no-shadow" >}} The query: ```sql -SELECT COLUMN_NAME AS [Name], - DATA_TYPE AS [Type], - CHARACTER_OCTET_LENGTH AS [Length], - NUMERIC_PRECISION as [Precisopn], - NUMERIC_PRECISION_RADIX AS [Radix], - NUMERIC_SCALE AS [Scale] -FROM INFORMATION_SCHEMA.COLUMNS -WHERE TABLE_NAME = 'mssql_types'; +SELECT * FROM [mssql_types] ``` -You can control the name of the Table panel columns by using regular `AS ` SQL column selection syntax. +You can control the name of the Table panel columns by using regular `AS ` SQL column selection syntax. Example: + +```sql +SELECT + c_bit as [column1], c_tinyint as [column2] +FROM + [mssql_types] +``` The resulting table panel: -![](/img/docs/v47/mssql_table.png) +{{< docs-imagebox img="/img/docs/v51/mssql_table_result.png" max-width="1489px" class="docs-image--no-shadow" >}} -### Time series queries +## Time series queries -If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must 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 ommit the `metric` column, tha 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 select multiple value columns along with a `metric` column, the names ("MetircName - ColumnName") will be combined to make the metric name. +If you set `Format as` to `Time series`, for use in Graph panel for example, then the query must 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 ommit the `metric` column, tha name of the value column will be the metric name. You may select multiple value columns, each will have its name as metric. -Example with `metric` column +**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) + +``` + +{{< docs-imagebox img="/img/docs/v51/mssql_time_series_one.png" class="docs-image--no-shadow docs-image--right" >}} + +**Example with one `value` and one `metric` column.** ```sql SELECT - [time_date_time] as [time], - [value_double] as [value], - [metric1] as [metric] -FROM [test_data] -WHERE $__timeFilter([time_date_time]) -ORDER BY [time_date_time] + time, + valueOne, + measurement as metric +FROM + metric_values +WHERE + $__timeFilter(time) +ORDER BY 1 ``` -Example with multiple `value` culumns +When above query are used in a graph panel the result will be two series named `Metric A` and `Metric B` with value of `valueOne` and `valueTwo` plotted over `time`. + +
+ +{{< docs-imagebox img="/img/docs/v51/mssql_time_series_two.png" class="docs-image--no-shadow docs-image--right" >}} + +**Example with multiple `value` culumns:** ```sql SELECT - [time_date_time] as [time], - [value_double1] as [metric_name1], - [value_int2] as [metric_name2] -FROM [test_data] -WHERE $__timeFilter([time_date_time]) -ORDER BY [time_date_time] + time, + valueOne, + valueTwo +FROM + metric_values +WHERE + $__timeFilter(time) +ORDER BY 1 ``` -Example with multiple `value` culumns combined with a `metric` column +When above query are used in a graph panel the result will be two series named `valueOne` and `valueTwo` with value of `valueOne` and `valueTwo` plotted over `time`. + +
+ +{{< docs-imagebox img="/img/docs/v51/mssql_time_series_three.png" class="docs-image--no-shadow docs-image--right" >}} + +**Example using the $__timeGroup macro:** ```sql SELECT - [time_date_time] as [time], - [value_double1] as [value1], - [value_int2] as [value2], - [metric_col] as [metric] -FROM [test_data] -WHERE $__timeFilter([time_date_time]) -ORDER BY [time_date_time] + $__timeGroup(time, '3m') as time, + measurement as metric, + avg(valueOne) +FROM + metric_values +WHERE + $__timeFilter(time) +GROUP BY + $__timeGroup(time, '3m'), + measurement +ORDER BY 1 ``` -The result of the above query would look something like the below -![](/img/docs/v47/mssql_metric_value.png) +When above query are used in a graph panel the result will be two series named `Metric A` and `Metric B` with an average of `valueOne` plotted over `time`. +Any two series lacking a value in a 3 minute window will render a line between those two lines. You'll notice that the graph to the right never goes down to zero. -Currently, there is no support for a dynamic group by time based on time range & panel width. -This is something we plan to add. +
+ +{{< docs-imagebox img="/img/docs/v51/mssql_time_series_four.png" class="docs-image--no-shadow docs-image--right" >}} + +**Example using the $__timeGroup macro with fill parameter set to zero:** + +```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 +ORDER BY 1 +``` + +When above query are used in a graph panel the result will be 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. ## Templating @@ -169,10 +294,9 @@ SELECT hostname FROM host WHERE region IN ($region) ``` ### Using Variables in Queries - -From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically so if it is a string value do not wrap them in quotes in where clauses. - -From Grafana 4.7.0, template variable values are only quoted when the template variable is a `multi-value`. +> From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically so if it is a string value do not wrap them in quotes in where clauses. +> +> From Grafana 5.0.0, template variable values are only quoted when the template variable is a `multi-value`. If the variable is a multi-value variable then use the `IN` comparison operator rather than `=` to match against multiple values. @@ -204,25 +328,197 @@ ORDER BY atimestamp [Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. -An example query: - -```sql -SELECT - DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time_column) ) as [time], - metric1 as [text], - convert(varvhar, metric1) + ',' + convert(varchar, metric2) as [tags] -FROM - test_data -WHERE - $__timeFilter(time_column) -``` +**Columns:** Name | Description ------------ | ------------- -time | The name of the date/time field. could be in a native sql time datatype +time | The name of the date/time field. Could be in a native sql time datatype or epoch seconds. text | Event description field. tags | Optional field name to use for event tags as a comma separated string. +**Example database tables:** + +```sql +CREATE TABLE [events] ( + time_sec bigint, + description nvarchar(100), + tags nvarchar(100), +) +``` + +We also use the database table defined in [Time series queries](#time-series-queries). + +**Example query using time column of type epoch seconds:** + +```sql +SELECT + time_sec as time, + description as [text], + tags +FROM + [events] +WHERE + $__unixEpochFilter(time_sec) +ORDER BY 1 +``` + +**Example query using time column of type datetime:** + +```sql +SELECT + time, + measurement as text, + convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags +FROM + metric_values +WHERE + $__timeFilter(time_column) +ORDER BY 1 +``` + +## Stored procedure support +Stored procedures have been verified to work. However, please note that we haven't done anything special to support this why there may exist edge cases where it won't work as you would expect. +Stored procedures should be supported in table, time series and annotation queries as long as you use the same naming of columns and return data in the same format as describe above under respective section. + +Please note that any macro function will not work inside a stored procedure. + +### Examples +{{< docs-imagebox img="/img/docs/v51/mssql_metrics_graph.png" class="docs-image--no-shadow docs-image--right" >}} +For the following examples the database table defined in [Time series queries](#time-series-queries). Let's say that we want to visualize 4 series in a graph panel, i.e. all combinations of columns `valueOne`, `valueTwo` and `measurement`. Graph panel to the right visualizes what we want to achieve. To solve this we actually need to use two queries: + +**First query:** +```sql +SELECT + $__timeGroup(time, '5m') as time, + measurement + ' - value one' as metric, + avg(valueOne) as valueOne +FROM + metric_values +WHERE + $__timeFilter(time) +GROUP BY + $__timeGroup(time, '5m'), + measurement +ORDER BY 1 +``` + +**Second query:** +```sql +SELECT + $__timeGroup(time, '5m') as time, + measurement + ' - value two' as metric, + avg(valueTwo) as valueTwo +FROM + metric_values +GROUP BY + $__timeGroup(time, '5m'), + measurement +ORDER BY 1 +``` + +#### Stored procedure using time in epoch format +We can define a stored procedure that will return all data we need to render 4 series in a graph panel like above. +In this case the stored procedure accepts two parameters `@from` and `@to` of `int` data types which should be a timerange (from-to) in epoch format +which will be used to filter the data to return from the stored procedure. + +We're mimicking the `$__timeGroup(time, '5m')` in the select and group by expressions and that's why there's a lot of lengthy expressions needed - +these could be extracted to MSSQL functions, if wanted. + +```sql +CREATE PROCEDURE sp_test_epoch( + @from int, + @to int +) AS +BEGIN + SELECT + cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time, + measurement + ' - value one' as metric, + avg(valueOne) as value + FROM + metric_values + WHERE + time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01') + GROUP BY + cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int), + measurement + UNION ALL + SELECT + cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time, + measurement + ' - value two' as metric, + avg(valueTwo) as value + FROM + metric_values + WHERE + time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01') + GROUP BY + cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int), + measurement + ORDER BY 1 +END +``` + +Then we can use the following query for our graph panel. + +```sql +DECLARE + @from int = $__unixEpochFrom(), + @to int = $__unixEpochTo() + +EXEC dbo.sp_test_epoch @from, @to +``` + +#### Stored procedure using time in datetime format +We can define a stored procedure that will return all data we need to render 4 series in a graph panel like above. +In this case the stored procedure accepts two parameters `@from` and `@to` of `datetime` data types which should be a timerange (from-to) +which will be used to filter the data to return from the stored procedure. + +We're mimicking the `$__timeGroup(time, '5m')` in the select and group by expressions and that's why there's a lot of lengthy expressions needed - +these could be extracted to MSSQL functions, if wanted. + +```sql +CREATE PROCEDURE sp_test_datetime( + @from datetime, + @to datetime +) AS +BEGIN + SELECT + cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time, + measurement + ' - value one' as metric, + avg(valueOne) as value + FROM + metric_values + WHERE + time >= @from AND time <= @to + GROUP BY + cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int), + measurement + UNION ALL + SELECT + cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time, + measurement + ' - value two' as metric, + avg(valueTwo) as value + FROM + metric_values + WHERE + time >= @from AND time <= @to + GROUP BY + cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int), + measurement + ORDER BY 1 +END + +``` + +Then we can use the following query for our graph panel. + +```sql +DECLARE + @from datetime = $__timeFrom(), + @to datetime = $__timeTo() + +EXEC dbo.sp_test_datetime @from, @to +``` + ## Alerting Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule From e5df179c7cf41a986123980a594fe68f1668f86c Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Tue, 20 Mar 2018 20:38:20 +0100 Subject: [PATCH 04/39] docs: spelling --- docs/sources/features/datasources/mssql.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 325e1fe3596..71baf4bd050 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -86,6 +86,7 @@ We plan to add many more macros. If you have suggestions for what macros you wou The query editor has a link named `Generated SQL` that shows up after a query has been executed, while in panel edit mode. Click on it and it will expand and show the raw interpolated SQL string that was executed. ## Table queries + If the `Format as` query option is set to `Table` then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns & rows your query returns. **Example database table:** @@ -142,7 +143,7 @@ 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 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 ommit the `metric` column, tha 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 set `Format as` to `Time series`, for use in Graph panel for example, then the query must 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, tha name of the value column will be the metric name. You may select multiple value columns, each will have its name as metric. **Example database table:** @@ -377,16 +378,19 @@ ORDER BY 1 ``` ## Stored procedure support + Stored procedures have been verified to work. However, please note that we haven't done anything special to support this why there may exist edge cases where it won't work as you would expect. Stored procedures should be supported in table, time series and annotation queries as long as you use the same naming of columns and return data in the same format as describe above under respective section. Please note that any macro function will not work inside a stored procedure. ### Examples + {{< docs-imagebox img="/img/docs/v51/mssql_metrics_graph.png" class="docs-image--no-shadow docs-image--right" >}} For the following examples the database table defined in [Time series queries](#time-series-queries). Let's say that we want to visualize 4 series in a graph panel, i.e. all combinations of columns `valueOne`, `valueTwo` and `measurement`. Graph panel to the right visualizes what we want to achieve. To solve this we actually need to use two queries: **First query:** + ```sql SELECT $__timeGroup(time, '5m') as time, @@ -417,6 +421,7 @@ ORDER BY 1 ``` #### Stored procedure using time in epoch format + We can define a stored procedure that will return all data we need to render 4 series in a graph panel like above. In this case the stored procedure accepts two parameters `@from` and `@to` of `int` data types which should be a timerange (from-to) in epoch format which will be used to filter the data to return from the stored procedure. @@ -468,6 +473,7 @@ EXEC dbo.sp_test_epoch @from, @to ``` #### Stored procedure using time in datetime format + We can define a stored procedure that will return all data we need to render 4 series in a graph panel like above. In this case the stored procedure accepts two parameters `@from` and `@to` of `datetime` data types which should be a timerange (from-to) which will be used to filter the data to return from the stored procedure. @@ -521,5 +527,5 @@ EXEC dbo.sp_test_datetime @from, @to ## Alerting -Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule +Time series queries should work in alerting conditions. Table formatted queries are not yet supported in alert rule conditions. From 1b8103f0ea2aeb5fdf9a3670559d15ce0474a4a1 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 23 Mar 2018 14:21:07 +0100 Subject: [PATCH 05/39] docs: update graph panel documentation Added new versions of images and new images to better highlight the possible configuration options. Documentation was very outdated so tried to fix that to better reflect the current state/latest release. --- docs/sources/features/panels/graph.md | 128 ++++++++++++++++---------- 1 file changed, 79 insertions(+), 49 deletions(-) diff --git a/docs/sources/features/panels/graph.md b/docs/sources/features/panels/graph.md index c3b0260c98b..d47131dc47c 100644 --- a/docs/sources/features/panels/graph.md +++ b/docs/sources/features/panels/graph.md @@ -22,15 +22,18 @@ options for the panel. ## General -{{< docs-imagebox img="/img/docs/v43/graph_general.png" max-width= "900px" >}} +{{< docs-imagebox img="/img/docs/v51/graph_general.png" max-width= "800px" >}} The general tab allows customization of a panel's appearance and menu options. -### General Options +### Info -- **Title** - The panel title on the dashboard -- **Span** - The panel width in columns -- **Height** - The panel contents height in pixels +- **Title** - The panel title of the dashboard, displayed at the top. +- **Description** - The panel description, displayed on hover of info icon in the upper left corner of the panel. +- **Transparent** - If checked, removes the solid background of the panel (default not checked). + +### Repeat +Repeat a panel for each value of a variable. Repeating panels are described in more detail [here]({{< relref "reference/templating.md#repeating-panels" >}}). ### Drilldown / detail link @@ -54,47 +57,65 @@ options. ## Axes -{{< docs-imagebox img="/img/docs/v43/graph_axes_grid_options.png" max-width= "900px" >}} +{{< docs-imagebox img="/img/docs/v51/graph_axes_grid_options.png" max-width= "800px" >}} -The Axes tab controls the display of axes, grids and legend. The **Left Y** and **Right Y** can be customized using: +The Axes tab controls the display of axes. + +### Left Y/Right Y + +The **Left Y** and **Right Y** can be customized using: - **Unit** - The display unit for the Y value -- **Scale** - +- **Scale** - The scale to use for the Y value, linear or logarithmic. (default linear) - **Y-Min** - The minimum Y value. (default auto) - **Y-Max** - The maximum Y value. (default auto) +- **Decimals** - Controls how many decimals are displayed for Y value (default auto) - **Label** - The Y axis label (default "") Axes can also be hidden by unchecking the appropriate box from **Show**. -### X-Axis Mode +### X-Axis -There are three options: +Axis can be hidden by unchecking **Show**. + +For **Mode** there are three options: - The default option is **Time** and means the x-axis represents time and that the data is grouped by time (for example, by hour or by minute). - The **Series** option means that the data is grouped by series and not by time. The y-axis still represents the value. - {{< docs-imagebox img="/img/docs/v45/graph-x-axis-mode-series.png" max-width="700px">}} + {{< docs-imagebox img="/img/docs/v51/graph-x-axis-mode-series.png" max-width="800px">}} - The **Histogram** option converts the graph into a histogram. A Histogram is a kind of bar chart that groups numbers into ranges, often called buckets or bins. Taller bars show that more data falls in that range. Histograms and buckets are described in more detail [here](http://docs.grafana.org/features/panels/heatmap/#histograms-and-buckets). -### Legend -The legend hand be hidden by checking the **Show** checkbox. If it's shown, it can be -displayed as a table of values by checking the **Table** checkbox. Series with no -values can be hidden from the legend using the **Hide empty** checkbox. +### Y-Axes -### Legend Values +- **Align** - Check to align left and right Y-axes by value (default unchecked/false) +- **Level** - Available when *Align* is checked. Value to use for alignment of left and right Y-axes, starting from Y=0 (default 0) + +## Legend + +{{< docs-imagebox img="/img/docs/v51/graph-legend.png" max-width= "800px" >}} + +### Options + +- **Show** - Uncheck to hide the legend (default checked/true) +- **Table** - Check to display legend in table (default unchecked/false) +- **To the right** - Check to display legend to the right (default unchecked/false) +- **Width** - Available when *To the right* is checked. Value to contral the minimum width for the legend (default 0) + +### Values Additional values can be shown along-side the legend names: -- **Total** - Sum of all values returned from metric query -- **Current** - Last value returned from the metric query - **Min** - Minimum of all values returned from metric query - **Max** - Maximum of all values returned from the metric query - **Avg** - Average of all values returned from metric query +- **Current** - Last value returned from the metric query +- **Total** - Sum of all values returned from metric query - **Decimals** - Controls how many decimals are displayed for legend values (and graph hover tooltips) The legend values are calculated client side by Grafana and depend on what type of @@ -103,63 +124,72 @@ be correct at the same time. For example if you plot a rate like requests/second using average as aggregator, then the Total in the legend will not represent the total number of requests. It is just the sum of all data points received by Grafana. +### Hide series + +Hide series when all values of a serie from a metric query are of a specific value: + +- **With only nulls** - Value=*null* (default unchecked) +- **With only zeros** - Value=*zero* (default unchecked) + ## Display styles -{{< docs-imagebox img="/img/docs/v43/graph_display_styles.png" max-width= "900px" >}} +{{< docs-imagebox img="/img/docs/v51/graph_display_styles.png" max-width= "800px" >}} Display styles control visual properties of the graph. -### Thresholds +### Draw Options -Thresholds allow you to add arbitrary lines or sections to the graph to make it easier to see when -the graph crosses a particular threshold. - - -### Chart Options +#### Draw Modes - **Bar** - Display values as a bar chart - **Lines** - Display values as a line graph - **Points** - Display points for values -### Line Options +#### Mode Options -- **Line Fill** - Amount of color fill for a series. 0 is none. -- **Line Width** - The width of the line for a series. -- **Null point mode** - How null values are displayed -- **Staircase line** - Draws adjacent points as staircase +- **Fill** - Amount of color fill for a series (default 1). 0 is none. +- **Line Width** - The width of the line for a series (default 1). +- **Staircase** - Draws adjacent points as staircase +- **Points Radius** - Asjust the size of points when *Points* are selected as *Draw Mode*. -### Multiple Series +#### Hover tooltip + +- **Mode** - Controls how many series to display in the tooltip when hover over a point in time, All series or single (default All series). +- **Sort order** - Controls how series displayed in tooltip are sorted, None, Ascending or Descending (default None). +- **Stacked value** - Available when *Stack* are checked and controls how stacked values are displayed in tooltip (default Individual). + - Individual: the value for the series you hover over + - Cumulative - sum of series below plus the series you hover over + +#### Stacking & Null value If there are multiple series, they can be displayed as a group. - **Stack** - Each series is stacked on top of another -- **Percent** - Each series is drawn as a percentage of the total of all series +- **Percent** - Available when *Stack* are checked. Each series is drawn as a percentage of the total of all series +- **Null value** - How null values are displayed -If you have stack enabled, you can select what the mouse hover feature should show. +### Series overrides -- Cumulative - Sum of series below plus the series you hover over -- Individual - Just the value for the series you hover over - -### Rendering - -- **Flot** - Render the graphs in the browser using Flot (default) -- **Graphite PNG** - Render the graph on the server using graphite's render API. - -### Tooltip - -- **All series** - Show all series on the same tooltip and a x crosshairs to help follow all series - -### Series Specific Overrides +{{< docs-imagebox img="/img/docs/v51/graph_display_overrides.png" max-width= "800px" >}} The section allows a series to be rendered differently from the others. For example, one series can be given -a thicker line width to make it stand out. +a thicker line width to make it stand out and/or be moved to the right Y-axis. #### Dashes Drawing Style There is an option under Series overrides to draw lines as dashes. Set Dashes to the value True to override the line draw setting for a specific series. +### Thresholds + +{{< docs-imagebox img="/img/docs/v51/graph_display_thresholds.png" max-width= "800px" >}} + +Thresholds allow you to add arbitrary lines or sections to the graph to make it easier to see when +the graph crosses a particular threshold. + ## Time Range -The time range tab allows you to override the dashboard time range and specify a panel specific time. Either through a relative from now time option or through a timeshift. +{{< docs-imagebox img="/img/docs/v51/graph-time-range.png" max-width= "900px" >}} -{{< docs-imagebox img="/img/docs/v45/graph-time-range.png" max-width= "900px" >}} +The time range tab allows you to override the dashboard time range and specify a panel specific time. +Either through a relative from now time option or through a timeshift. +Panel time overrides & timeshift are described in more detail [here]({{< relref "reference/timerange.md#panel-time-overrides-timeshift" >}}). From 403c64ab20b75b284803ed1a46c6b26a1e2220d7 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 23 Mar 2018 15:48:04 +0100 Subject: [PATCH 06/39] docs: update postgres, mysql and mssql documentation Due to changes closing #11306 --- docs/sources/features/datasources/mssql.md | 17 ++- docs/sources/features/datasources/mysql.md | 118 +++++++++++------- docs/sources/features/datasources/postgres.md | 63 +++++++--- 3 files changed, 124 insertions(+), 74 deletions(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 71baf4bd050..26ba6b31ceb 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -70,12 +70,11 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the Macro example | Description ------------ | ------------- *$__time(dateColumn)* | Will be replaced by an expression to rename the column to *time*. For example, *dateColumn as time* -*$__utcTime(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to UTC depending on the server's local timeoffset and rename it to *time*.
For example, *DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time* -*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to *time*.
For example, *DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), dateColumn) ) AS time* -*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name.
For example, *dateColumn >= DATEADD(s, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01') AND dateColumn <= DATEADD(s, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* -*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *DATEADD(second, 1494410783+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* -*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *DATEADD(second, 1494497183+DATEDIFF(second,GETUTCDATE(),GETDATE()), '1970-01-01')* -*$__timeGroup(dateColumn,'5m'[, fillvalue])* | Will be replaced by an expression usable in GROUP BY clause. Providing a *fillValue* of *NULL* or *floating value* will automatically fill empty series in timerange with that value.
For example, *cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second, GETDATE(), GETUTCDATE()), column))/300 as int)*300 as int)*. +*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert a DATETIME column type to unix timestamp and rename it to *time*.
For example, *DATEDIFF(second, '1970-01-01', dateColumn) AS time* +*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name.
For example, *dateColumn >= DATEADD(s, 1494410783, '1970-01-01') AND dateColumn <= DATEADD(s, 1494410783, '1970-01-01')* +*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *DATEADD(second, 1494410783, '1970-01-01')* +*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *DATEADD(second, 1494410783, '1970-01-01')* +*$__timeGroup(dateColumn,'5m'[, fillvalue])* | Will be replaced by an expression usable in GROUP BY clause. Providing a *fillValue* of *NULL* or *floating value* will automatically fill empty series in timerange with that value.
For example, *CAST(ROUND(DATEDIFF(second, '1970-01-01', time_column)/300.0, 0) as bigint)\*300*. *$__timeGroup(dateColumn,'5m', 0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). *$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* @@ -333,7 +332,7 @@ ORDER BY atimestamp Name | Description ------------ | ------------- -time | The name of the date/time field. Could be in a native sql time datatype or epoch seconds. +time | The name of the date/time field. Could be a column with a native sql date/time data type or epoch value. text | Event description field. tags | Optional field name to use for event tags as a comma separated string. @@ -349,7 +348,7 @@ CREATE TABLE [events] ( We also use the database table defined in [Time series queries](#time-series-queries). -**Example query using time column of type epoch seconds:** +**Example query using time column with epoch values:** ```sql SELECT @@ -363,7 +362,7 @@ WHERE ORDER BY 1 ``` -**Example query using time column of type datetime:** +**Example query using time column of native sql date/time data type:** ```sql SELECT diff --git a/docs/sources/features/datasources/mysql.md b/docs/sources/features/datasources/mysql.md index 6c15006949e..5334f21e178 100644 --- a/docs/sources/features/datasources/mysql.md +++ b/docs/sources/features/datasources/mysql.md @@ -12,6 +12,8 @@ weight = 7 # Using MySQL in Grafana > Only available in Grafana v4.3+. +> +> Starting from Grafana v5.1 you can name the time column *time* in addition to earlier supported *time_sec*. Usage of *time_sec* will eventually be deprecated. Grafana ships with a built-in MySQL data source plugin that allow you to query any visualize data from a MySQL compatible database. @@ -23,6 +25,17 @@ data from a MySQL compatible database. 3. Click the `+ Add data source` button in the top header. 4. Select *MySQL* from the *Type* dropdown. +### Data source options + +Name | Description +------------ | ------------- +*Name* | The data source name. This is how you refer to the data source in panels & queries. +*Default* | Default data source means that it will be pre-selected for new panels. +*Host* | The IP address/hostname and optional port of your MySQL instance. +*Database* | Name of your MySQL database. +*User* | Database user's login/username +*Password* | Database user's password + ### Database User Permissions (Important!) The database user you specify when you add the data source should only be granted SELECT permissions on @@ -46,10 +59,11 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the Macro example | Description ------------ | ------------- *$__time(dateColumn)* | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, *UNIX_TIMESTAMP(dateColumn) as time_sec* +*$__timeEpoch(dateColumn)* | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, *UNIX_TIMESTAMP(dateColumn) as time_sec* *$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *dateColumn > FROM_UNIXTIME(1494410783) AND dateColumn < FROM_UNIXTIME(1494497183)* *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *FROM_UNIXTIME(1494410783)* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *FROM_UNIXTIME(1494497183)* -*$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed) as time_sec,* +*$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed),* *$__timeGroup(dateColumn,'5m',0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). *$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* @@ -85,52 +99,50 @@ The resulting table panel: ![](/img/docs/v43/mysql_table.png) -### Time series queries +## Time series queries -If you set `Format as` to `Time series`, for use in Graph panel for example, then there are some requirements for -what your query returns. +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. -- Must be a column named `time_sec` representing a unix epoch in seconds. -- Must be a column named `value` representing the time series value. -- Must be a column named `metric` representing the time series name. - -Example: +**Example with `metric` column:** ```sql SELECT - min(UNIX_TIMESTAMP(time_date_time)) as time_sec, - max(value_double) as value, - metric1 as metric -FROM test_data -WHERE $__timeFilter(time_date_time) -GROUP BY metric1, UNIX_TIMESTAMP(time_date_time) DIV 300 -ORDER BY time_sec asc -``` - -Example with $__timeGroup macro: - -```sql -SELECT - $__timeGroup(time_date_time,'5m') as time_sec, - min(value_double) as value, - metric_name as metric + $__timeGroup(time_date_time,'5m'), + min(value_double), + 'min' as metric FROM test_data WHERE $__timeFilter(time_date_time) -GROUP BY 1, metric_name -ORDER BY 1 +GROUP BY time +ORDER BY time ``` -Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead: +**Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:** ```sql -SELECT - $__timeGroup(atimestamp,'24h',0) as time_sec, - avg(afloat) as value, - avarchar as metric -FROM testdata.grafana_metrics -WHERE $__timeFilter(atimestamp) -GROUP BY 1, avarchar -ORDER BY 1 +SELECT + $__timeGroup(createdAt,'5m',0), + sum(value_double) as value, + measurement +FROM test_data +WHERE + $__timeFilter(createdAt) +GROUP BY time, measurement +ORDER BY time +``` + +**Example with multiple columns:** + +```sql +SELECT + $__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 time +ORDER BY time ``` Currently, there is no support for a dynamic group by time based on time range & panel width. @@ -194,7 +206,7 @@ There are two syntaxes: ```sql SELECT - UNIX_TIMESTAMP(atimestamp) as time_sec, + UNIX_TIMESTAMP(atimestamp) as time, aint as value, avarchar as metric FROM my_table @@ -206,7 +218,7 @@ ORDER BY atimestamp ASC ```sql SELECT - UNIX_TIMESTAMP(atimestamp) as time_sec, + UNIX_TIMESTAMP(atimestamp) as time, aint as value, avarchar as metric FROM my_table @@ -216,23 +228,37 @@ ORDER BY atimestamp ASC ## Annotations -[Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. +[Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. -An example query: +**Example query using time column with epoch values:** ```sql SELECT - UNIX_TIMESTAMP(atimestamp) as time_sec, - value as text, + epoch_time as time, + metric1 as text, CONCAT(tag1, ',', tag2) as tags -FROM my_table -WHERE $__timeFilter(atimestamp) -ORDER BY atimestamp ASC +FROM + public.test_data +WHERE + $__unixEpochFilter(epoch_time) +``` + +**Example query using time column of native sql date/time data type:** + +```sql +SELECT + native_date_time as time, + metric1 as text, + CONCAT(tag1, ',', tag2) as tags +FROM + public.test_data +WHERE + $__timeFilter(native_date_time) ``` Name | Description ------------ | ------------- -time_sec | The name of the date/time field. +time | The name of the date/time field. Could be a column with a native sql date/time data type or epoch value. text | Event description field. tags | Optional field name to use for event tags as a comma separated string. diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index 270640a93dc..d830d8b9ed9 100644 --- a/docs/sources/features/datasources/postgres.md +++ b/docs/sources/features/datasources/postgres.md @@ -20,6 +20,18 @@ Grafana ships with a built-in PostgreSQL data source plugin that allows you to q 3. Click the `+ Add data source` button in the top header. 4. Select *PostgreSQL* from the *Type* dropdown. +### Data source options + +Name | Description +------------ | ------------- +*Name* | The data source name. This is how you refer to the data source in panels & queries. +*Default* | Default data source means that it will be pre-selected for new panels. +*Host* | The IP address/hostname and optional port of your PostgreSQL instance. +*Database* | Name of your PostgreSQL database. +*User* | Database user's login/username +*Password* | Database user's password +*SSL Mode* | This option determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. + ### Database User Permissions (Important!) The database user you specify when you add the data source should only be granted SELECT permissions on @@ -44,7 +56,7 @@ To simplify syntax and to allow for dynamic parts, like date range filters, the Macro example | Description ------------ | ------------- *$__time(dateColumn)* | Will be replaced by an expression to rename the column to `time`. For example, *dateColumn as time* -*$__timeSec(dateColumn)* | Will be replaced by an expression to rename the column to `time` and converting the value to unix timestamp. For example, *extract(epoch from dateColumn) as time* +*$__timeEpoch(dateColumn)* | Will be replaced by an expression to rename the column to `time` and converting the value to unix timestamp. For example, *extract(epoch from dateColumn) as time* *$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *extract(epoch from dateColumn) BETWEEN 1494410783 AND 1494497183* *$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *to_timestamp(1494410783)* *$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *to_timestamp(1494497183)* @@ -85,48 +97,48 @@ The resulting table panel: ![](/img/docs/v46/postgres_table.png) -### Time series queries +## 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 in seconds. +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. -Example with `metric` column +**Example with `metric` column:** ```sql SELECT - $__timeGroup(time_date_time,'5m'), - min(value_double), + $__timeGroup("time_date_time",'5m'), + min("value_double"), 'min' as metric FROM test_data -WHERE $__timeFilter(time_date_time) +WHERE $__timeFilter("time_date_time") GROUP BY time ORDER BY time ``` -Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead: +**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 -FROM public.grafana_metric +FROM test_data WHERE $__timeFilter("createdAt") GROUP BY time, measurement ORDER BY time ``` -Example with multiple columns: +**Example with multiple columns:** ```sql SELECT - $__timeGroup(time_date_time,'5m'), - min(value_double) as min_value, - max(value_double) as max_value + $__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) +WHERE $__timeFilter("time_date_time") GROUP BY time ORDER BY time ``` @@ -209,22 +221,35 @@ ORDER BY atimestamp ASC [Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. -An example query: +**Example query using time column with epoch values:** ```sql SELECT - extract(epoch from time_date_time) AS time, - metric1 as text, + epoch_time as time, + metric1 as text, concat_ws(', ', metric1::text, metric2::text) as tags FROM public.test_data WHERE - $__timeFilter(time_date_time) + $__unixEpochFilter(epoch_time) +``` + +**Example query using time column of native sql date/time data type:** + +```sql +SELECT + native_date_time as time, + metric1 as text, + concat_ws(', ', metric1::text, metric2::text) as tags +FROM + public.test_data +WHERE + $__timeFilter(native_date_time) ``` Name | Description ------------ | ------------- -time | The name of the date/time field. +time | The name of the date/time field. Could be a column with a native sql date/time data type or epoch value. text | Event description field. tags | Optional field name to use for event tags as a comma separated string. From 0a487c484d28768b6b8e257caeb537610bb415f1 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 23 Mar 2018 15:49:54 +0100 Subject: [PATCH 07/39] docs: fix typos --- docs/sources/features/panels/graph.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/panels/graph.md b/docs/sources/features/panels/graph.md index d47131dc47c..bc0f896775e 100644 --- a/docs/sources/features/panels/graph.md +++ b/docs/sources/features/panels/graph.md @@ -105,7 +105,7 @@ For **Mode** there are three options: - **Show** - Uncheck to hide the legend (default checked/true) - **Table** - Check to display legend in table (default unchecked/false) - **To the right** - Check to display legend to the right (default unchecked/false) -- **Width** - Available when *To the right* is checked. Value to contral the minimum width for the legend (default 0) +- **Width** - Available when *To the right* is checked. Value to control the minimum width for the legend (default 0) ### Values @@ -150,7 +150,7 @@ Display styles control visual properties of the graph. - **Fill** - Amount of color fill for a series (default 1). 0 is none. - **Line Width** - The width of the line for a series (default 1). - **Staircase** - Draws adjacent points as staircase -- **Points Radius** - Asjust the size of points when *Points* are selected as *Draw Mode*. +- **Points Radius** - Adjust the size of points when *Points* are selected as *Draw Mode*. #### Hover tooltip From b97cede054f22356405a55228bdea6f353e4d8ff Mon Sep 17 00:00:00 2001 From: Alexander Zobnin Date: Mon, 26 Mar 2018 16:00:27 +0300 Subject: [PATCH 08/39] docs: update heatmap and prometheus docs, #10009 --- .../features/datasources/prometheus.md | 2 +- docs/sources/features/panels/heatmap.md | 33 +++++++++++++------ 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/sources/features/datasources/prometheus.md b/docs/sources/features/datasources/prometheus.md index c9bb16441ca..2449119ceda 100644 --- a/docs/sources/features/datasources/prometheus.md +++ b/docs/sources/features/datasources/prometheus.md @@ -50,7 +50,7 @@ Name | Description *Min step* | Set a lower limit for the Prometheus step option. Step controls how big the jumps are when the Prometheus query engine performs range queries. Sadly there is no official prometheus documentation to link to for this very important option. *Resolution* | Controls the step option. Small steps create high-resolution graphs but can be slow over larger time ranges, lowering the resolution can speed things up. `1/2` will try to set step option to generate 1 data point for every other pixel. A value of `1/10` will try to set step option so there is a data point every 10 pixels. *Metric lookup* | Search for metric names in this input field. -*Format as* | **(New in v4.3)** Switch between Table & Time series. Table format will only work in the Table panel. +*Format as* | **(New in v4.3)** Switch between Table, Time series or Heatmap. Table format will only work in the Table panel. Heatmap format is suitable for displaying metrics having histogram type on Heatmap panel. Under the hood, it converts cumulative histogram to regular and sorts series by the bucket bound. ## Templating diff --git a/docs/sources/features/panels/heatmap.md b/docs/sources/features/panels/heatmap.md index e44527f8695..56ffe29f20f 100644 --- a/docs/sources/features/panels/heatmap.md +++ b/docs/sources/features/panels/heatmap.md @@ -56,26 +56,39 @@ Data and bucket options can be found in the `Axes` tab. Data format | Description ------------ | ------------- *Time series* | Grafana does the bucketing by going through all time series values. The bucket sizes & intervals will be determined using the Buckets options. -*Time series buckets* | Each time series already represents a Y-Axis bucket. The time series name (alias) needs to be a numeric value representing the upper interval for the bucket. Grafana does no bucketing so the bucket size options are hidden. +*Time series buckets* | Each time series already represents a Y-Axis bucket. The time series name (alias) needs to be a numeric value representing the upper or lower interval for the bucket. Grafana does no bucketing so the bucket size options are hidden. + +### Bucket bound + +When Data format is *Time series buckets* datasource returns series with names representing bucket bound. But depending +on datasource, a bound may be *upper* or *lower*. This option allows to adjust a bound type. If *Auto* is set, a bound +option will be chosen based on panels' datasource type. ### Bucket Size The Bucket count & size options are used by Grafana to calculate how big each cell in the heatmap is. You can define the bucket size either by count (the first input box) or by specifying a size interval. For the Y-Axis the size interval is just a value but for the X-bucket you can specify a time range in the *Size* input, for example, -the time range `1h`. This will make the cells 1h wide on the X-axis. +the time range `1h`. This will make the cells 1h wide on the X-axis. ### Pre-bucketed data -If you have a data that is already organized into buckets you can use the `Time series buckets` data format. This format requires that your metric query return regular time series and that each time series has a numeric name -that represent the upper or lower bound of the interval. +If you have a data that is already organized into buckets you can use the `Time series buckets` data format. This format +requires that your metric query return regular time series and that each time series has a numeric name that represent +the upper or lower bound of the interval. -The only data source that supports histograms over time is Elasticsearch. You do this by adding a *Histogram* -bucket aggregation before the *Date Histogram*. +There are a number of datasources 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 datasource could be used if it meets the requirements: +returns series with names representing bucket bound or returns sereis sorted by the bound in ascending order. -![](/img/docs/v43/elastic_histogram.png) +With Elasticsearch you control the size of the buckets using the Histogram interval (Y-Axis) and the Date Histogram interval (X-axis). -You control the size of the buckets using the Histogram interval (Y-Axis) and the Date Histogram interval (X-axis). +![Elastic histogram](/img/docs/v43/elastic_histogram.png) + +With Prometheus you can only control X-axis by adjusting *Min step* and *Resolution* options. + +![Prometheus histogram](/img/docs/v51/prometheus_histogram.png) ## Display Options @@ -100,8 +113,8 @@ but include a group by time interval or maxDataPoints limit coupled with an aggr 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 may 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, which currently is the only data source -data supports doing Histogram bucketing on the raw data. +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 & Memory taxing for your browser and could cause hangs and crashes if the number of From 2c7040c246033cfe1ea13df2d8c92bd3cb5860b0 Mon Sep 17 00:00:00 2001 From: Alexander Zobnin Date: Tue, 27 Mar 2018 09:48:19 +0300 Subject: [PATCH 09/39] docs: prometheus ds, remove "new in v4.3" note --- docs/sources/features/datasources/prometheus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/features/datasources/prometheus.md b/docs/sources/features/datasources/prometheus.md index 2449119ceda..af492d435e1 100644 --- a/docs/sources/features/datasources/prometheus.md +++ b/docs/sources/features/datasources/prometheus.md @@ -50,7 +50,7 @@ Name | Description *Min step* | Set a lower limit for the Prometheus step option. Step controls how big the jumps are when the Prometheus query engine performs range queries. Sadly there is no official prometheus documentation to link to for this very important option. *Resolution* | Controls the step option. Small steps create high-resolution graphs but can be slow over larger time ranges, lowering the resolution can speed things up. `1/2` will try to set step option to generate 1 data point for every other pixel. A value of `1/10` will try to set step option so there is a data point every 10 pixels. *Metric lookup* | Search for metric names in this input field. -*Format as* | **(New in v4.3)** Switch between Table, Time series or Heatmap. Table format will only work in the Table panel. Heatmap format is suitable for displaying metrics having histogram type on Heatmap panel. Under the hood, it converts cumulative histogram to regular and sorts series by the bucket bound. +*Format as* | Switch between Table, Time series or Heatmap. Table format will only work in the Table panel. Heatmap format is suitable for displaying metrics having histogram type on Heatmap panel. Under the hood, it converts cumulative histogram to regular and sorts series by the bucket bound. ## Templating From 828dd34507ec952768a0d7d26cc1d4618479df98 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Tue, 27 Mar 2018 20:18:04 +0200 Subject: [PATCH 10/39] docs: update table plugin documentation with value/range to text mapping --- docs/sources/features/panels/singlestat.md | 4 ++-- docs/sources/features/panels/table_panel.md | 11 +++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/panels/singlestat.md b/docs/sources/features/panels/singlestat.md index 510642337ff..b5186818bb0 100644 --- a/docs/sources/features/panels/singlestat.md +++ b/docs/sources/features/panels/singlestat.md @@ -77,11 +77,11 @@ Gauges gives a clear picture of how high a value is in it's context. It's a grea
-### Value to text mapping +### Value/Range to text mapping {{< docs-imagebox img="/img/docs/v45/singlestat-value-mapping.png" class="docs-image--right docs-image--no-shadow">}} -Value to text mapping allows you to translate the value of the summary stat into explicit text. The text will respect all styling, thresholds and customization defined for the value. This can be useful to translate the number of the main Singlestat value into a context-specific human-readable word or message. +Value/Range to text mapping allows you to translate the value of the summary stat into explicit text. The text will respect all styling, thresholds and customization defined for the value. This can be useful to translate the number of the main Singlestat value into a context-specific human-readable word or message.
diff --git a/docs/sources/features/panels/table_panel.md b/docs/sources/features/panels/table_panel.md index a3e56c72960..32f7764e415 100644 --- a/docs/sources/features/panels/table_panel.md +++ b/docs/sources/features/panels/table_panel.md @@ -97,3 +97,14 @@ The column styles allow you control how dates and numbers are formatted. 4. **Thresholds and Coloring**: Specify color mode and thresholds limits. 5. **Type**: The three supported types of types are **Number**, **String** and **Date**. **Unit** and **Decimals**: Specify unit and decimal precision for numbers. **Format**: Specify date format for dates. + +### String +#### Value/Range to text mapping + +> Only available in Grafana v5.1+. + +{{< docs-imagebox img="/img/docs/v51/table-value-mapping.png" class="docs-image--right docs-image--no-shadow">}} + +Value/range to text mapping allows you to translate numeric values into explicit text. The text will respect all styling, thresholds and customization defined for the value. This can be useful to translate the numeric values into a context-specific human-readable word or message. + +
From 51b078fb65bc6c27eb8f3b8737db97d2630bc660 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Tue, 3 Apr 2018 09:47:53 +0200 Subject: [PATCH 11/39] docs: spelling --- docs/sources/features/datasources/mssql.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 26ba6b31ceb..35cb9318a0b 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -38,7 +38,7 @@ Name | Description The database user you specify when you add the data source should only be granted SELECT permissions on the specified database & tables you want to query. Grafana does not validate that the query is safe. The query could include any SQL statement. For example, statements like `DELETE FROM user;` and `DROP TABLE user;` would be -executed. To protect against this we **Highly** recommmend you create a specific MSSQL user with restricted permissions. +executed. To protect against this we **Highly** recommend you create a specific MSSQL user with restricted permissions. Example: @@ -50,6 +50,7 @@ Example: Make sure the user does not get any unwanted privileges from the public role. ## Query Editor + {{< docs-imagebox img="/img/docs/v51/mssql_query_editor.png" class="docs-image--no-shadow" >}} You find the MSSQL query editor in the metrics tab in Graph, Singlestat or Table panel's edit mode. You enter edit mode by clicking the From d39dac10a6aa913d884ee5b1ffa5ef88d845303f Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Mon, 9 Apr 2018 15:19:41 +0200 Subject: [PATCH 12/39] docs: update after #11531 --- docs/sources/administration/provisioning.md | 2 +- .../features/datasources/elasticsearch.md | 18 ++++++++++++------ docs/sources/features/datasources/graphite.md | 13 +++++++++++-- docs/sources/features/datasources/influxdb.md | 14 +++++++++----- docs/sources/features/datasources/opentsdb.md | 3 +-- .../sources/features/datasources/prometheus.md | 2 +- 6 files changed, 35 insertions(+), 17 deletions(-) diff --git a/docs/sources/administration/provisioning.md b/docs/sources/administration/provisioning.md index b43ea68bcd8..ff18677a70b 100644 --- a/docs/sources/administration/provisioning.md +++ b/docs/sources/administration/provisioning.md @@ -100,7 +100,7 @@ datasources: - name: Graphite # datasource type. Required type: graphite - # access mode. direct or proxy. Required + # access mode. proxy or direct (Server or Browser in the UI). Required access: proxy # org id. will default to orgId 1 if not specified orgId: 1 diff --git a/docs/sources/features/datasources/elasticsearch.md b/docs/sources/features/datasources/elasticsearch.md index 6ce17113a9b..9e76bde48d6 100644 --- a/docs/sources/features/datasources/elasticsearch.md +++ b/docs/sources/features/datasources/elasticsearch.md @@ -29,13 +29,19 @@ Name | Description *Name* | The data source name. This is how you refer to the data source in panels & queries. *Default* | Default data source means that it will be pre-selected for new panels. *Url* | The HTTP protocol, IP, and port of your Elasticsearch server. -*Access* | Proxy = access via Grafana backend, Direct = access directly from browser. +*Access* | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. -Proxy access means that the Grafana backend will proxy all requests from the browser, and send them on to the Data Source. This is useful because it can eliminate CORS (Cross Origin Site Resource) issues, as well as eliminate the need to disseminate authentication to the browser. +Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated. -### Direct access +### Server access mode (Default) -If you select direct access you must update your Elasticsearch configuration to allow other domains to access +All requests will be made from the browser to Grafana backend/server which in turn will forward the requests to the data source and by that circumvent possible Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the grafana backend/server if you select this access mode. + +### Browser (Direct) access + +All requests will be made from the browser directly to the data source and may be subject to Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the browser if you select this access mode. + +If you select Browser access you must update your Elasticsearch configuration to allow other domains to access Elasticsearch from the browser. You do this by specifying these to options in your **elasticsearch.yml** config file. ```bash @@ -45,7 +51,7 @@ http.cors.allow-origin: "*" ### Index settings -![](/img/docs/elasticsearch/elasticsearch_ds_details.png) +![Elasticsearch Datasource Details](/img/docs/elasticsearch/elasticsearch_ds_details.png) Here you can specify a default for the `time field` and specify the name of your Elasticsearch index. You can use a time pattern for the index name or a wildcard. @@ -57,7 +63,7 @@ are supported. ## Metric Query editor -![](/img/docs/elasticsearch/query_editor.png) +![Elasticsearch Query Editor](/img/docs/elasticsearch/query_editor.png) The Elasticsearch query editor allows you to select multiple metrics and group by multiple terms or filters. Use the plus and minus icons to the right to add/remove metrics or group by clauses. Some metrics and group by clauses haves options, click the option text to expand the row to view and edit metric or group by options. diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 7c4187da9ae..06a242042a7 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -31,13 +31,22 @@ Name | Description *Name* | The data source name. This is how you refer to the data source in panels & queries. *Default* | Default data source means that it will be pre-selected for new panels. *Url* | The HTTP protocol, IP, and port of your graphite-web or graphite-api install. -*Access* | Proxy = access via Grafana backend, Direct = access directly from browser. +*Access* | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. -Proxy access means that the Grafana backend will proxy all requests from the browser, and send them on to the Data Source. This is useful because it can eliminate CORS (Cross Origin Site Resource) issues, as well as eliminate the need to disseminate authentication details to the browser. +Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated. + +### Server access mode (Default) + +All requests will be made from the browser to Grafana backend/server which in turn will forward the requests to the data source and by that circumvent possible Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the grafana backend/server if you select this access mode. + +### Browser access mode + +All requests will be made from the browser directly to the data source and may be subject to Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the browser if you select this access mode. ## Metric editor ### Navigate metric segments + Click the ``Select metric`` link to start navigating the metric space. One you start you can continue using the mouse or keyboard arrow keys. You can select a wildcard and still continue. diff --git a/docs/sources/features/datasources/influxdb.md b/docs/sources/features/datasources/influxdb.md index 6d0918a0d01..0c89fd6267b 100644 --- a/docs/sources/features/datasources/influxdb.md +++ b/docs/sources/features/datasources/influxdb.md @@ -28,16 +28,20 @@ Name | Description *Name* | The data source name. This is how you refer to the data source in panels & queries. *Default* | Default data source means that it will be pre-selected for new panels. *Url* | The http protocol, ip and port of you influxdb api (influxdb api port is by default 8086) -*Access* | Proxy = access via Grafana backend, Direct = access directly from browser. +*Access* | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. *Database* | Name of your influxdb database *User* | Name of your database user *Password* | Database user's password -### Proxy vs Direct access +Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated. -Proxy access means that the Grafana backend will proxy all requests from the browser. So requests to InfluxDB will be channeled through -`grafana-server`. This means that the URL you specify needs to be accessible from the server you are running Grafana on. Proxy access -mode is also more secure as the username & password will never reach the browser. +### Server access mode (Default) + +All requests will be made from the browser to Grafana backend/server which in turn will forward the requests to the data source and by that circumvent possible Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the grafana backend/server if you select this access mode. + +### Browser access mode + +All requests will be made from the browser directly to the data source and may be subject to Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the browser if you select this access mode. ## Query Editor diff --git a/docs/sources/features/datasources/opentsdb.md b/docs/sources/features/datasources/opentsdb.md index 03795473ff7..8182e82a501 100644 --- a/docs/sources/features/datasources/opentsdb.md +++ b/docs/sources/features/datasources/opentsdb.md @@ -28,11 +28,10 @@ Name | Description *Name* | The data source name. This is how you refer to the data source in panels & queries. *Default* | Default data source means that it will be pre-selected for new panels. *Url* | The http protocol, ip and port of you opentsdb server (default port is usually 4242) -*Access* | Proxy = access via Grafana backend, Direct = access directly from browser. +*Access* | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. *Version* | Version = opentsdb version, either <=2.1 or 2.2 *Resolution* | Metrics from opentsdb may have datapoints with either second or millisecond resolution. - ## Query editor Open a graph in edit mode by click the title. Query editor will differ if the datasource has version <=2.1 or = 2.2. diff --git a/docs/sources/features/datasources/prometheus.md b/docs/sources/features/datasources/prometheus.md index af492d435e1..2801991856e 100644 --- a/docs/sources/features/datasources/prometheus.md +++ b/docs/sources/features/datasources/prometheus.md @@ -30,7 +30,7 @@ Name | Description *Name* | The data source name. This is how you refer to the data source in panels & queries. *Default* | Default data source means that it will be pre-selected for new panels. *Url* | The http protocol, ip and port of you Prometheus server (default port is usually 9090) -*Access* | Proxy = access via Grafana backend, Direct = access directly from browser. +*Access* | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. *Basic Auth* | Enable basic authentication to the Prometheus data source. *User* | Name of your Prometheus user *Password* | Database user's password From 1232745e89c4f1643b3b56a119e5bb097a6136a9 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Wed, 11 Apr 2018 20:40:49 +0200 Subject: [PATCH 13/39] docs: fix typo of default port for mssql Fixes #11562 --- docs/sources/features/datasources/mssql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 35cb9318a0b..47ce7bb83a8 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -28,7 +28,7 @@ Name | Description ------------ | ------------- *Name* | The data source name. This is how you refer to the data source in panels & queries. *Default* | Default data source means that it will be pre-selected for new panels. -*Host* | The IP address/hostname and optional port of your MSSQL instance. If port is omitted, default 1443 will be used. +*Host* | The IP address/hostname and optional port of your MSSQL instance. If port is omitted, default 1433 will be used. *Database* | Name of your MSSQL database. *User* | Database user's login/username *Password* | Database user's password From fa95297e6a4794b44b6d45d7c920ca3d1e0a3ac2 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 13 Apr 2018 10:58:29 +0200 Subject: [PATCH 14/39] docs: update default annotation limit when querying api Needed due to closing #11569 --- docs/sources/http_api/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/http_api/annotations.md b/docs/sources/http_api/annotations.md index 038ff085674..824571422b0 100644 --- a/docs/sources/http_api/annotations.md +++ b/docs/sources/http_api/annotations.md @@ -32,7 +32,7 @@ Query Parameters: - `from`: epoch datetime in milliseconds. Optional. - `to`: epoch datetime in milliseconds. Optional. -- `limit`: number. Optional - default is 10. Max limit for results returned. +- `limit`: number. Optional - default is 100. Max limit for results returned. - `alertId`: number. Optional. Find annotations for a specified alert. - `dashboardId`: number. Optional. Find annotations that are scoped to a specific dashboard - `panelId`: number. Optional. Find annotations that are scoped to a specific panel From aa59843902b10bafaca1908cce61565f2f482ddf Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 13 Apr 2018 11:36:40 +0200 Subject: [PATCH 15/39] docs: update mssql with azure sql database support --- docs/sources/features/datasources/mssql.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 47ce7bb83a8..0e3d245f28f 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -1,7 +1,7 @@ +++ title = "Using Microsoft SQL Server in Grafana" description = "Guide for using Microsoft SQL Server in Grafana" -keywords = ["grafana", "MSSQL", "Microsoft", "SQL", "guide"] +keywords = ["grafana", "MSSQL", "Microsoft", "SQL", "guide", "Azure SQL Database"] type = "docs" [menu.docs] name = "Microsoft SQL Server" @@ -13,7 +13,7 @@ weight = 7 > Only available in Grafana v5.1+. -Grafana ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer. +Grafana ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer, including Microsoft Azure SQL Database. ## Adding the data source From 9c492bd774626f99f5398aadfa97334e93e7ed69 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 13 Apr 2018 15:53:45 +0200 Subject: [PATCH 16/39] docs: add mssql provisioning example --- docs/sources/features/datasources/mssql.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 0e3d245f28f..0310683320e 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -529,3 +529,23 @@ EXEC dbo.sp_test_datetime @from, @to Time series queries should work in alerting conditions. Table formatted queries are not yet supported in alert rule conditions. + +## Configure datasource with provisioning + +It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) + +Here are some provisioning examples for this datasource. + +```yaml +apiVersion: 1 + +datasources: + - name: MSSQL + type: mssql + url: localhost:1433 + database: grafana + user: grafana + secureJsonData: + password: "Password!" + +``` From abed9c055f5d5154d6bc43b0b11069d3de524c56 Mon Sep 17 00:00:00 2001 From: Leonard Gram Date: Thu, 22 Mar 2018 17:33:53 +0100 Subject: [PATCH 17/39] docs: new docker image in Grafana 5.1.0. --- docs/sources/installation/docker.md | 124 +++++++++++++++++++++------- 1 file changed, 94 insertions(+), 30 deletions(-) diff --git a/docs/sources/installation/docker.md b/docs/sources/installation/docker.md index f246bd55d33..d6f3ae16466 100644 --- a/docs/sources/installation/docker.md +++ b/docs/sources/installation/docker.md @@ -18,28 +18,6 @@ Grafana is very easy to install and run using the official docker container. $ docker run -d -p 3000:3000 grafana/grafana ``` -All Grafana configuration settings can be defined using environment -variables, this is especially useful when using the above container. - -## Docker volumes & ENV config - -The Docker container exposes two volumes, the sqlite3 database in the -folder `/var/lib/grafana` and configuration files is in `/etc/grafana/` -folder. You can map these volumes to host folders when you start the -container: - -```bash -$ docker run -d -p 3000:3000 \ - -v /var/lib/grafana:/var/lib/grafana \ - -e "GF_SECURITY_ADMIN_PASSWORD=secret" \ - grafana/grafana -``` - -In the above example I map the data folder and sets a configuration option via -an `ENV` instruction. - -See the [docker volumes documentation](https://docs.docker.com/engine/admin/volumes/volumes/) if you want to create a volume to use with the Grafana docker image instead of a bind mount (binding to a directory in the host system). - ## Configuration All options defined in conf/grafana.ini can be overridden using environment @@ -56,15 +34,24 @@ $ docker run \ grafana/grafana ``` -You can use your own grafana.ini file by using environment variable `GF_PATHS_CONFIG`. - The back-end web server has a number of configuration options. Go to the [Configuration]({{< relref "configuration.md" >}}) page for details on all those options. +## Running a Specific Version of Grafana + +```bash +# specify right tag, e.g. 5.1.0 - see Docker Hub for available tags +$ docker run \ + -d \ + -p 3000:3000 \ + --name grafana \ + grafana/grafana:5.1.0 +``` + ## Installing Plugins for Grafana -Pass the plugins you want installed to docker with the `GF_INSTALL_PLUGINS` environment variable as a comma separated list. This will pass each plugin name to `grafana-cli plugins install ${plugin}`. +Pass the plugins you want installed to docker with the `GF_INSTALL_PLUGINS` environment variable as a comma separated list. This will pass each plugin name to `grafana-cli plugins install ${plugin}` and install them when Grafana starts. ```bash docker run \ @@ -75,15 +62,22 @@ docker run \ grafana/grafana ``` -## Running a Specific Version of Grafana +## Building a custom Grafana image with pre-installed plugins +In the [grafana-docker](https://github.com/grafana/grafana-docker/) there is a folder called `custom/` which includes a `Dockerfile` that can be used to build a custom Grafana image. It accepts `GRAFANA_VERSION` and `GF_INSTALL_PLUGINS` as build arguments. + +Example of how to build and run: ```bash -# specify right tag, e.g. 4.5.2 - see Docker Hub for available tags -$ docker run \ +cd custom +docker build -t grafana:latest-with-plugins \ + --build-arg "GRAFANA_VERSION=latest" \ + --build-arg "GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource" . + +docker run \ -d \ -p 3000:3000 \ - --name grafana \ - grafana/grafana:5.0.2 + --name=grafana \ + grafana:latest-with-plugins ``` ## Configuring AWS Credentials for CloudWatch Support @@ -108,3 +102,73 @@ Supported variables: - `GF_AWS_${profile}_ACCESS_KEY_ID`: AWS access key ID (required). - `GF_AWS_${profile}_SECRET_ACCESS_KEY`: AWS secret access key (required). - `GF_AWS_${profile}_REGION`: AWS region (optional). + +## Grafana container with persistent storage (recommended) + +```bash +# create a persistent volume for your data in /var/lib/grafana (database and plugins) +docker volume create grafana-storage + +# start grafana +docker run \ + -d \ + -p 3000:3000 \ + --name=grafana \ + -v grafana-storage:/var/lib/grafana \ + grafana/grafana +``` + +## Grafana container using bind mounts + +You may want to run Grafana in Docker but use folders on your host for the database or configuration. When doing so it becomes important to start the container with a user that is able to access and write to the folder you map into the container. + +```bash +mkdir data # creates a folder for your data +ID=$(id -u) # saves your user id in the ID variable + +# starts grafana with your user id and using the data folder +docker run -d --user $ID --volume "$PWD/data:/var/lib/grafana" -p 3000:3000 grafana/grafana:5.1.0 +``` + +## Migration from a previous version of the docker container to 5.1 or later + +In 5.1 we switched the id of the grafana user. Unfortunately this means that files created prior to 5.1 won't have the correct permissions for later versions. We made this change so that it would be easier for you to control what user Grafana is executed as (see examples below). + +Version | User | User ID +--------|---------|--------- +< 5.1 | grafana | 104 +>= 5.1 | grafana | 472 + +There are two possible solutions to this problem. Either you start the new container as the root user and change ownership from `104` to `472` or you start the upgraded container as user `104`. + +### Running docker as a different user + +```bash +docker run --user 104 --volume "" grafana/grafana:5.1.0 +``` + +#### docker-compose.yml with custom user +```yaml +version: "2" + +services: + grafana: + image: grafana/grafana:5.1.0 + ports: + - 3000:3000 + user: "104" +``` + +### Modifying permissions + +The commands below will run bash inside the Grafana container with your volume mapped in. This makes it possible to modify the file ownership to match the new container. Always be careful when modifying permissions. + +```bash +$ docker run -ti --user root --volume "" --entrypoint bash grafana/grafana:5.1.0 + +# in the container you just started: +chown -R root:root /etc/grafana && \ + chmod -R a+r /etc/grafana && \ + chown -R grafana:grafana /var/lib/grafana && \ + chown -R grafana:grafana /usr/share/grafana +``` From ad22e20ecd7f1049b7525e6fd130cc01044cb6c2 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Tue, 17 Apr 2018 00:06:25 +0200 Subject: [PATCH 18/39] docs: update postgres macro functions documentation In addition to closing #11578 --- docs/sources/features/datasources/postgres.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index e90ba79b686..fa4e5d241ca 100644 --- a/docs/sources/features/datasources/postgres.md +++ b/docs/sources/features/datasources/postgres.md @@ -57,12 +57,12 @@ Macro example | Description ------------ | ------------- *$__time(dateColumn)* | Will be replaced by an expression to rename the column to `time`. For example, *dateColumn as time* *$__timeEpoch(dateColumn)* | Will be replaced by an expression to rename the column to `time` and converting the value to unix timestamp. For example, *extract(epoch from dateColumn) as time* -*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *extract(epoch from dateColumn) BETWEEN 1494410783 AND 1494497183* -*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *to_timestamp(1494410783)* -*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *to_timestamp(1494497183)* +*$__timeFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name. For example, *dateColumn BETWEEN '2017-05-10T10:06:23Z' AND '2017-05-10T10:06:23Z'* +*$__timeFrom()* | Will be replaced by the start of the currently active time selection. For example, *'2017-05-10T10:06:23Z'* +*$__timeTo()* | Will be replaced by the end of the currently active time selection. For example, *'2017-05-10T10:06:23Z'* *$__timeGroup(dateColumn,'5m')* | Will be replaced by an expression usable in GROUP BY clause. For example, *(extract(epoch from dateColumn)/300)::bigint*300 AS time* *$__timeGroup(dateColumn,'5m', 0)* | Same as above but with a fill parameter so all null values will be converted to the fill value (all null values would be set to zero using this example). -*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn > 1494410783 AND dateColumn < 1494497183* +*$__unixEpochFilter(dateColumn)* | Will be replaced by a time range filter using the specified column name with times represented as unix timestamp. For example, *dateColumn >= 1494410783 AND dateColumn <= 1494497183* *$__unixEpochFrom()* | Will be replaced by the start of the currently active time selection as unix timestamp. For example, *1494410783* *$__unixEpochTo()* | Will be replaced by the end of the currently active time selection as unix timestamp. For example, *1494497183* From d30835f64810df0c31afd95f997be8b3a54d4875 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Tue, 17 Apr 2018 17:22:25 +0200 Subject: [PATCH 19/39] docs: update provisioning documentation In addition to closing #10883 --- docs/sources/administration/provisioning.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/sources/administration/provisioning.md b/docs/sources/administration/provisioning.md index 79b401f6cbf..42a0fffeda1 100644 --- a/docs/sources/administration/provisioning.md +++ b/docs/sources/administration/provisioning.md @@ -197,13 +197,22 @@ providers: folder: '' type: file disableDeletion: false - editable: false options: path: /var/lib/grafana/dashboards ``` When Grafana starts, it will update/insert all dashboards available in the configured path. Then later on poll that path and look for updated json files and insert those update/insert those into the database. +#### Making changes to a provisioned dashboard + +It's possible to make changes to a provisioned dashboard in Grafana UI, but there's currently no possibility to automatically save the changes back to the provisioning source. +However, if you make changes to a provisioned dashboard you can `Save` the dashboard which will bring up a *Cannot save provisioned dashboard* dialog like seen in the screenshot below. +Here available options will let you `Copy JSON to Clipboard` and/or `Save JSON to file` which can help you synchronize your dashboard changes back to the provisioning source. + +Note: The JSON shown in input field and when using `Copy JSON to Clipboard` and/or `Save JSON to file` will have the `id` field automatically removed to aid the provisioning workflow. + +{{< docs-imagebox img="/img/docs/v51/provisioning_cannot_save_dashboard.png" max-width="500px" class="docs-image--no-shadow" >}} + ### Reuseable Dashboard Urls If the dashboard in the json file contains an [uid](/reference/dashboard/#json-fields), Grafana will force insert/update on that uid. This allows you to migrate dashboards betweens Grafana instances and provisioning Grafana from configuration without breaking the urls given since the new dashboard url uses the uid as identifier. From 24ae9cef36a8367ca1b55961205c5851521b90d8 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Tue, 17 Apr 2018 19:41:34 +0200 Subject: [PATCH 20/39] docs: describes new variable formatting syntax Fixes #11388 Ref #11141 --- docs/sources/reference/templating.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index 6dbc9cc9d11..f1ca9c226a6 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -36,6 +36,27 @@ interpolation the variable value might be **escaped** in order to conform to the For example, a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific documentation article for details on value escaping during interpolation. +### Advanced Formatting Options + +In Grafana 5.0, an additional option was added to control the formatting of the interpolation. + +Syntax: `${var_name:option}` + +Filter Option | Example | Raw | Interpolated | Description +------------ | ------------- | ------------- | ------------- | ------------- +`glob` | ${servers:glob} | `'test1', 'test2'` | `{test1,test2}` | (Default) Formats multi-value variable into a glob (for Graphite queries) +`regex` | ${servers:regex} | `'test.', 'test2'` | `(test\\.|test2)` | Formats multi-value variable into a regex string +`pipe` | ${servers:pipe} | `'test.', 'test2'` | `test.|test2` | Formats multi-value variable into a pipe-separated string +`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string (requires Grafana 5.1) +`distributed`| ${servers:distributed} | `'test1', 'test2'` | `test1,servers=test2` | Formats multi-value variable in custom format for OpenTSDB. +`lucene`| ${servers:lucene} | `'test', 'test2'` | `("test" OR "test2")` | Formats multi-value variable as a lucene expression. + +Test the formatting options on the [Grafana Play site](http://play.grafana.org/d/cJtIfcWiz/template-variable-formatting-options?orgId=1). + +If any invalid formatting option is specified, then `glob` is the default/fallback option. + +An alternative syntax is `[[var_name:option]]`. + ### Variable options A variable is presented as a dropdown select box at the top of the dashboard. It has a current value and a set of **options**. The **options** From 120a86ecf996fe340c369c3e125a0ae61a87e35b Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Tue, 17 Apr 2018 20:02:26 +0200 Subject: [PATCH 21/39] docs: graphite template variables for tag queries ref #11388 and ref #9911 and ref #10366 --- docs/sources/features/datasources/graphite.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 97233572878..7a768b4a579 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -89,6 +89,18 @@ being displayed in your dashboard. Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables. +Graphite 1.1 introduced tags and Grafana added support for Graphite queries with tags in version 5.0. To create a variable using tag values, then you need to use the Grafana functions `tags` and `tag_values`. + +Query | Description +------------ | ------------- +*tags()* | Returns all tags. +*tags(server=~backend\*)* | Returns only tags that occur in series matching the filter expression. +*tag_values(server)* | Return tag values for the specified tag. +*tag_values(server, server=~backend*)* | Returns filtered tag values that occur for the specified tag in series matching those expressions. +*tag_values(server, server=~backend*, app=$apps)* | Multiple filter expressions and expressions can contain other variables. + +For more details, see the [Graphite docs on the autocomplete api for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support). + ### Query variable The query you specify in the query field should be a metric find type of query. For example, a query like `prod.servers.*` will fill the @@ -97,6 +109,10 @@ variable with all possible values that exist in the wildcard position. You can also create nested variables that use other variables in their definition. For example `apps.$app.servers.*` uses the variable `$app` in its query definition. +### Query Variables in Tag Queries + +Multi-value variables in tag queries use the syntax introduced in Grafana 5.0 for variables: `{var:regex}`. Non-tag queries will use the default glob formatting for multi-value variables. Checkout the [Advanced Formatting Options section in the Templating]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. + ### Variable usage You can use a variable in a metric node path or as a parameter to a function. From ab4f8c273d75cd376baabed75fe774ccc2204470 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Wed, 18 Apr 2018 14:40:09 +0200 Subject: [PATCH 22/39] docs: describes variable formatting options csv option in postgres/mysql docs and the regex option in the graphite docs --- docs/sources/features/datasources/graphite.md | 19 ++++++++----------- docs/sources/features/datasources/mysql.md | 10 +++++++++- docs/sources/features/datasources/postgres.md | 17 ++++++++++++----- docs/sources/reference/templating.md | 2 +- 4 files changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 7a768b4a579..161d174203e 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -38,13 +38,13 @@ Proxy access means that the Grafana backend will proxy all requests from the bro ## Metric editor ### Navigate metric segments + Click the ``Select metric`` link to start navigating the metric space. One you start you can continue using the mouse or keyboard arrow keys. You can select a wildcard and still continue. {{< docs-imagebox img="/img/docs/v45/graphite_query1_still.png" animated-gif="/img/docs/v45/graphite_query1.gif" >}} - ### Functions Click the plus icon to the right to add a function. You can search for the function or select it from the menu. Once @@ -55,7 +55,6 @@ by the x icon. {{< docs-imagebox img="/img/docs/v45/graphite_query2_still.png" animated-gif="/img/docs/v45/graphite_query2.gif" >}} - ### Optional parameters Some functions like aliasByNode support an optional second argument. To add this parameter specify for example 3,-2 as the first parameter and the function editor will adapt and move the -2 to a second parameter. To remove the second optional parameter just click on it and leave it blank and the editor will remove it. @@ -63,7 +62,6 @@ Some functions like aliasByNode support an optional second argument. To add this {{< docs-imagebox img="/img/docs/v45/graphite_query3_still.png" animated-gif="/img/docs/v45/graphite_query3.gif" >}} - ### Nested Queries You can reference queries by the row “letter” that they’re on (similar to Microsoft Excel). If you add a second query to a graph, you can reference the first query simply by typing in #A. This provides an easy and convenient way to build compounded queries. @@ -71,7 +69,6 @@ You can reference queries by the row “letter” that they’re on (similar to {{< docs-imagebox img="/img/docs/v45/graphite_nested_queries_still.png" animated-gif="/img/docs/v45/graphite_nested_queries.gif" >}} - ## Point consolidation All Graphite metrics are consolidated so that Graphite doesn't return more data points than there are pixels in the graph. By default, @@ -97,7 +94,7 @@ Query | Description *tags(server=~backend\*)* | Returns only tags that occur in series matching the filter expression. *tag_values(server)* | Return tag values for the specified tag. *tag_values(server, server=~backend*)* | Returns filtered tag values that occur for the specified tag in series matching those expressions. -*tag_values(server, server=~backend*, app=$apps)* | Multiple filter expressions and expressions can contain other variables. +*tag_values(server, server=~backend*, app=${apps:regex})* | Multiple filter expressions and expressions can contain other variables. For more details, see the [Graphite docs on the autocomplete api for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support). @@ -109,14 +106,10 @@ variable with all possible values that exist in the wildcard position. You can also create nested variables that use other variables in their definition. For example `apps.$app.servers.*` uses the variable `$app` in its query definition. -### Query Variables in Tag Queries - -Multi-value variables in tag queries use the syntax introduced in Grafana 5.0 for variables: `{var:regex}`. Non-tag queries will use the default glob formatting for multi-value variables. Checkout the [Advanced Formatting Options section in the Templating]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. - -### Variable usage +### Variable Usage You can use a variable in a metric node path or as a parameter to a function. -![](/img/docs/v2/templated_variable_parameter.png) +![variable](/img/docs/v2/templated_variable_parameter.png) There are two syntaxes: @@ -129,6 +122,10 @@ the second syntax in expressions like `my.server[[serverNumber]].count`. Example: [Graphite Templated Dashboard](http://play.grafana.org/dashboard/db/graphite-templated-nested) +### Variable Usage in Tag Queries + +Multi-value variables in tag queries use the advanced formatting syntax introduced in Grafana 5.0 for variables: `{var:regex}`. Non-tag queries will use the default glob formatting for multi-value variables. Checkout the [Advanced Formatting Options section in the Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation diff --git a/docs/sources/features/datasources/mysql.md b/docs/sources/features/datasources/mysql.md index 8eaab86a906..1920759711c 100644 --- a/docs/sources/features/datasources/mysql.md +++ b/docs/sources/features/datasources/mysql.md @@ -200,6 +200,14 @@ WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ASC ``` +#### Disabling Quoting for Multi-value Variables + +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'. Do disable quoting, use the csv formatting option for variables: + +`${servers:csv}` + +Read more about variable formatting options in the [Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. @@ -242,4 +250,4 @@ datasources: database: grafana user: grafana password: password -``` \ No newline at end of file +``` diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index 405e8a7fdec..bc684a8f168 100644 --- a/docs/sources/features/datasources/postgres.md +++ b/docs/sources/features/datasources/postgres.md @@ -82,7 +82,7 @@ You can control the name of the Table panel columns by using regular `as ` SQL c The resulting table panel: -![](/img/docs/v46/postgres_table.png) +![postgres table](/img/docs/v46/postgres_table.png) ### Time series queries @@ -190,6 +190,14 @@ WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ASC ``` +#### Disabling Quoting for Multi-value Variables + +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'. Do disable quoting, use the csv formatting option for variables: + +`${servers:csv}` + +Read more about variable formatting options in the [Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. @@ -218,9 +226,9 @@ tags | Optional field name to use for event tags as a comma separated string. Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule conditions. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. @@ -237,5 +245,4 @@ datasources: password: "Password!" jsonData: sslmode: "disable" # disable/require/verify-ca/verify-full - -``` \ No newline at end of file +``` diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index f1ca9c226a6..c7666a169d8 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -38,7 +38,7 @@ documentation article for details on value escaping during interpolation. ### Advanced Formatting Options -In Grafana 5.0, an additional option was added to control the formatting of the interpolation. +In Grafana 5.0, a new syntax for variables was introduced to control the formatting of the interpolation. Syntax: `${var_name:option}` From cec9634f4ac26c79f8d97a8a6efb053f326cdca3 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Wed, 18 Apr 2018 14:52:36 +0200 Subject: [PATCH 23/39] fix typo --- docs/sources/features/panels/graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/features/panels/graph.md b/docs/sources/features/panels/graph.md index bc0f896775e..5a010ceca40 100644 --- a/docs/sources/features/panels/graph.md +++ b/docs/sources/features/panels/graph.md @@ -126,7 +126,7 @@ It is just the sum of all data points received by Grafana. ### Hide series -Hide series when all values of a serie from a metric query are of a specific value: +Hide series when all values of a series from a metric query are of a specific value: - **With only nulls** - Value=*null* (default unchecked) - **With only zeros** - Value=*zero* (default unchecked) From 250f85b9bdd23da0f7d34715015921dc65691ba9 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Fri, 13 Apr 2018 12:20:09 +0200 Subject: [PATCH 24/39] docs: what's new in v5.1 draft --- docs/sources/guides/whats-new-in-v5-1.md | 126 +++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 docs/sources/guides/whats-new-in-v5-1.md diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md new file mode 100644 index 00000000000..f1fc036413a --- /dev/null +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -0,0 +1,126 @@ ++++ +title = "What's New in Grafana v5.1" +description = "Feature & improvement highlights for Grafana v5.1" +keywords = ["grafana", "new", "documentation", "5.1"] +type = "docs" +[menu.docs] +name = "Version 5.1" +identifier = "v5.1" +parent = "whatsnew" +weight = -7 ++++ + +# What's New in Grafana v5.1 + +Grafana v5.1 brings new features, many enhancements and bug fixes. This article will detail the major new features and enhancements. + +* [Scrolling]({{< relref "#scrolling" >}}) +* [Improved docker image]({{< relref "#improved-docker-image-breaking-change" >}}) with a breaking change! +* [Improved workflow for provisioned dashboards]({{< relref "#improved-workflow-for-provisioned-dashboards" >}}) +* [New template variable interpolation syntax]({{< relref "#new-template-variable-interpolation-syntax" >}}) +* [Alerting]({{< relref "#alerting" >}}) +* [Datasources]({{< relref "#datasources" >}}) Enhancements to Prometheus, Cloudwatch, PostgreSQL and MySQL. This release also adds support for [Microsft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! +* [Dashboard & Panels]({{< relref "#dashboard-panels" >}}) Enhancements to Graph and Table panels and improved control for adding new panels. + +## Scrolling + + + +## Improved docker image (breaking change) + +Grafana v5.1 brings an improved official docker image which should make it easier to run and use the Grafana docker image and at the same time give more control to the user how to use/run it. + +We've switched the id of the grafana user running Grafana inside a docker container. Unfortunately this means that files created prior to 5.1 won't have the correct permissions for later versions and thereby this introduces a breaking change. +We made this change so that it would be easier for you to control what user Grafana is executed as (see examples below). + +Version | User | User ID +--------|---------|--------- +< 5.1 | grafana | 104 +>= 5.1 | grafana | 472 + +Please read the [updated documentation](/installation/docker/#migration-from-a-previous-version-of-the-docker-container-to-5-1-or-later) which includes migration instructions and more information. + +## Improved workflow for provisioned dashboards + +{{< docs-imagebox img="/img/docs/v51/provisioning_cannot_save_dashboard.png" max-width="800px" class="docs-image--right" >}} + +Grafana v5.1 brings an improved workflow for provisioned dashboards: + +* A populated `id` property in JSON is now automatically removed when provisioning dashboards. +* When making changes to a provisioned dashboard you can `Save` the dashboard which now will bring up a *Cannot save provisioned dashboard* dialog like seen in the screenshot to the right. + + +Available options in the dialog will let you `Copy JSON to Clipboard` and/or `Save JSON to file` which can help you synchronize your dashboard changes back to the provisioning source. +More information in the [Provisioning documentation](/features/datasources/prometheus/). + +
+ +## New template variable interpolation syntax + + +## Alerting + +New enhancements includes support for retries on failed alert queries and updating correct state when pausing/unpausing alerts. + +## Datasources + +### Prometheus + +New enhancements includes support for Prometheus histograms in the heatmap panel and autocomplete of template variables query editor. More information in the [Prometheus data source documentation](/features/datasources/prometheus/). + +### Cloudwatch + +New enhancements includes support for high resolution metrics and dimension filtering. More information in the [Cloudwatch data source documentation](/features/datasources/cloudwatch/). + +### PostgreSQL + +New enhancement includes support for filling in values for missing intervals and better precision handling and data type support for time columns. More information in the [PostgreSQL data source documentation](/features/datasources/postgres/#time-series-queries). + +### MySQL + +New enhancements includes support for filling in values for missing intervals, better precision handling and data type support for time columns and any column except time and metric is now treated as a value column. More information in the [MySQL data source documentation](/features/datasources/mysql/#time-series-queries). + +### Microsoft SQL Server + +{{< docs-imagebox img="/img/docs/v51/mssql_query_editor_showcase.png" max-width= "800px" class="docs-image--right" >}} + +Grafana v5.1 now ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer, including Microsoft Azure SQL Database. Have logs or metric data in MSSQL? You can now visualize that data and +define alert rules on it like any of our other data sources. + +Same enhancements as described for PostgreSQL and MySQL are included in the MSSQL datasource. + +Please read [Using Microsoft SQL Server in Grafana documentation](/features/datasources/mssql/) for more detailed information on how to get started and use it. + +
+ +## Dashboard & Panels + +### Adding new panels to a dashboard + +{{< docs-imagebox img="/img/docs/v51/dashboard_add_panel.png" max-width= "800px" class="docs-image--right" >}} + +The control for adding new panels to dashboards now includes functionality to search for the type of panel +you want to add. Further, the control has tabs separating functionality for adding and pasting panels: + +* Under the `Add` tab you'll find all of the panel types that you can add. +* Under the `Paste` tab you can paste a panel that you've earlier copied. + +By copying a panel in a dashboard, see screenshot below, it will be available in the `Paste` tab in *any* dashboard. +This should make it more intuitive to copy/paste panels between dashboards. + +![Copy panel](/img/docs/v51/dashboard_panel_copy.png) + +
+ +### Graph Panel + +New enhancements includes support for multiple series stacking in histogram mode, thresholds for right Y axis, aligning left and right Y-axes to one level and additional units. More information in the [Graph panel documentation](/features/panels/graph/). + +### Table Panel + +New enhancements includes support for mapping a numeric value/range to text and additional units. More information in the [Table panel documentation](/features/panels/table_panel/#string). + +## Changelog + +Checkout the [CHANGELOG.md](https://github.com/grafana/grafana/blob/master/CHANGELOG.md) file for a complete list +of new features, changes, and bug fixes. \ No newline at end of file From 6737f79331ca280e1e3793cee080a87c8b16de7f Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 19 Apr 2018 13:25:16 +0200 Subject: [PATCH 25/39] docs: improve what's new in v5.1 --- docs/sources/guides/whats-new-in-v5-1.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index f1fc036413a..d8697e63f8d 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -20,7 +20,7 @@ Grafana v5.1 brings new features, many enhancements and bug fixes. This article * [New template variable interpolation syntax]({{< relref "#new-template-variable-interpolation-syntax" >}}) * [Alerting]({{< relref "#alerting" >}}) * [Datasources]({{< relref "#datasources" >}}) Enhancements to Prometheus, Cloudwatch, PostgreSQL and MySQL. This release also adds support for [Microsft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! -* [Dashboard & Panels]({{< relref "#dashboard-panels" >}}) Enhancements to Graph and Table panels and improved control for adding new panels. +* [Dashboards & Panels]({{< relref "#dashboards-panels" >}}) Improved adding panels to dashboards and enhancements to Graph and Table panels. ## Scrolling @@ -93,22 +93,20 @@ Please read [Using Microsoft SQL Server in Grafana documentation](/features/data
-## Dashboard & Panels +## Dashboards & Panels -### Adding new panels to a dashboard +### Adding new panels to dashboards {{< docs-imagebox img="/img/docs/v51/dashboard_add_panel.png" max-width= "800px" class="docs-image--right" >}} -The control for adding new panels to dashboards now includes functionality to search for the type of panel -you want to add. Further, the control has tabs separating functionality for adding and pasting panels: +The control for adding new panels to dashboards have got some enhancements and now includes functionality to search for the type of panel +you want to add. Further, the control has tabs separating functionality for adding new panels and pasting +copied panels. -* Under the `Add` tab you'll find all of the panel types that you can add. -* Under the `Paste` tab you can paste a panel that you've earlier copied. +By copying a panel in a dashboard it will be displayed in the `Paste` tab in *any* dashboard and allows you to paste the +copied panel into the current dashboard. -By copying a panel in a dashboard, see screenshot below, it will be available in the `Paste` tab in *any* dashboard. -This should make it more intuitive to copy/paste panels between dashboards. - -![Copy panel](/img/docs/v51/dashboard_panel_copy.png) +{{< docs-imagebox img="/img/docs/v51/dashboard_panel_copy.png" max-width= "300px" >}}
From 601a1d9b92c15cd92e26ade42823cfcd8f7888ae Mon Sep 17 00:00:00 2001 From: bergquist Date: Thu, 19 Apr 2018 13:33:33 +0200 Subject: [PATCH 26/39] docs: more info prometheus heapmap to whats new --- docs/sources/guides/whats-new-in-v5-1.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index d8697e63f8d..4d0824aba1b 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -66,7 +66,9 @@ New enhancements includes support for retries on failed alert queries and updati ### Prometheus -New enhancements includes support for Prometheus histograms in the heatmap panel and autocomplete of template variables query editor. More information in the [Prometheus data source documentation](/features/datasources/prometheus/). +The Prometheus datasource now support transforming Prometheus histograms to the heatmap panel. Prometheus histogram is a powerful feature, and we are really happy to finally allow our users to render those as heatmaps. + +Prometheus query editor also got support for autocomplete of template variables. More information in the [Prometheus data source documentation](/features/datasources/prometheus/). ### Cloudwatch From b4a77d49b4b0c7399cea6e7ca386f7892a631b05 Mon Sep 17 00:00:00 2001 From: bergquist Date: Thu, 19 Apr 2018 13:39:02 +0200 Subject: [PATCH 27/39] docs: whats new reduce content a little bit and highlight mssql and prom heatmap --- docs/sources/guides/whats-new-in-v5-1.md | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index 4d0824aba1b..3ab792de1bf 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -18,8 +18,8 @@ Grafana v5.1 brings new features, many enhancements and bug fixes. This article * [Improved docker image]({{< relref "#improved-docker-image-breaking-change" >}}) with a breaking change! * [Improved workflow for provisioned dashboards]({{< relref "#improved-workflow-for-provisioned-dashboards" >}}) * [New template variable interpolation syntax]({{< relref "#new-template-variable-interpolation-syntax" >}}) -* [Alerting]({{< relref "#alerting" >}}) -* [Datasources]({{< relref "#datasources" >}}) Enhancements to Prometheus, Cloudwatch, PostgreSQL and MySQL. This release also adds support for [Microsft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! +* [Heatmap support for Prometehus]({{< relref "#prometheus" >}}) +* [Microsft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! * [Dashboards & Panels]({{< relref "#dashboards-panels" >}}) Improved adding panels to dashboards and enhancements to Graph and Table panels. ## Scrolling @@ -57,32 +57,21 @@ More information in the [Provisioning documentation](/features/datasources/prome ## New template variable interpolation syntax - -## Alerting - -New enhancements includes support for retries on failed alert queries and updating correct state when pausing/unpausing alerts. - -## Datasources - -### Prometheus +## Prometheus The Prometheus datasource now support transforming Prometheus histograms to the heatmap panel. Prometheus histogram is a powerful feature, and we are really happy to finally allow our users to render those as heatmaps. Prometheus query editor also got support for autocomplete of template variables. More information in the [Prometheus data source documentation](/features/datasources/prometheus/). -### Cloudwatch - -New enhancements includes support for high resolution metrics and dimension filtering. More information in the [Cloudwatch data source documentation](/features/datasources/cloudwatch/). - -### PostgreSQL +## PostgreSQL New enhancement includes support for filling in values for missing intervals and better precision handling and data type support for time columns. More information in the [PostgreSQL data source documentation](/features/datasources/postgres/#time-series-queries). -### MySQL +## MySQL New enhancements includes support for filling in values for missing intervals, better precision handling and data type support for time columns and any column except time and metric is now treated as a value column. More information in the [MySQL data source documentation](/features/datasources/mysql/#time-series-queries). -### Microsoft SQL Server +## Microsoft SQL Server {{< docs-imagebox img="/img/docs/v51/mssql_query_editor_showcase.png" max-width= "800px" class="docs-image--right" >}} From cc3418f6a3fa373c98cb7bbaac09ee4fbe025a3f Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 19 Apr 2018 13:44:37 +0200 Subject: [PATCH 28/39] docs: what's new Improved scrolling experience --- docs/sources/guides/whats-new-in-v5-1.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index 3ab792de1bf..c113be10819 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -14,7 +14,7 @@ weight = -7 Grafana v5.1 brings new features, many enhancements and bug fixes. This article will detail the major new features and enhancements. -* [Scrolling]({{< relref "#scrolling" >}}) +* [Improved scrolling experience]({{< relref "#improved-scrolling-experience" >}}) * [Improved docker image]({{< relref "#improved-docker-image-breaking-change" >}}) with a breaking change! * [Improved workflow for provisioned dashboards]({{< relref "#improved-workflow-for-provisioned-dashboards" >}}) * [New template variable interpolation syntax]({{< relref "#new-template-variable-interpolation-syntax" >}}) @@ -22,9 +22,12 @@ Grafana v5.1 brings new features, many enhancements and bug fixes. This article * [Microsft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! * [Dashboards & Panels]({{< relref "#dashboards-panels" >}}) Improved adding panels to dashboards and enhancements to Graph and Table panels. -## Scrolling - +## Improved scrolling experience +In Grafana v5.0 we introduced a new scrollbar component. Unfortunately this introduced a lot of issues and in some scenarios removed +the native scrolling functionality. Grafana v5.1 ships with a native scrollbar for all pages together with a scrollbar component for +the dashboard grid and panels that's not overriding the native scrolling functionality. We hope that these changes and improvements should +make the Grafana user experience much better! ## Improved docker image (breaking change) From 540bde269e9e8dfb6641b6f757aff7087403f55f Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 19 Apr 2018 13:49:40 +0200 Subject: [PATCH 29/39] docs: fix typos --- docs/sources/guides/whats-new-in-v5-1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index c113be10819..3a456fec053 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -18,8 +18,8 @@ Grafana v5.1 brings new features, many enhancements and bug fixes. This article * [Improved docker image]({{< relref "#improved-docker-image-breaking-change" >}}) with a breaking change! * [Improved workflow for provisioned dashboards]({{< relref "#improved-workflow-for-provisioned-dashboards" >}}) * [New template variable interpolation syntax]({{< relref "#new-template-variable-interpolation-syntax" >}}) -* [Heatmap support for Prometehus]({{< relref "#prometheus" >}}) -* [Microsft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! +* [Heatmap support for Prometheus]({{< relref "#prometheus" >}}) +* [Microsoft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! * [Dashboards & Panels]({{< relref "#dashboards-panels" >}}) Improved adding panels to dashboards and enhancements to Graph and Table panels. ## Improved scrolling experience From ffb1db833c4488d73ba1efde85d80a3b834d77ce Mon Sep 17 00:00:00 2001 From: bergquist Date: Thu, 19 Apr 2018 14:22:56 +0200 Subject: [PATCH 30/39] docs: what's new add's info about new template variable interpolation --- docs/sources/guides/whats-new-in-v5-1.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index 3a456fec053..a310ff45580 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -60,6 +60,15 @@ More information in the [Provisioning documentation](/features/datasources/prome ## New template variable interpolation syntax +We now support a new option for rendering template variables that gives the user full control of how the value(s) should be rendered. In the table below you can see two examples and you can find all different options in the [template variable docs](http://docs.grafana.org/reference/templating/#advanced-formatting-options) + +Filter Option | Example | Raw | Interpolated | Description +------------ | ------------- | ------------- | ------------- | ------------- +`glob` | ${servers:glob} | `'test1', 'test2'` | `{test1,test2}` | (Default) Formats multi-value variable into a glob (for Graphite queries) +`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string (requires Grafana 5.1) +`lucene`| ${servers:lucene} | `'test', 'test2'` | `("test" OR "test2")` | Formats multi-value variable as a lucene expression. + + ## Prometheus The Prometheus datasource now support transforming Prometheus histograms to the heatmap panel. Prometheus histogram is a powerful feature, and we are really happy to finally allow our users to render those as heatmaps. From 886c8b823a98f07d5dc90e79eedbd4cb335c7a2a Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 19 Apr 2018 14:51:33 +0200 Subject: [PATCH 31/39] docs: what's new improvements --- docs/sources/guides/whats-new-in-v5-1.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index a310ff45580..da893a95a1e 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -60,7 +60,7 @@ More information in the [Provisioning documentation](/features/datasources/prome ## New template variable interpolation syntax -We now support a new option for rendering template variables that gives the user full control of how the value(s) should be rendered. In the table below you can see two examples and you can find all different options in the [template variable docs](http://docs.grafana.org/reference/templating/#advanced-formatting-options) +We now support a new option for rendering template variables that gives the user full control of how the value(s) should be rendered. In the table below you can see two examples and you can find all different options in the [template variable docs](http://docs.grafana.org/reference/templating/#advanced-formatting-options). Filter Option | Example | Raw | Interpolated | Description ------------ | ------------- | ------------- | ------------- | ------------- @@ -71,10 +71,16 @@ Filter Option | Example | Raw | Interpolated | Description ## Prometheus -The Prometheus datasource now support transforming Prometheus histograms to the heatmap panel. Prometheus histogram is a powerful feature, and we are really happy to finally allow our users to render those as heatmaps. +{{< docs-imagebox img="/img/docs/v51/prometheus_heatmap.png" max-width="800px" class="docs-image--right" >}} + +The Prometheus datasource now support transforming Prometheus histograms to the heatmap panel. Prometheus histogram is a powerful feature, and we're +really happy to finally allow our users to render those as heatmaps. Please read [Heatmap panel documentation](/features/panels/heatmap/#pre-bucketed-data) +for more information on how to use it. Prometheus query editor also got support for autocomplete of template variables. More information in the [Prometheus data source documentation](/features/datasources/prometheus/). +
+ ## PostgreSQL New enhancement includes support for filling in values for missing intervals and better precision handling and data type support for time columns. More information in the [PostgreSQL data source documentation](/features/datasources/postgres/#time-series-queries). @@ -87,8 +93,9 @@ New enhancements includes support for filling in values for missing intervals, b {{< docs-imagebox img="/img/docs/v51/mssql_query_editor_showcase.png" max-width= "800px" class="docs-image--right" >}} -Grafana v5.1 now ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer, including Microsoft Azure SQL Database. Have logs or metric data in MSSQL? You can now visualize that data and -define alert rules on it like any of our other data sources. +Grafana v5.1 now ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any +Microsoft SQL Server 2005 or newer, including Microsoft Azure SQL Database. Do you have metric or log data in MSSQL? You can now visualize +that data and define alert rules on it like with any of Grafana's other core datasources. Same enhancements as described for PostgreSQL and MySQL are included in the MSSQL datasource. From 727a7bf27a4765a1123e039a319192bbc50f56a0 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Thu, 19 Apr 2018 16:26:42 +0200 Subject: [PATCH 32/39] docs: what's new improvements --- docs/sources/guides/whats-new-in-v5-1.md | 67 ++++++++++-------------- 1 file changed, 29 insertions(+), 38 deletions(-) diff --git a/docs/sources/guides/whats-new-in-v5-1.md b/docs/sources/guides/whats-new-in-v5-1.md index da893a95a1e..66b04ce3d50 100644 --- a/docs/sources/guides/whats-new-in-v5-1.md +++ b/docs/sources/guides/whats-new-in-v5-1.md @@ -16,11 +16,11 @@ Grafana v5.1 brings new features, many enhancements and bug fixes. This article * [Improved scrolling experience]({{< relref "#improved-scrolling-experience" >}}) * [Improved docker image]({{< relref "#improved-docker-image-breaking-change" >}}) with a breaking change! -* [Improved workflow for provisioned dashboards]({{< relref "#improved-workflow-for-provisioned-dashboards" >}}) -* [New template variable interpolation syntax]({{< relref "#new-template-variable-interpolation-syntax" >}}) * [Heatmap support for Prometheus]({{< relref "#prometheus" >}}) * [Microsoft SQL Server]({{< relref "#microsoft-sql-server" >}}) as metric & table datasource! * [Dashboards & Panels]({{< relref "#dashboards-panels" >}}) Improved adding panels to dashboards and enhancements to Graph and Table panels. +* [New variable interpolation syntax]({{< relref "#new-variable-interpolation-syntax" >}}) +* [Improved workflow for provisioned dashboards]({{< relref "#improved-workflow-for-provisioned-dashboards" >}}) ## Improved scrolling experience @@ -43,32 +43,6 @@ Version | User | User ID Please read the [updated documentation](/installation/docker/#migration-from-a-previous-version-of-the-docker-container-to-5-1-or-later) which includes migration instructions and more information. -## Improved workflow for provisioned dashboards - -{{< docs-imagebox img="/img/docs/v51/provisioning_cannot_save_dashboard.png" max-width="800px" class="docs-image--right" >}} - -Grafana v5.1 brings an improved workflow for provisioned dashboards: - -* A populated `id` property in JSON is now automatically removed when provisioning dashboards. -* When making changes to a provisioned dashboard you can `Save` the dashboard which now will bring up a *Cannot save provisioned dashboard* dialog like seen in the screenshot to the right. - - -Available options in the dialog will let you `Copy JSON to Clipboard` and/or `Save JSON to file` which can help you synchronize your dashboard changes back to the provisioning source. -More information in the [Provisioning documentation](/features/datasources/prometheus/). - -
- -## New template variable interpolation syntax - -We now support a new option for rendering template variables that gives the user full control of how the value(s) should be rendered. In the table below you can see two examples and you can find all different options in the [template variable docs](http://docs.grafana.org/reference/templating/#advanced-formatting-options). - -Filter Option | Example | Raw | Interpolated | Description ------------- | ------------- | ------------- | ------------- | ------------- -`glob` | ${servers:glob} | `'test1', 'test2'` | `{test1,test2}` | (Default) Formats multi-value variable into a glob (for Graphite queries) -`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string (requires Grafana 5.1) -`lucene`| ${servers:lucene} | `'test', 'test2'` | `("test" OR "test2")` | Formats multi-value variable as a lucene expression. - - ## Prometheus {{< docs-imagebox img="/img/docs/v51/prometheus_heatmap.png" max-width="800px" class="docs-image--right" >}} @@ -81,14 +55,6 @@ Prometheus query editor also got support for autocomplete of template variables.
-## PostgreSQL - -New enhancement includes support for filling in values for missing intervals and better precision handling and data type support for time columns. More information in the [PostgreSQL data source documentation](/features/datasources/postgres/#time-series-queries). - -## MySQL - -New enhancements includes support for filling in values for missing intervals, better precision handling and data type support for time columns and any column except time and metric is now treated as a value column. More information in the [MySQL data source documentation](/features/datasources/mysql/#time-series-queries). - ## Microsoft SQL Server {{< docs-imagebox img="/img/docs/v51/mssql_query_editor_showcase.png" max-width= "800px" class="docs-image--right" >}} @@ -97,8 +63,6 @@ Grafana v5.1 now ships with a built-in Microsoft SQL Server (MSSQL) data source Microsoft SQL Server 2005 or newer, including Microsoft Azure SQL Database. Do you have metric or log data in MSSQL? You can now visualize that data and define alert rules on it like with any of Grafana's other core datasources. -Same enhancements as described for PostgreSQL and MySQL are included in the MSSQL datasource. - Please read [Using Microsoft SQL Server in Grafana documentation](/features/datasources/mssql/) for more detailed information on how to get started and use it.
@@ -128,6 +92,33 @@ New enhancements includes support for multiple series stacking in histogram mode New enhancements includes support for mapping a numeric value/range to text and additional units. More information in the [Table panel documentation](/features/panels/table_panel/#string). +## New variable interpolation syntax + +We now support a new option for rendering variables that gives the user full control of how the value(s) should be rendered. +In the table below you can see some examples and you can find all different options in the [Variables documentation](http://docs.grafana.org/reference/templating/#advanced-formatting-options). + +Filter Option | Example | Raw | Interpolated | Description +------------ | ------------- | ------------- | ------------- | ------------- +`glob` | ${servers:glob} | `'test1', 'test2'` | `{test1,test2}` | Formats multi-value variable into a glob +`regex` | ${servers:regex} | `'test.', 'test2'` | `(test\\.|test2)` | Formats multi-value variable into a regex string +`pipe` | ${servers:pipe} | `'test.', 'test2'` | `test.|test2` | Formats multi-value variable into a pipe-separated string +`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string + +## Improved workflow for provisioned dashboards + +{{< docs-imagebox img="/img/docs/v51/provisioning_cannot_save_dashboard.png" max-width="800px" class="docs-image--right" >}} + +Grafana v5.1 brings an improved workflow for provisioned dashboards: + +* A populated `id` property in JSON is now automatically removed when provisioning dashboards. +* When making changes to a provisioned dashboard you can `Save` the dashboard which now will bring up a *Cannot save provisioned dashboard* dialog like seen in the screenshot to the right. + + +Available options in the dialog will let you `Copy JSON to Clipboard` and/or `Save JSON to file` which can help you synchronize your dashboard changes back to the provisioning source. +More information in the [Provisioning documentation](/features/datasources/prometheus/). + +
+ ## Changelog Checkout the [CHANGELOG.md](https://github.com/grafana/grafana/blob/master/CHANGELOG.md) file for a complete list From c10359dd5b5aee8ce96863989543e67ef8c05bc6 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Fri, 20 Apr 2018 13:21:14 +0200 Subject: [PATCH 33/39] docs: fixes for table in variable docs --- docs/sources/reference/templating.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/sources/reference/templating.md b/docs/sources/reference/templating.md index c7666a169d8..8341b9770bd 100644 --- a/docs/sources/reference/templating.md +++ b/docs/sources/reference/templating.md @@ -38,16 +38,18 @@ documentation article for details on value escaping during interpolation. ### Advanced Formatting Options -In Grafana 5.0, a new syntax for variables was introduced to control the formatting of the interpolation. +> Only available in Grafana v5.1+. + +The formatting of the variable interpolation depends on the data source but there are some situations where you might want to change the default formatting. For example, the default for the MySql datasource is to join multiple values as comma-separated with quotes: `'server01','server02'`. In some cases you might want to have a comma-separated string without quotes: `server01,server02`. This is now possible with the advanced formatting options. Syntax: `${var_name:option}` Filter Option | Example | Raw | Interpolated | Description ------------ | ------------- | ------------- | ------------- | ------------- `glob` | ${servers:glob} | `'test1', 'test2'` | `{test1,test2}` | (Default) Formats multi-value variable into a glob (for Graphite queries) -`regex` | ${servers:regex} | `'test.', 'test2'` | `(test\\.|test2)` | Formats multi-value variable into a regex string -`pipe` | ${servers:pipe} | `'test.', 'test2'` | `test.|test2` | Formats multi-value variable into a pipe-separated string -`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string (requires Grafana 5.1) +`regex` | ${servers:regex} | `'test.', 'test2'` | (test\.|test2) | Formats multi-value variable into a regex string +`pipe` | ${servers:pipe} | `'test.', 'test2'` | test.|test2 | Formats multi-value variable into a pipe-separated string +`csv`| ${servers:csv} | `'test1', 'test2'` | `test1,test2` | Formats multi-value variable as a comma-separated string `distributed`| ${servers:distributed} | `'test1', 'test2'` | `test1,servers=test2` | Formats multi-value variable in custom format for OpenTSDB. `lucene`| ${servers:lucene} | `'test', 'test2'` | `("test" OR "test2")` | Formats multi-value variable as a lucene expression. @@ -55,7 +57,7 @@ Test the formatting options on the [Grafana Play site](http://play.grafana.org/d If any invalid formatting option is specified, then `glob` is the default/fallback option. -An alternative syntax is `[[var_name:option]]`. +An alternative syntax (that might be deprecated in the future) is `[[var_name:option]]`. ### Variable options @@ -187,7 +189,7 @@ Option | Description ------- | -------- *Multi-value* | If enabled, the variable will support the selection of multiple options at the same time. *Include All option* | Add a special `All` option whose value includes all options. -*Custom all value* | By default the `All` value will include all options in combined expression. This can become very long and can have performance problems. Many times it can be better to specify a custom all value, like a wildcard regex. To make it possible to have custom regex, globs or lucene syntax in the **Custom all value** option it is never escaped so you will have to think avbout what is a valid value for your data source. +*Custom all value* | By default the `All` value will include all options in combined expression. This can become very long and can have performance problems. Many times it can be better to specify a custom all value, like a wildcard regex. To make it possible to have custom regex, globs or lucene syntax in the **Custom all value** option it is never escaped so you will have to think about what is a valid value for your data source. ### Formatting multiple values @@ -298,4 +300,3 @@ Variable values are always synced to the URL using the syntax `var-=val - [Graphite Templated Dashboard](http://play.grafana.org/dashboard/db/graphite-templated-nested) - [Elasticsearch Templated Dashboard](http://play.grafana.org/dashboard/db/elasticsearch-templated) - [InfluxDB Templated Dashboard](http://play.grafana.org/dashboard/db/influxdb-templated-queries) - From 71dcafebb8f8018c587ce2ce71861e791a8f6868 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Fri, 20 Apr 2018 13:22:43 +0200 Subject: [PATCH 34/39] docs: add missing backtick for mysql/postgres --- docs/sources/features/datasources/mysql.md | 6 +++--- docs/sources/features/datasources/postgres.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/features/datasources/mysql.md b/docs/sources/features/datasources/mysql.md index 1920759711c..0b0bdd41aef 100644 --- a/docs/sources/features/datasources/mysql.md +++ b/docs/sources/features/datasources/mysql.md @@ -202,7 +202,7 @@ ORDER BY atimestamp ASC #### Disabling Quoting for Multi-value Variables -Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'. Do disable quoting, use the csv formatting option for variables: +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. Do disable quoting, use the csv formatting option for variables: `${servers:csv}` @@ -234,9 +234,9 @@ tags | Optional field name to use for event tags as a comma separated string. Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule conditions. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/postgres.md b/docs/sources/features/datasources/postgres.md index bc684a8f168..c6bebc2667c 100644 --- a/docs/sources/features/datasources/postgres.md +++ b/docs/sources/features/datasources/postgres.md @@ -192,7 +192,7 @@ ORDER BY atimestamp ASC #### Disabling Quoting for Multi-value Variables -Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'. Do disable quoting, use the csv formatting option for variables: +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. Do disable quoting, use the csv formatting option for variables: `${servers:csv}` From 3a991483158f15f4c3eb403becd8ded9b078d800 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Fri, 20 Apr 2018 13:24:37 +0200 Subject: [PATCH 35/39] docs: spelling --- docs/sources/features/datasources/cloudwatch.md | 4 ++-- docs/sources/features/datasources/elasticsearch.md | 4 ++-- docs/sources/features/datasources/graphite.md | 4 ++-- docs/sources/features/datasources/influxdb.md | 4 ++-- docs/sources/features/datasources/opentsdb.md | 4 ++-- docs/sources/features/datasources/prometheus.md | 6 +++--- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/sources/features/datasources/cloudwatch.md b/docs/sources/features/datasources/cloudwatch.md index f5586bef2d8..d178c176602 100644 --- a/docs/sources/features/datasources/cloudwatch.md +++ b/docs/sources/features/datasources/cloudwatch.md @@ -208,9 +208,9 @@ it costs $0.01 per 1,000 GetMetricStatistics or ListMetrics requests. For each q issue a GetMetricStatistics request and every time you pick a dimension in the query editor Grafana will issue a ListMetrics request. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/elasticsearch.md b/docs/sources/features/datasources/elasticsearch.md index 1a00c2b18ff..f919ee3c7fc 100644 --- a/docs/sources/features/datasources/elasticsearch.md +++ b/docs/sources/features/datasources/elasticsearch.md @@ -154,9 +154,9 @@ Time | The name of the time field, needs to be date field. Text | Event description field. Tags | Optional field name to use for event tags (can be an array or a CSV string). -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 161d174203e..e401afdd0d2 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -134,9 +134,9 @@ queries via the Dashboard menu / Annotations view. Graphite supports two ways to query annotations. A regular metric query, for this you use the `Graphite query` textbox. A Graphite events query, use the `Graphite event tags` textbox, specify a tag or wildcard (leave empty should also work) -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/influxdb.md b/docs/sources/features/datasources/influxdb.md index d108c97bbfe..8c3468ace1e 100644 --- a/docs/sources/features/datasources/influxdb.md +++ b/docs/sources/features/datasources/influxdb.md @@ -191,9 +191,9 @@ For InfluxDB you need to enter a query like in the above example. You need to ha part. If you only select one column you will not need to enter anything in the column mapping fields. The Tags field can be a comma separated string. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/opentsdb.md b/docs/sources/features/datasources/opentsdb.md index 0959817c015..00c339d94e5 100644 --- a/docs/sources/features/datasources/opentsdb.md +++ b/docs/sources/features/datasources/opentsdb.md @@ -89,9 +89,9 @@ Query | Description For details on OpenTSDB metric queries checkout the official [OpenTSDB documentation](http://opentsdb.net/docs/build/html/index.html) -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. diff --git a/docs/sources/features/datasources/prometheus.md b/docs/sources/features/datasources/prometheus.md index 17a24ed0684..f915488804b 100644 --- a/docs/sources/features/datasources/prometheus.md +++ b/docs/sources/features/datasources/prometheus.md @@ -101,9 +101,9 @@ The step option is useful to limit the number of events returned from your query Since 4.6.0 Grafana exposes metrics for Prometheus on the `/metrics` endpoint. We also bundle a dashboard within Grafana so you can get started viewing your metrics faster. You can import the bundled dashboard by going to the data source edit page and click the dashboard tab. There you can find a dashboard for Grafana and one for Prometheus. Import and start viewing all the metrics! -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. @@ -115,4 +115,4 @@ datasources: type: prometheus access: proxy url: http://localhost:9090 -``` \ No newline at end of file +``` From 492f842c53f63ad8af63d4f00cee536d1660a284 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Fri, 20 Apr 2018 13:32:17 +0200 Subject: [PATCH 36/39] docs: fix example for graphite tag query Was missing a tilde in the tag_values example --- docs/sources/features/datasources/graphite.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index e401afdd0d2..0e72a6a954a 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -94,7 +94,7 @@ Query | Description *tags(server=~backend\*)* | Returns only tags that occur in series matching the filter expression. *tag_values(server)* | Return tag values for the specified tag. *tag_values(server, server=~backend*)* | Returns filtered tag values that occur for the specified tag in series matching those expressions. -*tag_values(server, server=~backend*, app=${apps:regex})* | Multiple filter expressions and expressions can contain other variables. +*tag_values(server, server=~backend*, app=~${apps:regex})* | Multiple filter expressions and expressions can contain other variables. For more details, see the [Graphite docs on the autocomplete api for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support). @@ -124,7 +124,15 @@ Example: ### Variable Usage in Tag Queries -Multi-value variables in tag queries use the advanced formatting syntax introduced in Grafana 5.0 for variables: `{var:regex}`. Non-tag queries will use the default glob formatting for multi-value variables. Checkout the [Advanced Formatting Options section in the Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. +Multi-value variables in tag queries use the advanced formatting syntax introduced in Grafana 5.0 for variables: `{var:regex}`. Non-tag queries will use the default glob formatting for multi-value variables. + +Example of a tag expression with regex formatting and using the Equal Tilde operator, `=~`: + +```text +server=~${servers:regex} +``` + +Checkout the [Advanced Formatting Options section in the Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation for examples and details. ## Annotations From ba2e43f547525248cdec14bce1bd43f69b2c5a43 Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Fri, 20 Apr 2018 13:36:07 +0200 Subject: [PATCH 37/39] docs: disable quoting option for MSSQL --- docs/sources/features/datasources/mssql.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 0310683320e..9a0f53093ec 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -295,6 +295,7 @@ SELECT hostname FROM host WHERE region IN ($region) ``` ### Using Variables in Queries + > From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically so if it is a string value do not wrap them in quotes in where clauses. > > From Grafana 5.0.0, template variable values are only quoted when the template variable is a `multi-value`. @@ -325,6 +326,14 @@ WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ``` +#### Disabling Quoting for Multi-value Variables + +Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. Do disable quoting, use the csv formatting option for variables: + +`${servers:csv}` + +Read more about variable formatting options in the [Variables]({{< relref "reference/templating.md#advanced-formatting-options" >}}) documentation. + ## Annotations [Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. @@ -530,9 +539,9 @@ EXEC dbo.sp_test_datetime @from, @to Time series queries should work in alerting conditions. Table formatted queries are not yet supported in alert rule conditions. -## Configure datasource with provisioning +## Configure the Datasource with Provisioning -It's now possible to configure datasources using config files with Grafanas provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) +It's now possible to configure datasources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for datasources on the [provisioning docs page](/administration/provisioning/#datasources) Here are some provisioning examples for this datasource. From 8f9d9ed35d71cee6b5488a9fd98b9a028812179b Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Fri, 20 Apr 2018 15:27:20 +0200 Subject: [PATCH 38/39] docs: escape asterisk in Graphite docs --- docs/sources/features/datasources/graphite.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/features/datasources/graphite.md b/docs/sources/features/datasources/graphite.md index 7a4113a89ef..da58a48225f 100644 --- a/docs/sources/features/datasources/graphite.md +++ b/docs/sources/features/datasources/graphite.md @@ -101,8 +101,8 @@ Query | Description *tags()* | Returns all tags. *tags(server=~backend\*)* | Returns only tags that occur in series matching the filter expression. *tag_values(server)* | Return tag values for the specified tag. -*tag_values(server, server=~backend*)* | Returns filtered tag values that occur for the specified tag in series matching those expressions. -*tag_values(server, server=~backend*, app=~${apps:regex})* | Multiple filter expressions and expressions can contain other variables. +*tag_values(server, server=~backend\*)* | Returns filtered tag values that occur for the specified tag in series matching those expressions. +*tag_values(server, server=~backend\*, app=~${apps:regex})* | Multiple filter expressions and expressions can contain other variables. For more details, see the [Graphite docs on the autocomplete api for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support). From 79928974186840ebcc89b17f5b545e52f8d6edd8 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Tue, 24 Apr 2018 16:30:24 +0200 Subject: [PATCH 39/39] docs: add known issues section for mssql documentation Fixes #11707 --- docs/sources/features/datasources/mssql.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/sources/features/datasources/mssql.md b/docs/sources/features/datasources/mssql.md index 9a0f53093ec..1676cffa0a8 100644 --- a/docs/sources/features/datasources/mssql.md +++ b/docs/sources/features/datasources/mssql.md @@ -49,6 +49,11 @@ Example: Make sure the user does not get any unwanted privileges from the public role. +### Known Issues + +MSSQL 2008 and 2008 R2 engine cannot handle login records when SSL encryption is not disabled. Due to this you may receive an `Login error: EOF` error when trying to create your datasource. +To fix MSSQL 2008 R2 issue, install MSSQL 2008 R2 Service Pack 2. To fix MSSQL 2008 issue, install Microsoft MSSQL 2008 Service Pack 3 and Cumulative update package 3 for MSSQL 2008 SP3. + ## Query Editor {{< docs-imagebox img="/img/docs/v51/mssql_query_editor.png" class="docs-image--no-shadow" >}}