Prometheus Querying Basics

Introduction to PromQL

• Prometheus uses a functional query language called PromQL to select and aggregate time series data in real-time.
• Queries can be either:
  • Instant queries: Evaluated at a single point in time.
  • Range queries: Evaluated over a period of time at equally-spaced intervals.
• Prometheus UI tabs:
  • Table tab: For instant queries.
  • Graph tab: For range queries.
• Other programs can access PromQL results via the HTTP API.

Expression Language Data Types

• Instant Vector: Single sample per time series, sharing the same timestamp.
• Range Vector: Multiple data points over time per time series.
• Scalar: Numeric floating point value.
• String: Simple string value (currently unused).
• Instant queries support all data types; range queries support scalar and instant vector types.

Native Histograms (Experimental)

• Enable via feature flag.
• Can contain both float and histogram samples.
• Compatible with binary and aggregation operations.

Literals

String Literals

• Enclosed in single, double quotes, or backticks.
• Follows Go’s escaping rules.
• Backticks do not parse escape characters.

Float Literals and Time Durations

• Can be written in integer or floating-point format.
• Supports underscores for readability.
• Time durations can use units like ms, s, m, h, d, w, y.

Time Series Selectors

Instant Vector Selectors

• Select a set of time series with a single sample value at a given timestamp.
• Use metric name and label matchers to filter.

Range Vector Selectors

• Select a range of samples back from the current instant.
• Specify range in square brackets, e.g., [5m].

Offset Modifier

• Changes time offset for vectors.
• Must follow the selector immediately.

@ Modifier

• Alters evaluation time using a Unix timestamp.
• Functions with both instant and range vectors.

Subquery

• Runs an instant query for a specified range and resolution.

Operators

• Prometheus supports various binary and aggregation operators.

Functions

• Prometheus provides several functions for data manipulation.

Comments

• Start with # for line comments.

Regular Expressions

• Use RE2 syntax and are fully anchored.

Gotchas

Staleness

• Prometheus assigns values independently of the present time series data.
• Series marked stale when no longer exported or target removed.

Avoiding Slow Queries

• Large data queries can time out or overload servers.
• Use tabular view initially to avoid large data sets.
• Pre-record expressions with recording rules for efficiency.

Contribution

• Documentation is open-source, contributions welcomed via issues or pull requests.