Docs: Refactor data sources content (#57573)
* Docs: Revise data source index * Docs: Consolidate data source administration docs * Docs: Revise panels docs related to data sources * Docs: Revise Alertmanager data source * Docs: Reorganize AWS CloudWatch data source docs * Docs: Reorganize Azure Monitor data source docs * Docs: Move azuremonitor to azure-monitor * Docs: Revise Elasticsearch docs * Docs: Move Elasticsearch index into bundle * Docs: Revise GCM docs * Docs: Revise Graphite docs * Docs: Move Graphite index into bundle * Docs: Revise InfluxDB docs * Docs: Revise Jaeger docs * Docs: Move Jaeger index into bundle * Docs: Revise Loki docs * Docs: Move Loki index into bundle * Docs: Revise MS SQL docs * Docs: Move MS SQL index into bundle * Docs: Revise Prometheus docs * Docs: Move Prometheus index into bundle * Docs: Revise Tempo docs * Docs: Move Tempo index into bundle * Docs: Revise TestData DB docs * Docs: Move TestData DB index into bundle * Docs: Revise Zipkin docs * Docs: Move Zipkin index into bundle * Docs: Move other data sources' index pages into bundles * Docs: Revise frontmatter * Fixing hugo markdown errors * Docs: Add query editor and template var sections to overview doc * Docs: Remove CTAs across data source docs * Docs: Remove CTA * Docs: Remove CTA * Docs: Fix links, images, typos, and usage consistency. * Docs: Fix typos * Docs: Fix CI issues * Update docs/sources/datasources/_index.md Co-authored-by: Torkel Ödegaard <torkel@grafana.com> * Update docs/sources/datasources/_index.md Co-authored-by: Torkel Ödegaard <torkel@grafana.com> * Docs: Fix query editor links * Update docs/sources/panels-visualizations/_index.md Co-authored-by: Torkel Ödegaard <torkel@grafana.com> * Update docs/sources/panels-visualizations/_index.md Co-authored-by: Torkel Ödegaard <torkel@grafana.com> * Docs: Rebundle child pages per writers' toolkit * Docs: Fix prettier for CI * Docs: Fix relrefs from outside data sources docs * Docs: Fix broken relrefs within datasources * Docs: Fix relrefs to data sources docs * Fixed some more refs Co-authored-by: Torkel Ödegaard <torkel@grafana.com>
This commit is contained in:
Garrett Guillotte
co-authored by
Torkel Ödegaard
Torkel Ödegaard
parent
22648d8581
commit
852d069a3c
@@ -0,0 +1,100 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/features/datasources/graphite/
|
||||
- /docs/grafana/latest/datasources/graphite/
|
||||
- /docs/grafana/latest/data-sources/graphite/
|
||||
description: Guide for using Graphite in Grafana
|
||||
keywords:
|
||||
- grafana
|
||||
- graphite
|
||||
- guide
|
||||
menuTitle: Graphite
|
||||
title: Graphite data source
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# Graphite data source
|
||||
|
||||
Grafana includes built-in support for Graphite.
|
||||
This topic explains options, variables, querying, and other features specific to the Graphite data source, which include its feature-rich query editor.
|
||||
|
||||
For instructions on how to add a data source to Grafana, refer to the [administration documentation]({{< relref "../../administration/data-source-management/" >}}).
|
||||
Only users with the organization administrator role can add data sources.
|
||||
|
||||
Once you've added the Graphite data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so that your Grafana instance's users can create queries in its [query editor]({{< relref "./query-editor/" >}}) when they [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
|
||||
|
||||
## Configure the data source
|
||||
|
||||
**To access the data source configuration page:**
|
||||
|
||||
1. Hover the cursor over the **Configuration** (gear) icon.
|
||||
1. Select **Data Sources**.
|
||||
1. Select the Graphite data source.
|
||||
|
||||
Set the data source's basic configuration options carefully:
|
||||
|
||||
| Name | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
|
||||
| **Default** | Sets whether the data source is pre-selected for new panels. You can set only one default data source per organization. |
|
||||
| **URL** | Sets the HTTP protocol, IP, and port of your graphite-web or graphite-api installation. |
|
||||
| **Auth** | For details, refer to [Configure Authentication]({{< relref "../../setup-grafana/configure-security/configure-authentication/" >}}). |
|
||||
| **Basic Auth** | Enables basic authentication to the data source. |
|
||||
| **User** | Sets the user name for basic authentication. |
|
||||
| **Password** | Sets the password for basic authentication. |
|
||||
| **Custom HTTP Headers** | Click **Add header** to add a custom HTTP header. |
|
||||
| **Header** | Defines the custom header name. |
|
||||
| **Value** | Defines the custom header value. |
|
||||
|
||||
You can also configure settings specific to the Graphite data source:
|
||||
|
||||
| Name | Description |
|
||||
| ----------- | -------------------------------- |
|
||||
| **Version** | Select your version of Graphite. |
|
||||
| **Type** | Select your type of Graphite. |
|
||||
|
||||
### Integrate with Loki
|
||||
|
||||
When you change the data source selection in [Explore]({{< relref "../../explore/" >}}), Graphite queries are converted to Loki queries.
|
||||
Grafana extracts Loki label names and values from the Graphite queries according to mappings provided in the Graphite data source configuration.
|
||||
Queries using tags with `seriesByTags()` are also transformed without any additional setup.
|
||||
|
||||
### Provision the data source
|
||||
|
||||
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
|
||||
For more information about provisioning, and for lists of common configuration options and JSON data options, refer to [Provisioning data sources]({{< relref "../../administration/provisioning/#data-sources" >}}).
|
||||
|
||||
#### Provisioning example
|
||||
|
||||
```yaml
|
||||
apiVersion: 1
|
||||
|
||||
datasources:
|
||||
- name: Graphite
|
||||
type: graphite
|
||||
access: proxy
|
||||
url: http://localhost:8080
|
||||
jsonData:
|
||||
graphiteVersion: '1.1'
|
||||
```
|
||||
|
||||
## Query the data source
|
||||
|
||||
Grafana includes a Graphite-specific query editor to help you build queries.
|
||||
The query editor helps you quickly navigate the metric space, add functions, and change function parameters.
|
||||
It can handle all types of Graphite queries, including complex nested queries through the use of query references.
|
||||
|
||||
For details, refer to the [query editor documentation]({{< relref "./query-editor/" >}}).
|
||||
|
||||
## Use template variables
|
||||
|
||||
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
|
||||
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
|
||||
Grafana refers to such variables as template variables.
|
||||
|
||||
For details, see the [template variables documentation]({{< relref "./template-variables/" >}}).
|
||||
|
||||
## Get Grafana metrics into Graphite
|
||||
|
||||
Grafana exposes metrics for Graphite on the `/metrics` endpoint.
|
||||
For detailed instructions, refer to [Internal Grafana metrics]({{< relref "../../setup-grafana/set-up-grafana-monitoring" >}}).
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/data-sources/graphite/query-editor/
|
||||
description: Guide for using the Graphite data source's query editor
|
||||
keywords:
|
||||
- grafana
|
||||
- microsoft
|
||||
- graphite
|
||||
- monitor
|
||||
- metrics
|
||||
- logs
|
||||
- resources
|
||||
- queries
|
||||
menuTitle: Query editor
|
||||
title: Graphite query editor
|
||||
weight: 300
|
||||
---
|
||||
|
||||
# Graphite query editor
|
||||
|
||||
Grafana includes a Graphite-specific query editor to help you build queries.
|
||||
The query editor helps you quickly navigate the metric space, add functions, and change function parameters.
|
||||
It can handle all types of Graphite queries, including complex nested queries through the use of query references.
|
||||
|
||||
For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
|
||||
|
||||
## View the raw query
|
||||
|
||||
To see the raw text of the query that Grafana sends to Graphite, click the **Toggle text edit mode** (pencil) icon.
|
||||
|
||||
## Choose metrics to query
|
||||
|
||||
Click **Select metric** to navigate the metric space.
|
||||
Once you begin, you can use the mouse or keyboard arrow keys.
|
||||
You can also select a wildcard and still continue.
|
||||
|
||||
{{< figure src="/static/img/docs/graphite/graphite-query-editor-still.png" animated-gif="/static/img/docs/graphite/graphite-query-editor.gif" >}}
|
||||
|
||||
## Functions
|
||||
|
||||
Click the plus icon next to **Function** to add a function. You can search for the function or select it from the menu. Once
|
||||
a function is selected, it will be added and your focus will be in the text box of the first parameter.
|
||||
|
||||
- To edit or change a parameter, click on it and it will turn into a text box.
|
||||
- To delete a function, click the function name followed by the x icon.
|
||||
|
||||
{{< figure src="/static/img/docs/graphite/graphite-functions-still.png" animated-gif="/static/img/docs/graphite/graphite-functions-demo.gif" >}}
|
||||
|
||||
Some functions like aliasByNode support an optional second argument. To add an argument, hover your mouse over the first argument and then click the `+` symbol that appears. To remove the second optional parameter, click on it and leave it blank and the editor will remove it.
|
||||
|
||||
To learn more, refer to [Graphite's documentation on functions](https://graphite.readthedocs.io/en/latest/functions.html).
|
||||
|
||||
### Sort labels
|
||||
|
||||
If you have the same labels on multiple graphs, they are both sorted differently and use different colors.
|
||||
|
||||
To avoid this and consistently order labels by name, use the `sortByName()` function.
|
||||
|
||||
### Modify the metric name in my tables or charts
|
||||
|
||||
Use `alias` functions, such as `aliasByNode()` or `aliasSub()`, to change metric names on Grafana tables or graphs.
|
||||
|
||||
### Consolidate data points
|
||||
|
||||
Grafana consolidates all Graphite metrics so that Graphite doesn't return more data points than there are pixels in the graph.
|
||||
By default, Grafana consolidates data points using the `avg` function.
|
||||
To control how Graphite consolidates metrics, use the Graphite `consolidateBy()` function.
|
||||
|
||||
> **Note:** Legend summary values (max, min, total) can't all be correct at the same time because they are calculated client-side by Grafana.
|
||||
> Depending on your consolidation function, only one or two can be correct at the same time.
|
||||
|
||||
### Combine time series
|
||||
|
||||
To combine time series, click **Combine** in the **Functions** list.
|
||||
|
||||
### Select and explor data with tags
|
||||
|
||||
In Graphite, _everything_ is a tag.
|
||||
|
||||
When exploring data, previously selected tags filter the remaining result set.
|
||||
To select data, use the `seriesByTag` function, which takes tag expressions (`=`, `!=`, `=~`, `!=~`) to filter timeseries.
|
||||
|
||||
The Grafana query builder does this for you automatically when you select a tag.
|
||||
|
||||
> **Tip:** The regular expression search can be slow on high-cardinality tags, so try to use other tags to reduce the scope first.
|
||||
> To help reduce the results, start by filtering on a particular name or namespace.
|
||||
|
||||
## Nest queries
|
||||
|
||||
You can reference a query by the "letter" of its row, similar to a spreadsheet.
|
||||
|
||||
If you add a second query to a graph, you can reference the first query by entering `#A`.
|
||||
This helps you build compounded queries.
|
||||
|
||||
## Use wildcards to make fewer queries
|
||||
|
||||
To view multiple time series plotted on the same graph, use wildcards in your search to return all of the matching time series in one query.
|
||||
|
||||
For example, to see how the CPU is being utilized on a machine, you can create a graph and use the single query `cpu.percent.*.g` to retrieve all time series that match that pattern.
|
||||
This is more efficient than adding a query for each time series, such as `cpu.percent.user.g`, `cpu.percent.system.g`, and so on, which results in many queries to the data source.
|
||||
|
||||
## Apply annotations
|
||||
|
||||
[Annotations]({{< relref "../../../dashboards/build-dashboards/annotate-visualizations" >}}) overlay rich event information on top of graphs.
|
||||
You can add annotation queries in the Dashboard menu's Annotations view.
|
||||
|
||||
Graphite supports two ways to query annotations:
|
||||
|
||||
- A regular metric query, using the `Graphite query` textbox.
|
||||
- A Graphite events query, using the `Graphite event tags` textbox with a tag, wildcard, or empty value
|
||||
|
||||
## Get Grafana metrics into Graphite
|
||||
|
||||
Grafana exposes metrics for Graphite on the `/metrics` endpoint.
|
||||
For detailed instructions, refer to [Internal Grafana metrics]({{< relref "../../../setup-grafana/set-up-grafana-monitoring" >}}).
|
||||
|
||||
## Integration with Loki
|
||||
|
||||
Graphite queries get converted to Loki queries when the data source selection changes in Explore. Loki label names and values are extracted from the Graphite queries according to mappings information provided in Graphite data source configuration. Queries using tags with `seriesByTags()` are also transformed without any additional setup.
|
||||
|
||||
Refer to the Graphite data source settings for more details.
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/data-sources/graphite/template-variables/
|
||||
description: Guide for using template variables when querying the Graphite data source
|
||||
keywords:
|
||||
- grafana
|
||||
- graphite
|
||||
- queries
|
||||
- template
|
||||
- variable
|
||||
menuTitle: Template variables
|
||||
title: Graphite template variables
|
||||
weight: 300
|
||||
---
|
||||
|
||||
# Graphite template variables
|
||||
|
||||
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
|
||||
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
|
||||
Grafana refers to such variables as template variables.
|
||||
|
||||
For an introduction to templating and template variables, refer to the [Templating]({{< relref "../../../dashboards/variables" >}}) and [Add and manage variables]({{< relref "../../../dashboards/variables/add-template-variables" >}}) documentation.
|
||||
|
||||
## Use tag variables
|
||||
|
||||
To create a variable using tag values, 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)` | Returns 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. |
|
||||
|
||||
Multiple filter expressions and expressions can contain other variables. For example:
|
||||
|
||||
```
|
||||
tag_values(server, server=~backend\*, app=~${apps:regex})
|
||||
```
|
||||
|
||||
For details, refer to the [Graphite docs on the autocomplete API for tags](http://graphite.readthedocs.io/en/latest/tags.html#auto-complete-support).
|
||||
|
||||
### Use multi-valie variables in tag queries
|
||||
|
||||
Multi-value variables in tag queries use the advanced formatting syntax for variables introduced in Grafana v5.0: `{var:regex}`.
|
||||
Non-tag queries use the default glob formatting for multi-value variables.
|
||||
|
||||
#### Tag expression example
|
||||
|
||||
**Using regex formatting and the Equal Tilde operator, `=~`:**
|
||||
|
||||
```text
|
||||
server=~${servers:regex}
|
||||
```
|
||||
|
||||
For more information, refer to [Advanced variable format options]({{< relref "../../../dashboards/variables/variable-syntax#advanced-variable-format-options" >}}).
|
||||
|
||||
## Use other query variables
|
||||
|
||||
When writing queries, use the metric find type of query.
|
||||
|
||||
For example, a query like `prod.servers.*` fills the variable with all possible values that exist in the wildcard position.
|
||||
|
||||
The results contain all possible values occurring only at the last level of the query.
|
||||
To get full metric names matching the query, use the `expand` function: `expand(*.servers.*)`.
|
||||
|
||||
### Compare expanded and non-expanded metric search results
|
||||
|
||||
The expanded query returns the full names of matching metrics.
|
||||
In combination with regular expressions, you can use it to extract any part of the metric name.
|
||||
By contrast, a non-expanded query returns only the last part of the metric name, and doesn't let you extract other parts of metric names.
|
||||
|
||||
Given these example metrics:
|
||||
|
||||
- `prod.servers.001.cpu`
|
||||
- `prod.servers.002.cpu`
|
||||
- `test.servers.001.cpu`
|
||||
|
||||
These examples demonstrate how expanded and non-expanded queries can fetch specific parts of the metrics name:
|
||||
|
||||
| Non-expanded query | Results | Expanded query | Expanded results |
|
||||
| ------------------ | ---------- | ------------------------- | ---------------------------------------------------------------- |
|
||||
| `*` | prod, test | `expand(*)` | prod, test |
|
||||
| `*.servers` | servers | `expand(*.servers)` | prod.servers, test.servers |
|
||||
| `test.servers` | servers | `expand(test.servers)` | test.servers |
|
||||
| `*.servers.*` | 001,002 | `expand(*.servers.*)` | prod.servers.001, prod.servers.002, test.servers.001 |
|
||||
| `test.servers.*` | 001 | `expand(test.servers.*)` | test.servers.001 |
|
||||
| `*.servers.*.cpu` | cpu | `expand(*.servers.*.cpu)` | prod.servers.001.cpu, prod.servers.002.cpu, test.servers.001.cpu |
|
||||
|
||||
The non-expanded query is the same as an expanded query, with a regex matching the last part of the name.
|
||||
|
||||
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.
|
||||
|
||||
### Use `__searchFilter` to filter query variable results
|
||||
|
||||
> **Note:** Available in Grafana v6.5 and higher.
|
||||
|
||||
You can use `__searchFilter` in the query field to filter the query result based on what the user types in the dropdown select box.
|
||||
The default value for `__searchFilter` is `*` if you've not entered anything, and `` when used as part of a regular expression.
|
||||
|
||||
#### Search filter example
|
||||
|
||||
To use `__searchFilter` as part of the query field to enable searching for `server` while the user types in the dropdown select box:
|
||||
|
||||
Query
|
||||
|
||||
```bash
|
||||
apps.$app.servers.$__searchFilter
|
||||
```
|
||||
|
||||
TagValues
|
||||
|
||||
```bash
|
||||
tag_values(server, server=~${__searchFilter:regex})
|
||||
```
|
||||
|
||||
## Choose a variable syntax
|
||||
|
||||
|
||||
|
||||
The Graphite data source supports two variable syntaxes for use in the **Query** field:
|
||||
|
||||
- `$<varname>`, for example `apps.frontend.$server.requests.count`, which is easier to read and write but does not allow you to use a variable in the middle of a word.
|
||||
- `${varname}`, for example `apps.frontend.${server}.requests.count`, to use in expressions like `my.server${serverNumber}.count`.
|
||||
|
||||
### Templated dashboard example
|
||||
|
||||
To view an example templated dashboard, refer to [Graphite Templated Dashboard](https://play.grafana.org/dashboard/db/graphite-templated-nested).
|
||||
Reference in New Issue
Block a user