logo

PromQL Cheatsheet

Prometheus, a powerful open-source monitoring and alerting toolkit, utilizes the Prometheus Query Language (PromQL) to explore and visualize time-series data. This cheat sheet provides a comprehensive overview of PromQL's essential components, from selectors and operators to functions and common query patterns, enabling users to effectively query their Prometheus metrics.

Data Types

PromQL expressions can evaluate to one of four data types:

  • Instant vector: A set of time series containing a single sample for each time series, all sharing the same timestamp.
  • Range vector: A set of time series containing a range of data points over time for each time series.
  • Scalar: A simple numeric floating-point value.
  • String: A simple string value; currently unused in PromQL.

Selectors and Matchers

Selectors are used to filter and select time series data based on metric names and labels.

  • Instant Vector Selectors: Select the most recent sample for a given metric name.
    • metric_name
    • metric_name{label="value"}
  • Range Vector Selectors: Select a range of samples for a given time duration.
    • metric_name[5m]
  • Label Matching Operators: Refine selections based on label values.
    • =: Select labels that are exactly equal to the provided string.
    • !=: Select labels that are not equal to the provided string.
    • =~: Select labels that regex-match the provided string.
    • !~: Select labels that do not regex-match the provided string.
  • Offset Modifier: Select data from a point in the past.
    • metric_name offset 5m

Operators

PromQL supports a variety of operators for performing arithmetic, comparisons, and logical operations on time series data.

Arithmetic Operators

These operators allow for basic mathematical calculations.

  • + (addition)
  • - (subtraction)
  • * (multiplication)
  • / (division)
  • % (modulo)
  • ^ (power/exponentiation)

Comparison Operators

These operators are used for comparing values.

  • == (equal)
  • != (not-equal)
  • > (greater-than)
  • < (less-than)
  • >= (greater-or-equal)
  • <= (less-or-equal)

Logical/Set Operators

These operators perform logical operations on instant vectors.

  • and (intersection)
  • or (union)
  • unless (difference)

Vector Matching

When performing operations between two instant vectors, PromQL attempts to find matching elements based on their labels.

  • One-to-One: Matches elements from each vector that have the exact same set of labels.
  • Many-to-One and One-to-Many: Uses the on() and ignoring() modifiers to specify which labels to consider for matching, and group_left() or group_right() to determine which labels are carried over to the result.
    • on(label_list): Specifies the labels to match on.
    • ignoring(label_list): Specifies the labels to ignore during matching.
    • group_left(label_list): The result will contain all labels from the left-side vector and the labels specified in the list from the right-side vector.
    • group_right(label_list): The result will contain all labels from the right-side vector and the labels specified in the list from the left-side vector.

Aggregation Operators

Aggregation operators are used to combine the values of multiple time series into a single value.

  • sum(): Calculates the sum over dimensions.
  • min(): Selects the minimum over dimensions.
  • max(): Selects the maximum over dimensions.
  • avg(): Calculates the average over dimensions.
  • group(): All values in the resulting vector are 1.
  • stddev(): Calculates the population standard deviation over dimensions.
  • stdvar(): Calculates the population standard variance over dimensions.
  • count(): Counts the number of elements in the vector.
  • count_values(): Counts the number of elements with the same value.
  • bottomk(k, ...): Selects the smallest k elements by sample value.
  • topk(k, ...): Selects the largest k elements by sample value.
  • quantile(φ, ...): Calculates the φ-quantile (0 ≤ φ ≤ 1) over dimensions.

These operators can be used with the by() and without() clauses to group the aggregation by specific labels.

  • by (label1, label2, ...): Aggregates over the provided labels.
  • without (label1, label2, ...): Aggregates over all labels except the ones provided.

Functions

PromQL offers a rich set of functions to perform various calculations on time series data.

Rate and Increase Functions

These functions are particularly useful for working with counter metrics.

  • rate(v range-vector): Calculates the per-second average rate of increase of a time series over a given time range. This is the most common function for calculating rates and provides a smoothed output.
  • irate(v range-vector): Calculates the per-second "instant" rate of increase based on the last two data points in the time range. This is useful for visualizing volatile, fast-moving counters.
  • increase(v range-vector): Calculates the total increase in a counter over the specified time range.
  • resets(v range-vector): Returns the number of counter resets within the provided time range.

Histogram Functions

These functions are used to analyze histogram metrics.

  • histogram_quantile(φ, b instant-vector): Calculates the φ-quantile (e.g., 0.95 for the 95th percentile) from the buckets of a histogram.
  • histogram_count(): Calculates the rate of HTTP requests.
  • histogram_sum(): Returns the sum of all observed values in a histogram metric.
  • histogram_avg(): Calculates the average HTTP request duration.

Other Notable Functions

  • abs(v instant-vector): Returns the absolute value of all samples.
  • ceil(v instant-vector): Rounds the sample values up to the nearest integer.
  • floor(v instant-vector): Rounds the sample values down to the nearest integer.
  • round(v instant-vector, to_nearest=1): Rounds the sample values to the nearest integer or the given to_nearest value.
  • sort(v instant-vector): Sorts the series by sample value in ascending order.
  • sort_desc(v instant-vector): Sorts the series by sample value in descending order.
  • label_replace(v instant-vector, dst_label, replacement, src_label, regex): Changes the value of a label.
  • label_join(v instant-vector, dst_label, separator, src_label_1, src_label_2, ...): Joins the values of multiple labels into a single label.
  • time(): Returns the time in seconds since January 1, 1970 UTC.
  • vector(s scalar): Returns a scalar as a vector with no labels.

Common Queries

Here are some examples of common PromQL queries for monitoring service level indicators (SLIs).

  • Request Rate (per-second rate over the last 5 minutes): 
    rate(http_requests_total[5m])
  • Error Rate Percentage (5xx errors as a percentage of total requests over the last 5 minutes): 
    sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) * 100
  • 95th Percentile Latency (over the last 10 minutes): 
    histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[10m])) by (le))
  • Service Uptime Percentage: 
    avg(up{job="my_service"}) * 100
  • Predicting Future Values (linear prediction of disk usage in 4 hours): 
    predict_linear(node_filesystem_free_bytes{mountpoint="/"}[1h], 4 * 3600)
logo
PRIVACY POLICYABOUT中文