Graphite data source on Grafana Labs

Configure the Graphite data source

Fri, 03 Apr 2026 19:43:06 +0000

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.

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 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:

Click Connections in the left-side menu.
Click Add new connection
Type Graphite in the search bar.
Select the Graphite data source.
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. 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. 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.
User	Sets the username used for basic authentication.
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).
ServerName	The server name used to verify the hostname on the certificate returned by the server.
Client Cert	Client certificate generated by a Certificate Authority (CA) or self-signed.
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.
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) and 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.

Example Graphite YAML provisioning file:

apiVersion: 1

datasources:
  - name: Graphite
    type: graphite
    access: proxy
    url: http://localhost:8080
    jsonData:
      graphiteVersion: '1.1'

Graphite query editor

Fri, 03 Apr 2026 19:43:06 +0000

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 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.

Query editor elements

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 browse the available metrics. You can navigate using your mouse or arrow keys. You can also select a wildcard.

Functions

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.

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.

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.

Refer to Functions in the Graphite documentation for more information.

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.

Sort labels

If the same labels appear on multiple graphs, they may be sorted differently and assigned different colors.

To ensure consistent sorting and coloring, use the sortByName() function to order labels alphabetically.

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
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.

Combine time series

To combine time series, click Combine in the Functions list.

Select and explore 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.

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.

Nested queries

Grafana lets you reference one query from another using its query letter, similar to how cell references work in a spreadsheet.

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 display multiple time series on the same graph, use wildcards in your query to return all matching series at once.

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 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

Integration with Loki

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.

Graphite template variables

Fri, 03 Apr 2026 19:43:06 +0000

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 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 and Add and manage variables documentation.

To view an example templated dashboard, refer to Graphite Templated Nested dashboard.

Use query variables

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.

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

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 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.

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.

Using regular expression formatting and the equal tilde operator =~:

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.

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 query type to retrieve dynamic values.

For example, the query prod.servers.* populates the variable with all values that exist at the wildcard position (*).

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

