PromQL Query¶

Applying PromQL queries in charts can help you extract and analyze time series data from the Prometheus data source, displaying the results intuitively in the chart.

Simple Definition

PromQL is the query language of Prometheus, used to query and manipulate time series data from the Prometheus data source. It provides a rich set of functions and operators that support aggregation, filtering, calculation, and comparison of data, helping users quickly extract and analyze data.

Start Querying¶

Click on "Add PromQL Query";
Select query method;
Begin querying.

Query Method¶

For more details, refer to Comparison of DQL with other query languages; or go directly to PromQL.

Range Query (Range Query)¶

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

Example:

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

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

Instant Query (Instant Query)¶

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

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 one timestamp for the end time (endtime). To adapt to various use cases of Guance, the query engine will intelligently process 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) for PromQL queries, the following priority order applies:
- If a time window is specified in PromQL (e.g., [5m]), then that window value is used as step.
- If no window is specified, check if there is a time 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: The default value for step in range queries (Range Query) is max(interval, max-point-window), meaning it takes the larger value between interval and max-point-window.

Query Examples¶

For example, if you want to monitor whether a concurrency limiter has been triggered in a particular region to promptly identify potential performance issues or resource bottlenecks.

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

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

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

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

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

Statement Format

Dynamic replacement of label values: #{region} is a placeholder that needs to be replaced by a specific value during actual querying. Ensure that placeholders are correctly replaced during querying.

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`	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`, then the `timerange` range is readjusted according to the `interval` time interval, generally shifting forward.