PromQL Query¶

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 the query language of Prometheus, used to query and manipulate time series data from Prometheus data sources. It provides rich functions and operators, supports data aggregation, filtering, calculation, and comparison, helping users quickly extract and analyze data.

Start Querying¶

Click "Add PromQL Query".
Select a query method.
Start querying.

Query Method¶

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

Range Query¶

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

Example:

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

Indicates returning the total number of requests at various time points in the past 5 minutes.

Instant Query¶

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

Example:

http_requests_total{job="api-server"}

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

Time Explanation

For instant queries (Instant Query), which are based on instant vector logic, the query uses only a single end time (endtime) timestamp. To accommodate various usage scenarios of Guance, the query engine intelligently processes the received data:

If identified as an instant query, the engine uses the end time of the time range (timerange) as the final query timestamp.
When determining the time window (step) for the PromQL query, the following priority is applied:
- 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 (interval) parameter; if so, use interval as the step.
- If there is no interval, use the time range (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 (Range Query) 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 regional concurrent limiter is triggered in a certain region, 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.

Application Scenarios¶

In the PromQL query interface definition, there are three 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`. Interacts with the `interval` and `timerange` parameters. If the value is `true`, the `timerange` is readjusted based on the `interval` time interval, generally shifting it forward.