In Micrometer, a meter is identified by its name plus a set of tags (key/value dimensions). What makes a tag safe or unsafe to add, and what exactly breaks — in the application process, at export/scrape time, and in the metrics backend — when tag cardinality is unbounded?

## What a tag actually creates Micrometer identifies a meter by its `Meter.Id`: a name plus an unordered set of tags (string key/value pairs), plus meter type and base unit. Two registrations with the same name but different tag values are **two different meters**, each with its own state, exported as its own time series. (Aside: the name you register is not necessarily the name you query — each registry rewrites it into the backend's idiom on export; that translation is a separate topic from cost.) So the question "is this tag safe?" is really "how many distinct values will this key ever take, over the lifetime of the process?" ## The safe/unsafe test A tag is safe when its value set is **bounded, small, and chosen by your code**. HTTP method, status or status class, success/failure outcome, cache name, queue name, matched route template, a fixed enum of error kinds — all finite and enumerable at design time. A tag is unsafe when its values are **produced by data or by callers**: user id, tenant id in a large multi-tenant system, order id, the raw request path, a full exception message (which often embeds ids), session id, correlation id, a timestamp, a free-text search term. The practical heuristic: *if an external caller can influence the value, treat it as unbounded until proven otherwise.* And remember cardinality is **multiplicative across tags on the same meter**, not additive. Four tags with 10, 20, 5 and 8 values is 8,000 series — before anyone adds a fifth. ## Stage 1 — the application process The registry holds a concurrent map from `Meter.Id` to the meter instance. Each new tag combination allocates a meter object and its accumulators. For a `Timer` or `DistributionSummary` configured with percentile histograms, that is an array of bucket counters — hundreds of bytes to kilobytes each. Crucially, **meters are not evicted automatically**. There is no TTL; a meter created once for a one-off user id stays registered for the life of the process (you can call the registry's remove operation, but nothing does it for you). An unbounded tag is therefore a memory leak that looks like ordinary heap growth, and it also lengthens every export cycle because the registry iterates all meters. ## Stage 2 — export With a pull-based registry, every scrape serialises the entire meter set into the response body. Ten thousand series is unremarkable; a million makes the endpoint slow and the payload large. When the scrape exceeds the collector's timeout you do not lose the noisy series — **you lose every series from that instance**, so the blast radius of one bad tag is total blindness for that process, exactly when you need it. Push-based registries fail differently: larger batches, more egress, and dropped or throttled publishes at the vendor. ## Stage 3 — the backend Time-series databases size memory largely by **active series count**, and each series carries an index entry plus its own chunk stream. One careless service can push a shared cluster into memory pressure, ingestion rejection or compaction backlog — degrading observability for teams that did nothing wrong. This is why cardinality is a platform-level control, not a per-team preference. ## Stage 4 — queries An aggregation must read every series matching the selector, even when the result is a single line. A dashboard panel over a million-series metric is slow, and alert rule evaluation over it eats evaluation budget, so alerts start lagging or timing out. ## The route-template fix The canonical offender is tagging with the raw request path. `/orders/8412` and `/orders/8413` are different values, so the series count grows with your data. Tag the **route template your router matched** (`/orders/{id}`) so the value set equals the number of endpoints you wrote. The subtle half: requests that match *no* route. Unmatched paths are attacker- or scanner-controlled, so a vulnerability scanner probing thousands of paths mints a series per probe — a cheap denial-of-service against your own monitoring. Fold every unmatched request into a **single constant value** (a `NOT_FOUND`-style placeholder), and do the same for redirects. Any per-tenant or per-entity dimension deserves the same question: is the set finite and owned by us? ## Guard rails Discipline does not survive contact with a fleet, so enforce it centrally with `MeterFilter` on the registry configuration: - `MeterFilter.maximumAllowableTags(prefix, tagKey, maxValues, onMaxReached)` — tracks distinct values for a tag key and applies the supplied filter (commonly `MeterFilter.deny()`) once the cap is exceeded, so the damage stops at a known ceiling. - `MeterFilter.replaceTagValues(tagKey, mapping, exceptions...)` — normalises values, e.g. mapping anything unrecognised to a single `other` bucket. Use this when you want an overflow bucket rather than outright denial; `maximumAllowableTags` alone does not create one. - `MeterFilter.maximumAllowableMetrics(max)` — a global ceiling on meters in the registry. - `MeterFilter.denyNameStartsWith(prefix)` — drop whole families you never query. Treat these as production controls with the same seriousness as a connection-pool limit. ## When you genuinely need per-entity detail If the question is "which request was slow" rather than "what fraction is slow", metrics are the wrong store. Logs and traces are built for high-cardinality identifiers, and exemplars can attach a trace id to a metric bucket so you can jump from the aggregate to one concrete request — without minting a series per entity.