PromQL Queries¶

Applying PromQL queries in charts helps you extract and analyze time series data from Prometheus data sources and intuitively display the results in charts.

Simple Definition

PromQL is Prometheus's query language, used to query and manipulate time series data from Prometheus data sources. It provides rich functions and operators, supporting data aggregation, filtering, calculation, and comparison, helping users quickly extract and analyze data.

Start Querying¶

Click "Add PromQL Query".
Select the Query Method.
Start querying.

Query Method¶

For more details, refer to Comparison of DQL with Other Query Languages; or go directly to PromQL.

Range Query¶

Queries monitoring data over a period of time, returning a Range Vector, i.e., multiple sample values for each time series within the specified time range. The syntax requires appending a time range.

For example:

[5m]): http_requests_total{job="api-server"}[5m]

Indicates returning the total number of requests at each time point in the past 5 minutes.

Instant Query¶

Queries monitoring data at a specific point in time, returning an Instant Vector, i.e., the latest sample value of each time series at that moment.

For example:

http_requests_total{job="api-server"}

Indicates returning the total number of all requests meeting the label conditions at the current moment.

Time Explanation

For Instant Queries, which are based on instant vector logic, the query uses only a single endtime timestamp. To accommodate various use cases in Guance, the query engine intelligently processes the received data:

If identified as an instant query, the engine uses the end time of the timerange as the final query timestamp.
When determining the time window (step) for the PromQL query, the following priority is followed:
- If a time window is specified in the PromQL (e.g., [5m]), that window value is used as the step.
- If no window is specified, check if there is an interval parameter; if so, use interval as the step.
- If there is no interval, use the timerange as the step.
- If none of the above exist, the engine defaults to using 5 minutes (5m) as the step.

Additional note: The default step for Range Queries is max(interval, max-point-window), i.e., the larger value between interval and max-point-window.

Query Example¶

For example, you want to monitor whether a concurrent limiter in a certain region is triggered, to promptly detect potential performance issues or resource bottlenecks.

dataplatform:system_concurrent_limiter_current{region="#{region}"} > 0

Entering the above query statement means: filter out all data points where the value of the system_concurrent_limiter_current metric is greater than 0, and the region label value for these data points is #{region}.

Assuming the value of region is us-west-1, the actual query statement becomes:

dataplatform:system_concurrent_limiter_current{region="us-west-1"} > 0

This query returns all time series data where region is us-west-1 and the value of the system_concurrent_limiter_current metric is greater than 0.

Statement Format

Dynamic replacement of label values: #{region} is a placeholder that needs to be replaced with a specific value in the actual query.

Filter Conditions¶

In PromQL mode, filter conditions only support label string matching. The system automatically converts eligible filters into PromQL label matchers.

Supported Conversion Rules¶

Filter Condition	Conversion Result	Description
Multiple AND conditions	Comma-separated	e.g., `a="1" AND b="2"` converts to `a="1", b="2"`
Multiple OR values for the same label	Regex match	e.g., `a="1" OR a="2"` converts to `a=~"1\\|2"`
Equality match	`=`, `!=`	Directly converts to PromQL equality match
Regex match	`=~`, `!~`	Directly converts to PromQL regex match

Unsupported Filters¶

The following filter conditions are currently not supported:

OR between different labels
Numeric comparisons (>, <, >=, <=)
Function-based filters

Use Cases¶

In the PromQL query interface definition, there are 3 parameters used to control the data processing behavior of the query: interval, timerange, and align_time. Their meanings are as follows:

Field	Description
`timerange`	The time range for querying data
`interval`	The time interval between data points
`align_time`	Values: `true`, `false`. Links with the `interval` and `timerange` parameters. If the value is `true`, the `timerange` is readjusted according to the `interval` time interval, generally with logic to shift forward.