Observability
Prometheus High Cardinality Guide
Find and reduce high-cardinality Prometheus metrics caused by unbounded labels, identifiers and accidental dimensions. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Measure series growth | Identify when active series and memory use changed. |
| Rank label values | Look for user IDs, request IDs, raw URLs and error messages in labels. |
| Fix instrumentation | Replace unbounded labels with routes, classes or controlled buckets. |
| Verify after rollout | Confirm new series growth slows while useful aggregation remains. |
Starter snippet
series growth -> metric family -> label cardinality -> source instrumentation -> bounded replacementReview checks
- Keep IDs in logs or traces, not metric labels.
- Normalize URL paths to route templates.
- Review histogram bucket counts.
- Set ownership for custom metrics.
Common mistakes
- Deleting historical data before fixing the producer.
- Using exception messages as labels.
- Adding a tenant label without estimating tenant count.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Structured Logging Guide, Error Budget Slo Guide, Uptime Monitoring Checklist.