root
/
grafana
mirror of https://github.com/grafana/grafana.git
1
0
Fork 0
Code Issues Actions 142 Packages Projects Releases Wiki Activity

[release-12.0.3] Docs: Updated the Graphite data source docs (#107432)
Lint Frontend / Verify i18n (push) Waiting to run Details
Lint Frontend / Lint (push) Waiting to run Details
Lint Frontend / Typecheck (push) Waiting to run Details
Lint Frontend / Betterer (push) Waiting to run Details
End-to-end tests / Build & Package Grafana (push) Waiting to run Details
End-to-end tests / ${{ matrix.suite }} (dashboards-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (panels-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (smoke-tests-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (various-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (old arch) (old-arch/dashboards-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (old arch) (old-arch/panels-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (old arch) (old-arch/smoke-tests-suite) (push) Blocked by required conditions Details
End-to-end tests / ${{ matrix.suite }} (old arch) (old-arch/various-suite) (push) Blocked by required conditions Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (1) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (2) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (3) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (4) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (5) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (6) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (7) (push) Waiting to run Details
Frontend tests / Unit tests (${{ matrix.chunk }} / 8) (8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Integration Tests / Sqlite (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Integration Tests / MySQL (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (1/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (2/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (3/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (4/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (5/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (6/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (7/8) (push) Waiting to run Details
Integration Tests / Postgres (${{ matrix.shard }}) (8/8) (push) Waiting to run Details
Dispatch sync to mirror / dispatch-job (push) Waiting to run Details
publish-technical-documentation-release / sync (push) Has been cancelled Details 

Docs: Updated the Graphite data source docs (#105426)

* initial edits

* edits to config doc

* query editor updates

* ran prettier

* updates

* made more updates

* final edits

* ran prettier, updated some descriptions

* a few more quick edits

* one more definition

(cherry picked from commit dec2df8379)

Co-authored-by: Larissa Wandzura <126723338+lwandz13@users.noreply.github.com>
This commit is contained in:
grafana-delivery-bot[bot] 2025-07-17 16:41:47 +01:00 committed by GitHub
parent f5aa69691c
commit bf23c3c9e1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 372 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
docs/sources/datasources/graphite/_index.md
View File

@ -2,7 +2,7 @@
aliases:
- ../data-sources/graphite/
- ../features/datasources/graphite/
description: Guide for using Graphite in Grafana
description: Introduction to the Graphite data source in Grafana.
keywords:
- grafana
- graphite
@ -46,6 +46,36 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
transformations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/
alerting:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/
visualizations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
annotate-visualizations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/annotate-visualizations/
set-up-grafana-monitoring:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/set-up-grafana-monitoring/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/set-up-grafana-monitoring/
---
# Graphite data source
@ -54,87 +84,30 @@ 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](ref: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](#configure-the-data-source) so that your Grafana instance's users can create queries in its [query editor](query-editor/) when they [build dashboards](ref:build-dashboards) and use [Explore](ref:explore).
{{< docs/play title="Graphite: Sample Website Dashboard" url="https://play.grafana.org/d/000000003/" >}}
## Configure the data source
To configure basic settings for the data source, complete the following steps:
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `Graphite` in the search bar.
1. Click **Graphite**.
The **Settings** tab of the data source is displayed.
1. Set the data source's basic configuration options:
| 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](ref: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. If you are using Grafana Cloud Graphite, this should be set to `1.1.x`. |
| **Type** | Select your type of Graphite. If you are using Grafana Cloud Graphite, this should be set to `Default`. |
### Integrate with Loki
When you change the data source selection in [Explore](ref: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](ref: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](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](template-variables/).
Grafana exposes metrics for Graphite on the `/metrics` endpoint.
For detailed instructions, refer to [Internal Grafana metrics](ref:internal-grafana-metrics).
## Get Grafana metrics into Graphite
Grafana exposes metrics for Graphite on the `/metrics` endpoint.
For detailed instructions, refer to [Internal Grafana metrics](ref:internal-grafana-metrics).
Refer to [Internal Grafana metrics](ref:set-up-grafana-monitoring) for more information.
## Graphite and Loki integration
When you change the data source selection in [Explore](ref: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. Grafana automatically transforms queries using tags with `seriesByTags()` without requiring additional setup.
## Get the most out of the data source
After installing and configuring the Graphite data source you can:
- Create a wide variety of [visualizations](ref:visualizations)
- Configure and use [templates and variables](ref:variables)
- Add [transformations](ref:transformations)
- Add [annotations](ref:annotate-visualizations)
- Set up [alerting](ref:alerting)

179
docs/sources/datasources/graphite/configure/index.md Normal file
View File

@ -0,0 +1,179 @@
---
aliases:
- ../data-sources/graphite/
- ../datasources/graphite/
- ../features/datasources/graphite/
description: This document provides instructions for configuring the Graphite data source.
keywords:
- grafana
- graphite
- guide
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure
title: Configure the Graphite data source
weight: 100
refs:
explore:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/
provisioning-data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#data-sources
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#data-sources
internal-grafana-metrics:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/set-up-grafana-monitoring/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/set-up-grafana-monitoring/
build-dashboards:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/
configure-authentication:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-authentication/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-authentication/
data-source-management:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
private-data-source-connect:
- pattern: /docs/grafana/
destination: docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/
- pattern: /docs/grafana-cloud/
destination: docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/
configure-pdc:
- pattern: /docs/grafana/
destination: /docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/configure-pdc/#configure-grafana-private-data-source-connect-pdc
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/configure-pdc/#configure-grafana-private-data-source-connect-pdc
---
# Configure the Graphite data source
This document provides instructions for configuring the Graphite data source and explains available configuration options. For general information on managing data sources, refer to [Data source management](ref:data-source-management).
## Before you begin
- You must have the `Organization administrator` role to configure the Graphite data source.
Organization administrators can also [configure the data source via YAML](#provision-the-data-source) with the Grafana provisioning system.
- Grafana comes with a built-in Graphite data source plugin, eliminating the need to install a plugin.
- Familiarize yourself with your Graphite security configuration and gather any necessary security certificates and client keys.
## Add the Graphite data source
To configure basic settings for the data source, complete the following steps:
1. Click **Connections** in the left-side menu.
1. Click **Add new connection**
1. Type `Graphite` in the search bar.
1. Select the **Graphite data source**.
1. Click **Add new data source** in the upper right.
Grafana takes you to the **Settings** tab, where you will set up your Graphite configuration.
## Configuration options in the UI
Following is a list of configuration options for Graphite.
| Setting | Description |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | The display name for the data source. This is how you'll reference it in panels and queries. <br>Examples: `graphite-1`, `graphite-metrics`. |
| **Default** | When enabled, sets this data source as the default for dashboard panels. It will be automatically selected when creating new panels. |
**HTTP:**
| Setting | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **URL** | Sets the HTTP protocol, IP, and port of your `graphite-web` or `graphite-api` installation. <br>Since the access method is set to _Server_, the URL must be accessible from the Grafana backend. |
| **Allowed cookies** | By default, Grafana removes forwarded cookies. Specify cookie names here to allow them to be forwarded to the data source. |
| **Timeout** | Sets the HTTP request timeout in seconds. |
**Auth:**
| **Setting** | **Description** |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Basic Auth** | Toggle on to enable basic authentication to the data source. |
| &nbsp;&nbsp;**User** | Sets the username used for basic authentication. |
| &nbsp;&nbsp;**Password** | Enter the password used for basic authentication. |
| **With Credentials** | Toggle on to include cookies and authentication headers in cross-origin requests. |
| **TLS Client Auth** | Toggle on to enable TLS client authentication (both server and client are verified). |
| &nbsp;&nbsp;**ServerName** | The server name used to verify the hostname on the certificate returned by the server. |
| &nbsp;&nbsp;**Client Cert** | Client certificate generated by a Certificate Authority (CA) or self-signed. |
| &nbsp;&nbsp;**Client Key** | Private key used to encrypt communication between the client and server. Also generated by a CA or self-signed. |
| **With CA Cert** | Toggle on to authenticate with a CA certificate. |
| &nbsp;&nbsp;**CA Cert** | CA certificate used to validate the server certificate. |
| **Skip TLS Verify** | Toggle on to bypass TLS certificate validation. Not recommended unless necessary or for testing purposes. |
| **Forward OAuth Identity** | Toggle on to forward the user's upstream OAuth identity to the data source. Grafana includes the access token in the request. |
**Custom HTTP Headers:**
Pass along additional information and metadata about the request or response.
| **Setting** | **Description** |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| **Header** | Add a custom header. This allows custom headers to be passed based on the needs of your Graphite instance. |
| **Value** | The value of the header. |
**Graphite details:**
| **Setting** | **Description** |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Version** | Select your Graphite version from the drop-down. This controls which functions are available in the Graphite query editor. Use `1.1.x` for Grafana Cloud Graphite. |
| **Graphite backend type** | Select the Graphite backend type. Choosing `Metrictank` enables additional features like query processing metadata. (`Metrictank` is a multi-tenant time series engine compatible with Graphite.) Use `Default` for Grafana Cloud Graphite. |
| **Rollup indicator** | Toggle on to display an info icon in panel headers when data aggregation (rollup) occurs. Only available when `Metrictank` is selected. |
**Label mappings:**
Label mappings are the rules you define to tell Grafana how to pull pieces of the Graphite metric path into Loki labels when switching data sources. They are currently only supported between Graphite and Loki queries.
When you change your data source from Graphite to Loki, your queries are automatically mapped based on the rules you define. To create a mapping, specify the full path of the metric and replace the nodes you want to map with label names, using parentheses. The corresponding label values are extracted from your Graphite query during the data source switch.
Grafana automatically maps all Graphite tags to labels, even if you haven’t defined explicit mappings. When using matching patterns with `{}`(e.g., `metric.{a,b}.value`), Grafana converts them to Loki’s regular expression matching syntax. If your queries include functions, Graphite extracts the relevant metrics and tags, then matches them against your mappings.
| **Graphite Query** | **Mapped to Loki Query** |
| -------------------------------------------------------- | -------------------------------- |
| `alias(servers.west.001.cpu,1,2)` | `{cluster="west", server="001"}` |
| `alias(servers.*.{001,002}.*,1,2)` | `{server=~"(001,002)"}` |
| `interpolate(seriesByTag('foo=bar', 'server=002'), inf)` | `{foo="bar", server="002"}` |
| **Setting** | **Description** |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Private data source connect** | _Only for Grafana Cloud users._ Establishes a private, secured connection between a Grafana Cloud stack and data sources within a private network. Use the drop-down to locate the PDC URL. For setup instructions, refer to [Private data source connect (PDC)](ref:private-data-source-connect) and [Configure PDC](ref:configure-pdc). Click **Manage private data source connect** to open your PDC connection page and view your configuration details. |
|
After configuring your Graphite data source options, click **Save & test** at the bottom to test the connection. You should see a confirmation dialog box that says:
**Data source is working**
## Provision the data source
You can define and configure the data source in YAML files as part of the Grafana provisioning system.
For more information about provisioning, and for lists of common configuration options and JSON data options, refer to [Provisioning data sources](ref:provisioning-data-sources).
Example Graphite YAML provisioning file:
```yaml
apiVersion: 1
datasources:
- name: Graphite
type: graphite
access: proxy
url: http://localhost:8080
jsonData:
graphiteVersion: '1.1'
```

90
docs/sources/datasources/graphite/query-editor/index.md
View File

@ -1,7 +1,7 @@
---
aliases:
- ../../data-sources/graphite/query-editor/
description: Guide for using the Graphite data source's query editor
description: Guide for using the Graphite data source query editor.
keywords:
- grafana
- microsoft
@ -41,45 +41,53 @@ refs:
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.
It supports a variety 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](ref:query-transform-data).
## View the raw query
## Query editor elements
To see the raw text of the query that Grafana sends to Graphite, click the **Toggle text edit mode** (pencil) icon.
The query editor consists of the following elements:
- **Series** - A series in Graphite is a unique time-series dataset, represented by a specific metric name and timestamped values. Click **select metric** to select a metric from the drop-down.
- **Functions** - Graphite uses functions to manipulate data. Click the **+ sign** to view a list of functions in the drop-down. You can create a query with multiple functions.
To view the raw query, click the **Pencil icon** in the upper right. Click the **Pencil icon** again to continue adding series and functions.
## 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.
Click **Select metric** to browse the available metrics. You can navigate using your mouse or arrow keys. You can also select a wildcard.
{{< 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.
Click the **+ sign** next to **Function** to add a function from the drop-down. You can also search by typing the first few letters of the function name.
- 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.
After selecting a function, Grafana adds it to your query and automatically places your cursor in the first parameter field.
To edit a parameter, click it to open an editable text box.
To remove a function simply click on it, then click the **X icon** that appears above it.
{{< 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.
Some functions like `aliasByNode` support an optional second argument. To add this argument, hover your mouse over the argument and a dialog box appears. To remove the second optional parameter, click on it to delete it.
To learn more, refer to [Graphite's documentation on functions](https://graphite.readthedocs.io/en/latest/functions.html).
Refer to [Functions](https://graphite.readthedocs.io/en/latest/functions.html) in the Graphite documentation for more information.
{{< admonition type="warning" >}}
Some functions take a second argument that may be a function that returns a series. If you are adding a second argument that is a function, it is suggested to use a series reference from a second query instead of the function itself. The query editor does not currently support parsing of a second argument that is a function when switching between the query editor and the code editor.
{{< /admonition >}}
{{% admonition type="warning" %}}
Some functions accept a second argument, which can itself be another function that returns a series. If you need to add a second argument that is a function, Grafana recommends using a series reference from a second query instead of embedding the function directly.
Currently, the query editor does not support parsing a second function argument when switching between the query builder and the code editor.
{{% /admonition %}}
### Sort labels
If you have the same labels on multiple graphs, they are both sorted differently and use different colors.
If the same labels appear on multiple graphs, they may be sorted differently and assigned different colors.
To avoid this and consistently order labels by name, use the `sortByName()` function.
To ensure consistent sorting and coloring, use the `sortByName()` function to order labels alphabetically.
### Modify the metric name in my tables or charts
@ -91,60 +99,52 @@ Grafana consolidates all Graphite metrics so that Graphite doesn't return more d
By default, Grafana consolidates data points using the `avg` function.
To control how Graphite consolidates metrics, use the Graphite `consolidateBy()` function.
{{< admonition type="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.
{{< /admonition >}}
{{% admonition type="note" %}}
Grafana calculates legend summary values like `max`, `min`, and `total` on the client side, after data has been calculated.
Depending on the consolidation function used, only one or two of these values may be accurate at the same time.
{{% /admonition %}}
### Combine time series
To combine time series, click **Combine** in the **Functions** list.
### Select and explor data with tags
### Select and explore data with tags
In Graphite, _everything_ is a tag.
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.
{{< admonition type="note" >}}
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.
{{< /admonition >}}
{{% admonition type="note" %}}
Regular expression searches 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.
{{% /admonition %}}
## Nest queries
## Nested queries
You can reference a query by the "letter" of its row, similar to a spreadsheet.
Grafana lets you reference one query from another using its query letter, similar to how cell references work in 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.
For example, if you add a second query and want to build on the results of query A, you can reference it using #A.
This approach allows you to build compound or nested queries, making your panels more flexible and easier to manage.
## 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.
To display multiple time series on the same graph, use wildcards in your query to return all matching series at once.
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.
For example, to monitor CPU utilization across a variety of metrics, you can use a single query like `cpu.percent.*.g` to retrieve all matching time series.
This approach is more efficient than writing separate queries for each series, such as `cpu.percent.user.g`, `cpu.percent.system.g`, and others, which would result in multiple queries to the data source.
## Apply annotations
[Annotations](ref:annotate-visualizations) overlay rich event information on top of graphs.
You can add annotation queries in the Dashboard menu's Annotations view.
[Annotations](ref: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](ref: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.
When you change the data source to Loki in Explore, your Graphite queries are automatically converted to Loki queries. Loki label names and values are extracted based on the mapping information defined in your Graphite data source configuration. Grafana automatically transforms queries that use tags with `seriesByTags()` without requiring additional setup.

167
docs/sources/datasources/graphite/template-variables/index.md
View File

@ -1,7 +1,7 @@
---
aliases:
- ../../data-sources/graphite/template-variables/
description: Guide for using template variables when querying the Graphite data source
description: Guide for using template variables when querying the Graphite data source.
keywords:
- grafana
- graphite
@ -37,122 +37,153 @@ refs:
# 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 lists these variables in drop-down selection 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](ref:variables) and [Add and manage variables](ref:add-template-variables) documentation.
## Select a query type
To view an example templated dashboard, refer to [Graphite Templated Nested dashboard](https://play.grafana.org/d/cvDFGseGz/graphite-templated-nested).
There are three query types for Graphite template variables
## Use query variables
| Query Type | Description |
| ----------------- | ------------------------------------------------------------------------------- |
| Default Query | Use functions such as `tags()`, `tag_values()`, `expand(<metric>)` and metrics. |
| Value Query | Returns all the values for a query that includes a metric and function. |
| Metric Name Query | Returns all the names for a query that includes a metric and function. |
With Graphite data sources, you can only create query variables. Grafana supports three specific query types for Graphite-based variables:
| Query type | Description | Example usage |
| --------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Default query** | Allows you to dynamically list metrics, nodes, or tag values using Graphite functions. | `tag_values(apps.*.requests.count, app)` |
| **Value query** | Returns all the values for a query that includes a metric and function. | `tag_values(apps.*.status.*, status)` |
| **Metric name query** | Returns all the names for a query that includes a metric and function. | `apps.*.requests.count` |
### Choose a variable syntax
The Graphite data source supports two variable syntaxes for use in the **Query** field.
![Variable syntax example](/static/img/docs/v2/templated_variable_parameter.png)
Grafana allows two ways to reference variables in a query:
| **Syntax** | **Example** |
| ------------ | ---------------------------------------- |
| `$varname` | `apps.frontend.$server.requests.count` |
| `${varname}` | `apps.frontend.${server}.requests.count` |
- **Shorthand syntax (`$varname`)** is convenient for simple paths but doesn't work when the variable is adjacent to characters (e.g., `cpu$coreLoad`).
- **Full syntax (`${varname}`)** is more flexible and works in any part of the string, including embedded within words.
Choose the format that best fits the structure of your Graphite metric path.
## Use tag variables
To create a variable using tag values, use the Grafana functions `tags` and `tag_values`.
Grafana supports tag-based variables for Graphite, allowing you to dynamically populate drop-downs based on tag keys and values in your metric series. To do this, use the Graphite functions `tags()` and `tag_values()` in your variable queries.
| 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. |
| Query | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `tags()` | Returns a list of all tag keys in the Graphite database. |
| `tags(server=~backend\*)` | Returns tag keys only from series that match the provided filter expression. |
| `tag_values(server)` | Returns all values for the specified tag key. |
| `tag_values(server, server=~backend\*)` | Returns tag values for a given key, filtered to only those that appear in matching series. |
Multiple filter expressions and expressions can contain other variables. For example:
You can use multiple filter expressions, and those expressions can include other Grafana variables. For example:
```
tag_values(server, server=~backend\*, app=~${apps:regex})
```
This query returns all server tag values from series where the `server` tag matches backend\* and the `app` tag matches the regex-filtered values from another variable ${apps}.
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-value variables in tag queries
**Using regular expression formatting and the equal tilde operator `=~`:**
Multi-value variables in tag queries use the advanced formatting syntax for variables: `{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}
```
This query tells Grafana to format the selected values in the `servers` variable as a regular expression (e.g., (`server1`|`server2`) if two servers are selected).
For more information, refer to [Advanced variable format options](ref:variable-syntax-advanced-variable-format-options).
### Filter with multiple expressions
When using multi-value variables in tag queries, append `${var:regex}` to the variable name to apply regex formatting.
```
tag_values(server, app=~${apps:regex})
```
This query returns only series where the app tag matches the selected values in $`{apps}`, formatted as a regular expression. `=~` is the regular expression operator
Non-tag queries use the default `glob` formatting for multi-value variables.
## Use other query variables
When writing queries, use the metric find type of query.
When writing queries, use the **metric find** query type to retrieve dynamic values.
For example, a query like `prod.servers.*` fills the variable with all possible values that exist in the wildcard position.
For example, the query `prod.servers.*` populates the variable with all values that exist at 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.*)`.
Note that the results include only the values found at the last level of the query path.
To return full metric paths that match your 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.
When querying Graphite metrics in Grafana, you can choose between using an **expanded** or **non-expanded** query:
Given these example metrics:
- **Expanded queries** (using the `expand()` function) return the **full metric paths** that match your query.
- **Non-expanded queries** return only the **last segment** of each matching metric path, which limits your ability to extract or filter based on deeper parts of the metric name.
Expanded queries are especially useful when working with regular expressions to match or extract specific parts of the metric path.
Suppose your Graphite database contains the following 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:
The following table illustrates the difference between expanded and non-expanded queries:
| 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 |
| **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.
{{% admonition type="note" %}}
A non-expanded query query works like an expanded query but returns only the final segment of each matched metric.
{{% /admonition %}}
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.
Grafana also supports **nested variables**, which allow you to reference other variables in a query.
### Use `__searchFilter` to filter query variable results
For example:
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.
```
apps.$app.servers.*
```
#### Search filter example
This query uses the selected value of the `$app` variable to dynamically filter the metric path. The variable `$app` contains one or more application names and `servers.*` matches all servers for the given application.
To use `__searchFilter` as part of the query field to enable searching for `server` while the user types in the dropdown select box:
### Filter query variable results with `__searchFilter`
Query
Grafana provides the variable `__searchFilter`, which you can use to dynamically filter query results based on what the user types into the variable drop-down.
When the drop-down is empty or blank, `__searchFilter` defaults to `*`, which means it returns all possible values. If you type a string, Grafana replaces `__searchFilter` with that input.
```bash
To use `__searchFilter` as part of the query field to enable searching for `server` while the user types in the drop-down select box:
Query:
```
apps.$app.servers.$__searchFilter
```
TagValues
TagValues:
```bash
```
tag_values(server, server=~${__searchFilter:regex})
```
## Choose a variable syntax
![variable](/static/img/docs/v2/templated_variable_parameter.png)
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 Nested dashboard](https://play.grafana.org/d/cvDFGseGz/graphite-templated-nested).