When querying Graphite metrics in Grafana, you can choose between using an expanded or non-expanded query:

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

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`

Note
A non-expanded query query works like an expanded query but returns only the final segment of each matched metric.

Grafana also supports nested variables, which allow you to reference other variables in a query.

For example:

apps.$app.servers.*

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.

Filter query variable results with `__searchFilter`

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.

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:

tag_values(server, server=~${__searchFilter:regex})

Troubleshoot Graphite data source issues

Fri, 03 Apr 2026 19:43:06 +0000

Troubleshoot Graphite data source issues

This document provides solutions for common issues you might encounter when using the Graphite data source.

Connection issues

Use the following troubleshooting steps to resolve connection problems between Grafana and your Graphite server.

Data source test fails with “Unable to connect”:

If the data source test fails, verify the following:

The URL in your data source configuration is correct and accessible from the Grafana server.
The Graphite server is running and accepting connections.
Any firewall rules or network policies allow traffic between Grafana and the Graphite server.
If using TLS, ensure your certificates are valid and properly configured.

To test connectivity, run the following command from the Grafana server:

curl -v <GRAPHITE_URL>/render

Replace <GRAPHITE_URL> with your Graphite server URL. A successful connection returns a response from the Graphite server.

Authentication errors:

If you receive 401 or 403 errors:

Verify your Basic Auth username and password are correct.
Ensure the With Credentials toggle is enabled if your Graphite server requires cookies for authentication.
Check that your TLS client certificates are valid and match what the server expects.

For detailed authentication configuration, refer to Configure the Graphite data source.

Query issues

Use the following troubleshooting steps to resolve problems with Graphite queries.

No data returned:

If your query returns no data:

Verify the metric path exists in your Graphite server by testing directly in the Graphite web interface.
Check that the time range in Grafana matches when data was collected.
Ensure wildcards in your query match existing metrics.
Confirm your query syntax is correct for your Graphite version.

HTTP 500 errors with HTML content:

Graphite-web versions before 1.6 return HTTP 500 errors with full HTML stack traces when a query fails. If you see error messages containing HTML tags:

Check the Graphite server logs for the full error details.
Verify your query syntax is valid.
Ensure the requested time range doesn’t exceed your Graphite server’s capabilities.
Check that all functions used in your query are supported by your Graphite version.

Parser errors in the query editor:

If the query editor displays parser errors:

Check for unbalanced parentheses in function calls.
Verify that function arguments are in the correct format.
Ensure metric paths don’t contain unsupported characters.

For query syntax help, refer to Graphite query editor.

Version and feature issues

Use the following troubleshooting steps to resolve problems related to Graphite versions and features.

Functions missing from the query editor:

If expected functions don’t appear in the query editor:

Verify the correct Graphite version is selected in the data source configuration.
The available functions depend on the configured version. For example, tag-based functions require Graphite 1.1 or later.
If using a custom Graphite installation with additional functions, ensure the version setting matches your server.

Tag-based queries not working:

If seriesByTag() or other tag functions fail:

Confirm your Graphite server is version 1.1 or later.
Verify the Graphite version setting in your data source configuration matches your actual server version.
Check that tags are properly configured in your Graphite server.

Performance issues

Use the following troubleshooting steps to address slow queries or timeouts.

Queries timing out:

If queries consistently time out:

Increase the Timeout setting in the data source configuration.
Reduce the time range of your query.
Use more specific metric paths instead of broad wildcards.
Consider using summarize() or consolidateBy() functions to reduce the amount of data returned.
Check your Graphite server’s performance and resource utilization.

Slow autocomplete in the query editor:

If metric path autocomplete is slow:

This often indicates a large number of metrics in your Graphite server.
Use more specific path prefixes to narrow the search scope.
Check your Graphite server’s index performance.

MetricTank-specific issues

If you’re using MetricTank as your Graphite backend, use the following troubleshooting steps.

Rollup indicator not appearing:

If the rollup indicator doesn’t display when expected:

Verify Metrictank is selected as the Graphite backend type in the data source configuration.
Ensure the Rollup indicator toggle is enabled.
The indicator only appears when data aggregation actually occurs.

Unexpected data aggregation:

If you see unexpected aggregation in your data:

Check the rollup configuration in your MetricTank instance.
Adjust the time range or use consolidateBy() to control aggregation behavior.
Review the query processing metadata in the panel inspector for details on how data was processed.

Get additional help

If you continue to experience issues:

Check the Grafana community forums for similar issues and solutions.
Review the Graphite documentation for additional configuration options.
Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Advanced customer.

When reporting issues, include the following information:

Grafana version
Graphite version (for example, 1.1.x) and backend type (Default or MetricTank)
Authentication method (Basic Auth, TLS, or none)
Error messages (redact sensitive information)
Steps to reproduce the issue
Relevant configuration such as data source settings, timeout values, and Graphite version setting (redact passwords and other credentials)
Sample query (if applicable, with sensitive data redacted)

Graphite data source on Grafana Labs

Configure the Graphite data source

Configure the Graphite data source

Before you begin

Add the Graphite data source

Configuration options in the UI

Provision the data source

Graphite query editor

Graphite query editor

Query editor elements

Choose metrics to query

Functions

Sort labels

Modify the metric name in my tables or charts

Consolidate data points

Combine time series

Select and explore data with tags

Nested queries

Use wildcards to make fewer queries

Apply annotations

Integration with Loki

Graphite template variables

Graphite template variables

Use query variables

Choose a variable syntax

Use tag variables

Filter with multiple expressions

Use other query variables

Compare expanded and non-expanded metric search results

Filter query variable results with __searchFilter

Troubleshoot Graphite data source issues

Troubleshoot Graphite data source issues

Connection issues

Query issues

Version and feature issues

Performance issues

MetricTank-specific issues

Get additional help

Filter query variable results with `__searchFilter`