Cardinality

Cardinality is the count of distinct values in a field. In monitoring, it usually refers to the number of unique label combinations a metric has. method has low cardinality (a handful of values), while user_id or request_id has very high cardinality.

Why it matters

Time-series databases store a separate series for every unique combination of labels. Add one high-cardinality label and the series count multiplies. Memory use, storage cost, and query time climb quickly, and some systems drop data or fall over. It is one of the most common reasons a metrics bill or cluster suddenly explodes.

Example

A request counter with these labels:

http_requests_total{method, route, status}

If you have 5 methods, 40 routes, and 8 status codes, that is at most 1,600 series, which is fine. Add user_id with 200,000 users and you could reach 320 million. Use the raw URL instead of the route template (/orders/12345 rather than /orders/:id) and you create an unbounded series count.

Put high-cardinality detail in logs or traces, and keep metric labels to bounded sets.

Common mistakes

• Using IDs, email addresses, timestamps, or full query strings as labels.
• Not budgeting series per service.
• Assuming a managed vendor makes the cost irrelevant.

Related

• Metrics
• Time-series database
• Structured logging
• Sampling

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.