This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation Data sources OpenTSDB Query editor

OpenTSDB query editor

The query editor allows you to build OpenTSDB queries visually. The available options depend on the OpenTSDB version you configured for the data source.

Access the query editor

The OpenTSDB query editor is located on the Explore page. You can also access the OpenTSDB query editor from a dashboard panel. Click the ellipsis in the upper right of the panel and select Edit.

Create a query

To create a query:

1. Select the OpenTSDB data source in a panel.
2. Configure the query using the sections described in the following documentation.

Metric section

The Metric section contains the core query configuration:

Alias patterns

The alias field supports dynamic substitution using tag values. Use the pattern $tag_<tagname> where <tagname> is the name of a tag on your metric.

Downsample section

Downsampling reduces the number of data points returned by aggregating values over time intervals. This improves query performance and reduces the amount of data transferred.

Interval format

The interval field accepts time duration strings:

When the interval is left blank, Grafana automatically calculates an appropriate interval based on the panel’s time range and pixel width. This ensures optimal data density for visualization.

Filters section

Filters (available in OpenTSDB 2.2+) provide advanced filtering capabilities that replace the legacy tag-based filtering.

Add, edit, and remove filters

To manage filters:

1. Click the + button next to “Filters” to add a new filter.
2. Configure the filter fields (Key, Type, Filter, Group by).
3. Click add filter to apply the filter.
4. To edit an existing filter, click the pencil icon next to it.
5. To remove a filter, click the x icon next to it.

You can add multiple filters to a single query. All filters are combined with AND logic.

Filter types

Group by behavior

When Group by is enabled for a filter:

• Results are split into separate time series for each unique value of the filtered tag.
• Each time series is labeled with its tag value.
• This is useful for comparing values across hosts, environments, or other dimensions.

When Group by is disabled:

• All matching time series are combined using the selected aggregator.
• A single aggregated time series is returned.

Tags section

Tags filter metrics by key-value pairs. This is the legacy filtering method for OpenTSDB versions prior to 2.2.

Add, edit, and remove tags

To manage tags:

1. Click the + button next to “Tags” to add a new tag.
2. Select or type a tag key.
3. Select or type a tag value (use * for wildcard).
4. Click add tag to apply the tag filter.
5. To edit an existing tag, click the pencil icon next to it.
6. To remove a tag, click the x icon next to it.

Rate section

The Rate section computes the rate of change, which is essential for counter metrics that continuously increment.

When to use rate calculation

Enable Rate when your metric is a continuously increasing counter, such as:

• Network bytes sent/received
• Request counts
• Error counts
• Disk I/O operations

The rate calculation converts cumulative values into per-second rates, making the data more meaningful for visualization.

Counter settings

Enable Counter when your metric can reset to zero (for example, after a service restart). The counter settings help OpenTSDB calculate correct rates across resets:

• Counter max: Set this to the maximum value your counter can reach before wrapping. For 64-bit counters, use 18446744073709551615. For 32-bit counters, use 4294967295.
• Reset value: The value the counter resets to, typically 0.

Explicit tags

When Explicit tags is enabled (version 2.3+), OpenTSDB only returns time series that have all the tags specified in your query. This prevents unexpected results when some time series are missing tags that others have.

Aggregators

The aggregator function combines multiple time series into one. Grafana fetches the list of available aggregators from your OpenTSDB server, so you may see additional aggregators beyond those listed here.

Common aggregators

Interpolation aggregators

These aggregators handle missing data points differently:

Fill policies

Fill policies (available in OpenTSDB 2.2+) determine how to handle missing data points during downsampling. This is important when your data has gaps or irregular collection intervals.

Choose the right fill policy

• Use none (default) when you want to see actual data gaps in your visualizations.
• Use null when you want graphs to show breaks at missing data points.
• Use zero when missing data should be interpreted as zero (for example, no requests during a period).
• Use nan when you need missing values to propagate through calculations.

Autocomplete suggestions

The query editor provides autocomplete suggestions to help you build queries quickly and accurately.

What autocomplete provides

Autocomplete requirements

For autocomplete to work:

• The OpenTSDB suggest API must be enabled on your server.
• Metrics must exist in your OpenTSDB database.
• The Lookup limit setting in your data source configuration controls the maximum number of suggestions returned.

If autocomplete isn’t working, refer to Troubleshooting.

Use template variables

You can use template variables in any text field in the query editor. Template variables are replaced with their current values when the query executes.

Common uses include:

• Metric field: $metric to dynamically select metrics.
• Filter values: $host to filter by a variable-selected host.
• Tag values: $environment to filter by environment.

For more information about creating and using template variables, refer to Template variables.

Query examples

The following examples demonstrate common query patterns.

Basic metric query with tag filtering

This query returns the average CPU usage for the host webserver01.

Query with wildcard filter (OpenTSDB 2.2+)

This query sums HTTP request counts across all hosts matching web-* and groups results by host.

Rate calculation for network counters

This query calculates the rate of bytes received per second. The counter max is set to the 64-bit unsigned integer maximum to handle counter wraps correctly.

Using alias patterns

This query uses the alias pattern to create readable legend labels like webserver01 - Response Time.

Downsampling with custom interval

This query downsamples disk I/O data to 5-minute averages, filling gaps with zero values.

Compare environments with filters

This query shows error counts for both staging and production environments as separate time series for comparison.

Exclude specific hosts

This query shows CPU usage for all hosts except test-server and dev-server.

Query with explicit tags (version 2.3+)

This query only returns time series that have the host tag defined, excluding any time series that are missing this tag.

Next steps

• Use template variables to create dynamic, reusable dashboards.
• Set up alerting to get notified when metrics cross thresholds.
• Troubleshoot issues if you encounter problems with queries.