PromQL Query¶

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

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 to help users quickly extract and analyze data.

Start Querying¶

Click "Add PromQL Query";
Select Query Method;
Begin querying.

Query Method¶

For more details, please refer to Comparison Between DQL and Other Query Languages, or go directly to PromQL.

Range Query¶

Queries monitoring data within a certain time range and returns a range vector, i.e., multiple sample values of each time series within the specified time period. The syntax needs to append a time range.

Example:

[5m]）：http_requests_total{job="api-server"}[5m]

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

Instant Query¶

Queries monitoring data at a specific time point and returns an instant vector, i.e., the latest sample value of each time series at that moment.

Example:

http_requests_total{job="api-server"}

This means returning the current total number of requests for all label conditions that are satisfied.

Time Description

For instant queries (Instant Query), it is based on the logic of the instant vector and uses only one end-time timestamp during querying. To adapt to various use cases of Guance, the query engine will perform intelligent processing based on the received data:

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

Additional note: For range queries (Range Query), the default step value is max(interval, max-point-window), which takes the larger of interval and max-point-window.

Query Example¶

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

guancedb:guance_concurrent_limiter_current{region="#{region}"} > 0

Enter the above query statement, meaning: filter out all data points where the value of the guance_concurrent_limiter_current metric is greater than 0, and the region tag value of these data points is #{region}.

Assume the value of region is us-west-1; then the actual query statement becomes:

guancedb:guance_concurrent_limiter_current{region="us-west-1"} > 0

This query returns time series data where the region is us-west-1 and the guance_concurrent_limiter_current metric's value is greater than 0.

Statement Format

Dynamic replacement of tag values: #{region} is a placeholder that needs to be replaced with a specific value during the actual query. Ensure that the placeholder is correctly replaced before executing the query.

Use Cases¶

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

Field	Description
`timerange`	Time range of queried data
`interval`	Time interval between data points
`align_time`	Value: `true`, `false`. Works together with `interval` and `timerange` parameters. If the value is `true`, the `timerange` range will be adjusted according to the `interval` time interval, generally logically shifted backward.