PromQL Basics and Data Model
What you'll learn: How to query Prometheus time-series data using PromQL and understand the underlying data structure.
The Data Model Foundation
Prometheus stores every metric as a time-series: a stream of timestamped values identified by a metric name and key-value pairs called labels. Think of it like a spreadsheet where each row is uniquely identified by its column headers (labels), and the data itself is values at specific timestamps.
For example:
http_requests_total{method="GET", endpoint="/api", status="200"} → [(timestamp1, 150), (timestamp2, 175), ...]
The metric name is http_requests_total, and the labels {method="GET", endpoint="/api", status="200"} create a unique series.
Instant vs Range Vectors
PromQL (Prometheus Query Language) returns data in two forms:
-
Instant vector: A set of time-series containing a single sample per series at one moment in time. Query:
http_requests_totalreturns the most recent value for each unique label combination. -
Range vector: Time-series data over a specified time window. Query:
http_requests_total[5m]returns all samples from the last 5 minutes for each series.
You need range vectors to calculate rates or averages over time, while instant vectors are what you graph or alert on.
Selecting and Filtering
Use curly braces to filter by labels:
http_requests_total{status="500"} # Only 500 errors
http_requests_total{method=~"GET|POST"} # Regex matching
Key Takeaway: PromQL queries Prometheus' label-based time-series data model, returning either instant vectors (single points) or range vectors (time windows), enabling powerful filtering and aggregation across your infrastructure metrics.