Prometheus Data Query Basics and Practical Usage Guide

Prometheus defines each time series uniquely by a metric name and a set of labels, allowing users to filter, aggregate, and compute new series using its query language PromQL.

PromQL enables real‑time selection and summarisation of time‑series data, with results displayed as graphs, tables, or via the HTTP API.

Expressions in PromQL evaluate to one of four types: instant vectors, range vectors, scalars, or strings.

Basic PromQL usage

Instant vector selectors retrieve the latest sample for each series at a given timestamp. For example, http_requests_total or http_requests_total{} returns all series with that metric name.

Label matchers inside curly braces filter series, e.g., http_requests_total{code="200",handler="alerts"} . Supported matchers include exact ( label=value ), inequality ( label!=value ), regex ( label=~regex ) and regex negation ( label!~regex ).

Range vectors select a time window for each series, written as metric_name[5m] to fetch samples from the last five minutes.

Offsets shift the evaluation time, e.g., http_requests_total{} offset 5m queries data from five minutes ago, while http_requests_total[1d] offset 1d fetches a day‑old one‑day window.

Storage design overview

Prometheus stores data in time‑ordered blocks; each block contains series for a specific time range, enabling efficient range queries and easier deletion of expired data.

An inverted index on label values allows fast retrieval of series matching label selectors.

Common functions and operators

rate() computes per‑second increase for counters over a range vector, handling counter resets. irate() uses only the two most recent points, suitable for rapidly changing counters.

predict_linear() applies simple linear regression to forecast future values, useful for proactive alerts on gauges.

Aggregation operators such as sum , min , max , avg , count , topk can be combined with by or without to control label retention.

Usage recommendations

Apply sum before rate to avoid artificial spikes caused by counter resets.

Prefer rate for most cases; use irate only when high‑resolution changes are needed.

When querying large datasets, limit the time range and step size to prevent overload; consider using Recording Rules to pre‑compute frequent queries ( Recording Rules ).

Choose a query range at least four times the scrape interval; for a 10‑second scrape, a 30‑second range ensures two samples for rate or irate , with a typical rounded range of 1 minute.

When using /api/v1/query_range , set the step parameter appropriately: smaller steps yield more points but increase load, while larger steps may miss short‑lived spikes.