Skip to content

PromQL Query

Applying PromQL queries in charts can help you extract and analyze time series data from Prometheus data sources, and visually 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, supporting data aggregation, filtering, calculation, and comparison, helping users quickly extract and analyze data.

Start Querying

  1. Click "Add PromQL Query".
  2. Select the Query Method.
  3. Start querying.

Query Method

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

Range Query

Query monitoring data over a 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 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 the instant vector logic, and only uses an end time (endtime) timestamp when querying. To accommodate various use cases of TrueWatch, the query engine intelligently processes the received data:

  • If recognized 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 PromQL queries, the following priority is used:

    • 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 for range queries (Range Query) is max(interval, max-point-window), which is 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 identify potential performance issues or resource bottlenecks.

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

Enter the above query statement, which 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 the 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.

Use Cases

In the PromQL query interface definition, there are 3 parameters used to control the data processing performance of the query, namely interval, timerange, and align_time, with the following meanings:

Field
 Description
timerange The time range for querying data
interval The time interval between data points
align_time Values: true, false.
Linked with interval and timerange parameters. If the value is true, the timerange range is readjusted based on the interval time interval, generally shifting forward.