Query with PromQL

This section tells you about using PromQL with StatsHouse:

• What is PromQL?
• How to switch to a PromQL query editor
• What is specific about PromQL in StatsHouse?
  • The query result is an aggregate
  • __what__ for choosing the aggregate components
  • Histograms are t-digests
  • No data grouping by default
• PromQL extensions in StatsHouse
  • __what__ and __by__
  • Applying dashboard variables
  • Range vectors and instant vectors
  • prefix_sum
  • default

What is PromQL?

PromQL is the Prometheus Query Language that lets the user select time series data.

Why have we decided to support querying with PromQL in StatsHouse? We wanted to broaden the range of things the users could do with data in StatsHouse. PromQL provides users with the necessary operations, it is widely used and well-documented.

Find the original PromQL documentation.

How to switch to a PromQL query editor

To switch to the PromQL query editor in StatsHouse, press the < > button near the Metric name field. Find more about the PromQL query editor in the UI.

What is specific about PromQL in StatsHouse?

If you have been using PromQL before, you may be confused with some PromQL implementation details in StatsHouse. Let's make them clear.

• The query result is an aggregate—not an exact metric value per moment.
• You can choose the aggregate components using the __what__ selector.
• StatsHouse histograms are t-digests.
• StatsHouse does not group data by default.

The query result is an aggregate

Prometheus stores timestamp—value pairs. Instead, StatsHouse stores aggregated data per time intervals, or aggregates.

So, the query result in StatsHouse is an aggregate, and it depends on

• the minimal available aggregation interval (i.e., on the "age" of the data),
• the requested aggregation interval,
• the metric resolution.

An aggregate contains the count, sum, min, max statistics, and, optionally, the String top tag (tag_s) and percentiles (if enabled). They are aggregate components:

timestamp	metric	tag_1	tag_2	tag_s	count	sum	min	max	percentiles
13:45:05	toy_metric	...	...	...	...	...	...	...	...

Read more about aggregation in StatsHouse.

what for choosing the aggregate components

• In Prometheus, you can query the exact values. In Prometheus timestamp—value pairs, the value is the floating-point number associated with a moment in time.
• In StatsHouse, you can query the aggregates associated with time intervals.

To query the aggregate components, use the __what__ selector. The possible values are:

"avg"
"count"
"countsec"
"max"
"min"
"sum"
"sumsec"
"stddev"
"stdvar"
"p25"
"p50"
"p75"
"p90"
"p95"
"p99"
"p999"
"cardinality"
"cardinalitysec"
"unique"
"uniquesec"

They are the descriptive statistics you see in the StatsHouse UI. The "sec" postfix means that the value is normalized—divided by the aggregation interval in seconds.

For example, this selector returns the counter for the api_methods metric associated with the aggregation interval:

api_methods{__what__="count"}

If the __what__ selector is not specified, StatsHouse tries to guess based on the PromQL functions you use in your query:

PromQL functions	StatsHouse interpretation
"increase" "irate" "rate" "resets"	__what__="count"
"delta" "deriv" "holt_winters" "idelta" "predict_linear"	__what__="avg"

For example, this query returns the api_methods metric's counter rate for five minutes:

rate(api_methods[5m])

If StatsHouse fails to guess, it returns the counter for the counter metrics and the average (the sum divided by the counter) for the value metrics.

Histograms are t-digests

Prometheus provides you with "traditional" and "native" histograms. StatsHouse will soon support the "traditional" ones. More details will be provided when the scraping feature is implemented. Now it is recommended to use StatsHouse histograms.

StatsHouse stores histograms in the t-digest structure but does not provide them by default—you should enable writing percentiles.

To get access to percentiles (if enabled), specify the necessary one in the __what__ selector:

"p25"
"p50"
"p75"
"p90"
"p95"
"p99"
"p999"

For example, this expression returns the 99th percentile:

api_methods{__what__="p99"}

No data grouping by default

If you query data in Prometheus by a metric name, it returns all the data rows for this metric—all label combinations.

On the contrary, StatsHouse returns the result of aggregation. For example, in StatsHouse, the "api_methods" query returns the single row. To group data by tags, specify the necessary ones using the __by__ PromQL operator.

PromQL extensions in StatsHouse

Find PromQL extensions implemented in StatsHouse.

what and by

The __what__ and __by__ selectors help to express any standard query in StatsHouse.

Applying dashboard variables

To bind the tag to the previously created variable in your PromQL query, use the following syntax:

tag_name:$variable_name

The resulting query may look like this:

topk(5,api_methods{@what="countsec",0:$env})

Find more about setting up variables for PromQL-based graphs and dashboards.

Range vectors and instant vectors

Functions for the range vectors receive instant vectors too. But the converse is false.

Prefix sum

The prefix_sum function allows you to calculate a prefix sum. For example, for a 1, 2, 3, 4, 5, 6 sequence, it returns the following: 1, 3, 6, 10, 15, 21.

default

It is a binary operator. It has an array on the left, and an array or a literal on the right.

• If it has the literal on the right, the NaN values on the left are replaced with the literal.
• If it has the array on the right, the logic of mapping the arrays is the same as for the or operator. The NaN values on the left are replaced with the corresponding values on the right.