Time Series Database:Connect Grafana to TSDB

This topic describes how to connect TSDB to Grafana.

Prepare the environment

The following example shows how to install Grafana on an ECS instance, and connect Grafana to a TSDB instance over a virtual private cloud (VPC). For more information about how to use Elastic Compute Service (ECS), see What is ECS?

Create a TSDB instance and an ECS instance in the same VPC. The following requirements must be met:

• The OS of the ECS instance is 64-bit CentOS 7.3.

• The ECS instance provides at least one CPU core and 2 GB memory. The available disk storage is no less than 10 GB.

• The private IP address of the ECS instance in the VPC is added to the whitelist of the TSDB instance.

• If you want to use a browser to access Grafana over the Internet, configure a public IP address for the ECS instance.

• A security group rule has been created in the ECS console to enable access to the ECS instance over port 3000, see Create a security group.

Install and configure Grafana

Perform the following steps to install and start Grafana on the ECS instance: For more information about how to install Grafana, see Grafana official documentation.

1. Run a command in a similar manner as the following command on the ECS instance to install Grafana.

   $ sudo yum install https://dl.grafana.com/oss/release/grafana-6.2.2-1.x86_64.rpm

2. Start Grafana.

   $ sudo service grafana-server start

Connect a TSDB instance to Grafana

Perform the following steps to connect your TSDB instance that is used as a data source to Grafana:

1. Connect to the ECS instance over port 3000 by using a browser. The Grafana logon page appears.

   For example, if the public IP address of the ECS instance is 106.15.XX.XX, enter http://106.15.XX.XX:3000/ in the address bar of your browser.

2. On the Grafana logon page, enter admin for the username and the password. The Grafana homepage appears.

3. Create a data source in Grafana. You must specify the parameters provided in the following section. You can retain the default values for the other parameters.

   • Set the database type to OpenTSDB.

   • URL: Enter the private endpoint of the TSDB instance deployed in your VPC. To view this endpoint, go to the Instance Details page in the TSDB console, and check the value in the VPC Network Address field in the Basic Information section.

   • Version: Select ==2.3.

   • If you enable the user management feature for the TSDB instance, you must select Basic Auth and With Credentials and enter the authentication information of a user that has the permissions to read data from the instance.

     

4. Click Save & Test. If the Data source is working message appears on the page, the TSDB instance is connected to Grafana.

After you perform the preceding operations, you can create and use dashboards in Grafana. For more information, see Grafana official documentation.

The following section describes how to use Grafana to display TSDB time series data.

Create a monitoring dashboard that displays specific metrics

1. On the homepage of Grafana, choose Create > Dashboard, as shown in the following figure.

   

   If a dashboard is created for the TSDB instance, you can select the dashboard.

2. On the New dashboard page, click New Panel. In the New Panel dialog box, click Add Query, as shown in the following figure.

   

3. On the following page where you can edit the panel, specify parameters based on your needs.

   

   1. Specify the metric that you want to monitor and whether to aggregate the metric values in different time series.

   2. Configure a downsampling rule based on your needs. To configure a downsampling rule, specify the interval, Aggregator, and Fill parameters.

   3. Group the time series to be monitored by tag. If you want to monitor time series that correspond to all tag values of a tag, enter an asterisk (*) as the tag value.

      Important

      TSDB supports some of the aggregators that are provided by Grafana. For more information, see Query single-value data points.

      You can use Grafana to display TSDB multi-value model data. If you enter a metric name in a single-value or multi-value model, the drop-down list displays only the name of the metric. If you enter an at sign (@) after the metric name in a multi-value model, the drop-down list displays all fields of the metric. You can select the field that you want to view.

      Important

      Grafana displays only numeric values. TSDB supports numeric, string, and boolean values.

      

Use variables to simplify time series filtering

To display new time series in an existing panel in real time, you must specify the metric, tag key, or tag value for each new time series. This may increase your workload if a large number of time series exist and the number of time series is increasing at a high frequency. To simplify the procedure, Grafana allows you to use variables.

This section describes how to use variables to filter the time series that you want to display. In the example provided in this section, a variable is created and used to filter tags.

1. On the homepage of the selected dashboard, click the Settings icon.

   

2. On the Variables page, set the variable that you want to create and specify how to obtain the values of the variable.

   • Set Data source to OpenTSDB.

   • In the Query field, enter an expression that is supported by Grafana to query data in OpenTSDB.

     In this example, the variable to be created represents tag values. Therefore, an expression that starts with tag_values is used.

     

   • TSDB supports all query expressions that are provided by Grafana for OpenTSDB:

     • metrics(prefix): returns the names of all metrics that contain the specified prefix. An empty result may be returned.

     • tag_names(metric): returns all tag keys that correspond to the specified metric.

     • tag_values(metric, tagKey): returns all tag values of the specified tag key that corresponds to the specified metric.

     • suggest_tagk(prefix): returns all tag keys that contain the specified prefix for all metrics.

     • suggest_tagv(prefix): returns all tag values that contain the specified prefix for all metrics.

     For more information about the preceding query expressions, see Grafana official documentation.

     Important

     In all released Grafana versions, a limited number of query results are returned. This means that some expected metrics, tag keys, or tag values may not be returned. The Grafana community is already aware of this issue. However, for Grafana version 6.2.2 and earlier, this issue is not fixed. If you encounter this issue, we recommend that you modify your query criteria or use other temporary fixes.

3. After the variable is specified, you can use $Variable name to reference the query that is represented by the variable when you create or edit a panel in the dashboard.