public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'docs-5.1' into graph_51_docs

Browse Source
This commit is contained in:
Marcus Efraimsson
2018-03-23 15:51:32 +01:00
parent 0a487c484d 403c64ab20
commit 13d0bd5815
86 changed files with 7935 additions and 1462 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/administration/provisioning.md
+16 -13
View File
@@ -11,11 +11,13 @@ weight = 8
# Provisioning Grafana
## Config file
In previous versions of Grafana, you could only use the API for provisioning data sources and dashboards. But that required the service to be running before you started creating dashboards and you also needed to set up credentials for the HTTP API. In v5.0 we decided to improve this experience by adding a new active provisioning system that uses config files. This will make GitOps more natural as data sources and dashboards can be defined via files that can be version controlled. We hope to extend this system to later add support for users, orgs and alerts as well.
## Config File
Checkout the [configuration](/installation/configuration) page for more information on what you can configure in `grafana.ini`
### Config file locations
### Config File Locations
- Default configuration from `$WORKING_DIR/conf/defaults.ini`
- Custom configuration from `$WORKING_DIR/conf/custom.ini`
@@ -26,7 +28,7 @@ Checkout the [configuration](/installation/configuration) page for more informat
> `/etc/grafana/grafana.ini`. This path is specified in the Grafana
> init.d script using `--config` file parameter.
### Using environment variables
### Using Environment Variables
All options in the configuration file (listed below) can be overridden
using environment variables using the syntax:
@@ -59,7 +61,7 @@ export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey
<hr />
## Configuration management tools
## Configuration Management Tools
Currently we do not provide any scripts/manifests for configuring Grafana. Rather than spending time learning and creating scripts/manifests for each tool, we think our time is better spent making Grafana easier to provision. Therefore, we heavily relay on the expertise of the community.
@@ -76,10 +78,12 @@ Saltstack | [https://github.com/salt-formulas/salt-formula-grafana](https://gith
It's possible to manage datasources in Grafana by adding one or more yaml config files in the [`provisioning/datasources`](/installation/configuration/#provisioning) directory. Each config file can contain a list of `datasources` that will be added or updated during start up. If the datasource already exists, Grafana will update it to match the configuration file. The config file can also contain a list of datasources that should be deleted. That list is called `delete_datasources`. Grafana will delete datasources listed in `delete_datasources` before inserting/updating those in the `datasource` list.
### Running multiple Grafana instances.
### Running Multiple Grafana Instances
If you are running multiple instances of Grafana you might run into problems if they have different versions of the `datasource.yaml` configuration file. The best way to solve this problem is to add a version number to each datasource in the configuration and increase it when you update the config. Grafana will only update datasources with the same or lower version number than specified in the config. That way, old configs cannot overwrite newer configs if they restart at the same time.
### Example datasource config file
### Example Datasource Config File
```yaml
# config file version
apiVersion: 1
@@ -133,20 +137,20 @@ datasources:
editable: false
```
#### Extra info per datasource
#### Custom Settings per Datasource
| Datasource | Misc |
| ---- | ---- |
| Elasticserach | Elasticsearch uses the `database` property to configure the index for a datasource |
| Elasticsearch | Elasticsearch uses the `database` property to configure the index for a datasource |
#### Json data
#### Json Data
Since not all datasources have the same configuration settings we only have the most common ones as fields. The rest should be stored as a json blob in the `json_data` field. Here are the most common settings that the core datasources use.
| Name | Type | Datasource | Description |
| ---- | ---- | ---- | ---- |
| tlsAuth | boolean | *All* | Enable TLS authentication using client cert configured in secure json data |
| tlsAuthWithCACert | boolean | *All* | Enable TLS authtication using CA cert |
| tlsAuthWithCACert | boolean | *All* | Enable TLS authentication using CA cert |
| tlsSkipVerify | boolean | *All* | Controls whether a client verifies the server's certificate chain and host name. |
| graphiteVersion | string | Graphite | Graphite version |
| timeInterval | string | Elastic, Influxdb & Prometheus | Lowest interval/step value that should be used for this data source |
@@ -161,8 +165,7 @@ Since not all datasources have the same configuration settings we only have the
| tsdbResolution | string | OpenTsdb | Resolution |
| sslmode | string | Postgre | SSLmode. 'disable', 'require', 'verify-ca' or 'verify-full' |
#### Secure Json data
#### Secure Json Data
`{"authType":"keys","defaultRegion":"us-west-2","timeField":"@timestamp"}`
@@ -200,7 +203,7 @@ providers:
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.
### Reuseable dashboard urls
### 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 identifer.
When Grafana starts, it will update/insert all dashboards available in the configured folders. If you modify the file, the dashboard will also be updated.
docs/sources/features/datasources/mssql.md
+8 -9
View File
@@ -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*. <br/>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*. <br/>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. <br/>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. <br/>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*. <br/>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. <br/>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. <br/>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
docs/sources/features/datasources/mysql.md
+72 -46
View File
@@ -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.
docs/sources/features/datasources/postgres.md
+44 -19
View File
@@ -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.