CONCEPT Cited by 1 source
Per-pattern tag cardinality¶
The technique of tracking the distinct-value count for a tag key within the scope of a single query pattern (rather than globally across all patterns), and collapsing the tag on that pattern alone when the per-pattern count exceeds a threshold. A load-bearing refinement over global-cardinality tracking that prevents over-collapsing of tags correlated with query structure.
What global tracking gets wrong¶
A naive cardinality reducer tracks the distinct-value count for each tag key globally — across all query patterns that carry that key. A key with thousands of distinct values across the fleet is collapsed for every pattern that uses it.
This breaks for tags that are correlated with query
pattern. Canonical PlanetScale example: source_location
(file + line number where the query was issued).
source_location is high-cardinality globally — every
distinct call site in the application contributes one
value. But per query pattern, source_location is usually
1-2 values — a given SQL pattern (say, a specific
SELECT * FROM users WHERE id = ?) is typically issued
from one or two places in the code.
Because Insights already emits one aggregate message per
query pattern, a per-pattern-correlated tag like
source_location doesn't inflate the aggregate message
count — the messages would exist anyway. Collapsing it
globally would destroy useful attribution ("which call
site is generating the slow queries?") for no message-
count savings.
The per-pattern refinement¶
Track the distinct-value count for each tag key separately
for each query pattern, with its own rolling window.
Collapse the key only for patterns where it's locally
high-cardinality. request_id gets collapsed on every
pattern (it's high-cardinality everywhere);
source_location gets collapsed only on patterns where
several call sites contribute (uncommon).
Canonical production rule (Source: sources/2026-04-21-planetscale-enhanced-tagging-in-postgres-query-insights):
"An important part of this approach is that cardinality is monitored per query pattern and not globally… Monitoring cardinality per-pattern allows high-cardinality tags that are highly correlated with query pattern to pass through without being collapsed."
Concrete PlanetScale parameters (as disclosed)¶
- Threshold: > 20 distinct values for the tag key on the pattern.
- Effect: collapse the tag to
*on the pattern for 1 hour. - Scope: per-pattern, not per-fleet.
After the 1-hour window, the tracker restarts. If cardinality is still high, collapse resumes; if cardinality dropped (e.g. a load test finished), specific values return.
Design principle¶
The scope of cardinality tracking should match the scope of emission. If the aggregation pipeline emits one message per query pattern × tag combination, the tracker should reason about cardinality inside one query pattern. Global tracking mismatches the emission scope and produces both false positives (collapse tags that don't need collapsing) and potentially false negatives (a tag that's high-cardinality for one hot pattern but low-cardinality elsewhere).
Seen in¶
- sources/2026-04-21-planetscale-enhanced-tagging-in-postgres-query-insights — Canonical disclosure. Per-pattern scoping explicitly framed as the design property that makes tag collapse useful rather than harmful.