All Products
Search
Document Center

Developer guide

Last Updated: May 19, 2022

This topic describes the label operators and aggregation operations that are supported by TSDB for Prometheus.

PromQL

Prometheus Query Language (PromQL) is a functional query language that is provided by Prometheus. PromQL allows you to select and aggregate time series data in real time. For more information about PromQL, see PromQL documentation on the official website of Prometheus.

TSDB for Prometheus provides a built-in interface for the remote storage adapter. The built-in interface is compatible with the query feature of Prometheus.

Supported label operators

TSDB for Prometheus supports four label operators: =, !=, =~, and !~. The following code provides sample queries:

node__cpu__seconds__total{cpu="1",mode="user"}
node__cpu__seconds__total{cpu!="1",mode="user"}

node__cpu__seconds__total{cpu=~"1",mode="user"}
node__cpu__seconds__total{cpu=~"1|2|3",mode="user"}

node__cpu__seconds__total{cpu!~"1",mode="user"}
node__cpu__seconds__total{cpu!~"1|2|3",mode="user"}

For the =~ operator, TSDB for Prometheus supports only vertical bars (|) and asterisks (*) in regular expressions for value matching in PromQL queries. For the !~ operator, only vertical bars (|) are supported, and asterisks (*) are not supported. The following code provides sample queries:

node__cpu__seconds__total{mode=~"user|sys"}    #Supported
node__cpu__seconds__total{mode=~"use*"}        #Supported
node__cpu__seconds__total{mode=~"user.+"}      #Not supported

node__cpu__seconds__total{mode!~"user|sys"}    #Supported
node__cpu__seconds__total{mode!~"use*"}        #Not supported
node__cpu__seconds__total{mode!~"user.+"}      #Not supported

More features for PromQL regular expression queries are being developed by the TSDB for Prometheus team. These features will be provided in future versions.

Supported aggregation operations

TSDB for Prometheus supports a wide range of aggregation operations, such as min, max, avg, stddev, stdvar, count, topk, bottomk, quantile, and count_values. The following code provides sample queries:

min (node__cpu__seconds__total)
max (node__cpu__seconds__total)
avg (node__cpu__seconds__total)
stddev (node__cpu__seconds__total)
stdvar (node__cpu__seconds__total)
count (node__cpu__seconds__total)
topk (1,node__cpu__seconds__total)
bottomk (1,node__cpu__seconds__total)
quantile(1,node__cpu__seconds__total)
count_values("count", node__cpu__seconds__total)

Note

The characters that are supported by Prometheus are different from those supported by Time Series Database (TSDB). The following table lists the differences.

Prometheus

TSDB

metric

[a-zA-Z:][a-zA-Z0-9:]*

Contains only letters, digits, and the following special characters: -_./():,[]='#

tagKey

[a-zA-Z][a-zA-Z0-9]*. tagName that starts with > is reserved for internal use.

Contains only letters, digits, and the following special characters: -_./():,[]='#

tagValue

Supports Unicode characters.

Contains only letters, digits, and the following special characters: -_./():,[]='#

Notice
  • Due to the preceding differences, if data is written by using Prometheus, we recommend that you query data by using Prometheus. If you use the native API of TSDB to query the data, the returned tag value may contain garbled text.

  • TSDB uses a number sign (#) as an identifier when TSDB encodes and decodes characters that are not supported for the tag value. We recommend that you do not specify number signs (#) in the tag value that is written to TSDB by using Prometheus.

  • Before you use the native API of TSDB to read the data that is written by using Prometheus, make sure that the tag value written by using Prometheus contains only characters that are supported by TSDB. Before you use Prometheus to read the data that is written by using the native API of TSDB, make sure that the metric and tag key written by using the native API of TSDB contain only characters that are supported by Prometheus.