Prometheus / Basic: collection and time-series meaning / Lesson 5

Selectors, vectors, and evaluation time

Read instant and range selectors as population-and-time contracts, including label matching, absent labels, and the distinction between query range and data range.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish instant vectors, range vectors, and scalars.
Interpret exact and regex label matching.
Explain lookback without assuming a sample at every timestamp.

Start with the expression’s result type

PromQL expressions operate on types including scalars, instant vectors, and range vectors. An instant selector returns eligible series with one selected sample at an evaluation time, while a range selector supplies samples over an interval for functions that accept it. A range query evaluates an expression repeatedly across timestamps; it is not the same thing as a range-vector selector inside that expression. This distinction explains why a function can require brackets even when a dashboard already has a wide time range. Keep the expression’s type, evaluation interval, and intended output clear before combining operators.

Read every matcher as an eligibility rule

The example selects one synthetic job and two bounded operation values. PromQL regex matchers are fully anchored under the reference semantics, so lookup|reserve expresses those complete values rather than arbitrary containing text. Exact, negative, and regex matchers can select different populations. A matcher compatible with an empty value can also match a missing label, which matters during schema migration. Avoid a broad negative selector when the intended question requires an explicit eligible outcome. Record expected labels and examples so an apparently harmless query edit does not silently include unrelated or unlabeled series.

promql Illustrative instant and range selectors

warehouse_requests_total{job="warehouse-lab",operation=~"lookup|reserve"}
warehouse_requests_total{job="warehouse-lab",operation="lookup"}[5m]

The first expression is an instant-vector selector; the second is a range-vector selector. Both are unexecuted PromQL fragments, not measured query results.

A selected sample need not share evaluation time

An instant selector can use a recent eligible sample rather than requiring a sample with exactly the evaluation timestamp. Lookback and staleness rules determine whether the series remains selectable; explicit timestamps and configuration can affect behavior. A flat graph may therefore reuse a recent value instead of proving fresh collection at every point. Show collection freshness separately when it matters. The local fixture models only a simplified age cutoff with no stale markers, resets, or interpolation. It demonstrates the question to ask, not a replacement implementation of Prometheus selection.

python Offline simplified lookback model

samples = [(0, 4), (10, 7)]
def latest_within(evaluation, max_age):
    eligible = [(t, value) for t, value in samples if t <= evaluation and evaluation - t <= max_age]
    return max(eligible)[1] if eligible else None
print(latest_within(12, 5))
print(latest_within(20, 5))

Expected output

7
None

The fixed five-second age is a model input, not a recommended or reproduced Prometheus default. Real stale-marker behavior is omitted.

Align range boundaries with the question

A window such as five minutes determines which observations a range function receives, while the dashboard step determines how often the expression is evaluated. A wider step can hide a short pattern even if the underlying data remains stored. Boundary inclusion and sparse samples affect functions, so consult the pinned documentation instead of assuming ordinary spreadsheet semantics. Keep timezone, evaluation timestamp, and late-data assumptions visible in comparisons. Two panels using the same metric name can disagree because one computes a recent rate and the other displays a cumulative value.

Test populations before complex expressions

Begin diagnosis with a narrow selector and inspect its intended labels and time scope through authorized evidence, then add functions and aggregation one step at a time. An empty result is not automatically zero, and a broad selector can accidentally include another environment. Keep credentials and private identifiers out of query links. This lesson runs only a synthetic sample-list model, with no query engine, stored series, or dashboard. Syntax and engine behavior remain reference-based teaching claims rather than locally executed PromQL results.

Common errors and fixes

A dashboard time range replaces the range selector

Why it happens: Repeated evaluation was confused with function input type.
How to fix it: Distinguish range queries from range vectors.
Prevent it next time: Document expression types beside examples.

A negative matcher includes unlabeled data

Why it happens: Missing labels can satisfy the matcher’s empty-value semantics.
How to fix it: Use explicit eligibility and test missing-label cases.
Prevent it next time: Review selectors during label migrations.

A flat line is reported as fresh collection

Why it happens: Recent sample selection was confused with new observations.
How to fix it: Inspect sample age and collection health separately.
Prevent it next time: Show freshness when decisions depend on it.

Check your understanding

1. Why does a rate expression still need [5m] when a dashboard shows a day?

Show worked solution

The day is the range of evaluation timestamps. The bracketed range supplies each rate evaluation with its own recent samples. Those are different time contracts. Choose the function window according to the measurement question and sample availability, not merely the width of the screen.

2. A query using outcome!="error" rises after a rollout that omitted outcome. What should be checked?