Vector Matching
What you'll learn: How to combine metrics from different time series using one-to-one and many-to-one matching semantics in PromQL.
What Is Vector Matching?
When you perform binary operations (like addition, subtraction, or comparison) between two instant vectors in PromQL, Prometheus needs to figure out which time series from the left side should be paired with which time series from the right side. This pairing process is called vector matching.
Think of it like a dating app for metrics: you have two groups of time series, and Prometheus matches them based on their labels to perform calculations.
One-to-One Matching
By default, Prometheus uses one-to-one matching. Two series match if they have exactly the same label sets (after ignoring the metric name). For example:
instance_cpu_usage{instance="server1"} / instance_cpu_limit{instance="server1"}
Here, both sides must have identical instance labels to match and divide.
Many-to-One Matching
Sometimes you need to match multiple series on one side with one series on the other. Use group_left or group_right modifiers for this:
instance_cpu_usage / on(cluster) group_left instance_cpu_capacity
This divides each instance's CPU usage by a single cluster-wide capacity metric. The on(cluster) specifies the matching label, and group_left indicates the left side (usage) has more cardinality.
Why It Matters
Vector matching lets you calculate ratios, differences, and relationships between related metrics—like comparing actual vs. capacity, or request counts vs. error counts—even when they come from different metric families.
Key Takeaway: Vector matching determines how Prometheus pairs time series during binary operations, using one-to-one matching by default or many-to-one/one-to-many with group_left/group_right when cardinalities differ.