Define and enforce a bounded-cardinality metrics contract

[lan17]

Priority

P1 — High — resolve before broad production adoption or large-scale use.

Problem

Prometheus labels include caller-supplied useCase, keyType, and arbitrary Error.name. Dynamically constructing definitions grows both the internal use-case set and metric series. Accidental per-tenant/per-ID values can grow process and backend cardinality indefinitely.

Evidence:

• Caller-controlled label types
• Prometheus label sets
• Arbitrary error-name mapping
• Persistent use-case registration set

Open decisions

Approve an error taxonomy/hook and whether construction-time validation or bounded warnings should detect likely dynamic labels.

Acceptance criteria

• Document that definitions, useCase, and keyType must be static and bounded.
• Normalize arbitrary error names into an approved bounded taxonomy with an unknown bucket or explicit hook.
• Never add IDs, args, raw messages, or Redis keys as labels.
• Add adversarial tests for custom Error.name and dynamic inputs.
• Verify compatibility for custom metrics adapters.