1+++ 2title = "OpenTSDB" 3description = "Guide for using OpenTSDB in Grafana" 4keywords = ["grafana", "opentsdb", "guide"] 5aliases = ["/docs/grafana/latest/features/opentsdb", "/docs/grafana/latest/features/datasources/opentsdb/"] 6weight = 1100 7+++ 8 9# Using OpenTSDB in Grafana 10 11Grafana ships with advanced support for OpenTSDB. This topic explains options, variables, querying, and other options specific to the OpenTSDB data source. Refer to [Add a data source]({{< relref "add-a-data-source.md" >}}) for instructions on how to add a data source to Grafana. Only users with the organization admin role can add data sources. 12 13## OpenTSDB settings 14 15To access OpenTSDB settings, hover your mouse over the **Configuration** (gear) icon, then click **Data Sources**, and then click the OpenTSDB data source. 16 17| Name | Description | 18| ----------------- | --------------------------------------------------------------------------------------- | 19| `Name` | The data source name. This is how you refer to the data source in panels and queries. | 20| `Default` | Default data source means that it will be pre-selected for new panels. | 21| `URL` | The HTTP protocol, IP, and port of your OpenTSDB server (default port is usually 4242) | 22| `Allowed cookies` | List the names of cookies to forward to the data source. | 23| `Version` | Version = opentsdb version, either <=2.1 or 2.2 | 24| `Resolution` | Metrics from opentsdb may have datapoints with either second or millisecond resolution. | 25| `Lookup limit` | Default is 1000. | 26 27## Query editor 28 29Open a graph in edit mode by click the title. Query editor will differ if the data source has version <=2.1 or = 2.2. 30In the former version, only tags can be used to query OpenTSDB. But in the latter version, filters as well as tags 31can be used to query opentsdb. Fill Policy is also introduced in OpenTSDB 2.2. 32 33 34 35> **Note:** While using OpenTSDB 2.2 data source, make sure you use either Filters or Tags as they are mutually exclusive. If used together, might give you weird results. 36 37### Auto complete suggestions 38 39As soon as you start typing metric names, tag names and tag values , you should see highlighted auto complete suggestions for them. 40The autocomplete only works if the OpenTSDB suggest API is enabled. 41 42## Templating queries 43 44Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. 45Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data 46being displayed in your dashboard. 47 48Check out the [Templating]({{< relref "../variables/_index.md" >}}) documentation for an introduction to the templating feature and the different 49types of template variables. 50 51### Query variable 52 53Grafana's OpenTSDB data source supports template variable queries. This means you can create template variables 54that fetch the values from OpenTSDB. For example, metric names, tag names, or tag values. 55 56When using OpenTSDB with a template variable of `query` type you can use following syntax for lookup. 57 58| Query | Description | 59| --------------------------- | --------------------------------------------------------------------------------- | 60| `metrics(prefix)` | Returns metric names with specific prefix (can be empty) | 61| `tag_names(cpu)` | Returns tag names (i.e. keys) for a specific cpu metric | 62| `tag_values(cpu, hostname)` | Returns tag values for metric cpu and tag key hostname | 63| `suggest_tagk(prefix)` | Returns tag names (i.e. keys) for all metrics with specific prefix (can be empty) | 64| `suggest_tagv(prefix)` | Returns tag values for all metrics with specific prefix (can be empty) | 65 66If you do not see template variables being populated in `Preview of values` section, you need to enable 67`tsd.core.meta.enable_realtime_ts` in the OpenTSDB server settings. Also, to populate metadata of 68the existing time series data in OpenTSDB, you need to run `tsdb uid metasync` on the OpenTSDB server. 69 70### Nested templating 71 72One template variable can be used to filter tag values for another template variable. First parameter is the metric name, 73second parameter is the tag key for which you need to find tag values, and after that all other dependent template variables. 74Some examples are mentioned below to make nested template queries work successfully. 75 76| Query | Description | 77| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | 78| `tag_values(cpu, hostname, env=$env)` | Return tag values for cpu metric, selected env tag value and tag key hostname | 79| `tag_values(cpu, hostname, env=$env, region=$region)` | Return tag values for cpu metric, selected env tag value, selected region tag value and tag key hostname | 80 81For details on OpenTSDB metric queries, check out the official [OpenTSDB documentation](http://opentsdb.net/docs/build/html/index.html) 82 83## Configure the data source with provisioning 84 85It's now possible to configure data sources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for data sources on the [provisioning docs page]({{< relref "../administration/provisioning/#datasources" >}}) 86 87Here are some provisioning examples for this data source. 88 89```yaml 90apiVersion: 1 91 92datasources: 93 - name: OpenTsdb 94 type: opentsdb 95 access: proxy 96 url: http://localhost:4242 97 jsonData: 98 tsdbResolution: 1 99 tsdbVersion: 1 100``` 101
