PromQL Query¶

Applying PromQL queries in charts can help 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 a rich set of 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 directly visit PromQL.

Range Query¶

Query monitoring data within a specific time range, returning a range vector (Range Vector), which is multiple sample values of each time series within the specified time period. The syntax requires appending a time range.

For example:

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

This returns the total number of requests at each time point in the past 5 minutes.

Instant Query¶

Query monitoring data at a specific time point, returning an instant vector (Instant Vector), which is the latest sample value of each time series at that moment.

For example:

http_requests_total{job="api-server"}

This returns the total number of requests that meet the label conditions at the current moment.

Time Explanation

For instant queries (Instant Query), it is based on instant vector logic, and only uses an end time (endtime) timestamp when querying. To adapt to various use cases of TrueWatch, 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 a PromQL query, the following priority is applied:
- If a time window is specified in PromQL (e.g., [5m]), that window value is used as step.
- If no window is specified, check if there is an interval (interval) parameter, and if so, use interval as step.
- If there is no interval, use the time range (timerange) as step.
- If none of the above exists, the engine defaults to using 5 minutes (5m) as step.

Additional note: The default step value 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 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 of 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 during the actual query. Ensure the placeholder is correctly replaced during the query.

Use Cases¶

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, with the following meanings:

Field	Description
`timerange`	Time range for querying data
`interval`	Time interval between data points
`align_time`	Values: `true`, `false`. Linked with `interval` and `timerange` parameters. If the value is `true`, the `timerange` is adjusted according to the `interval` time interval, generally shifting forward.