The Metric Naming Convention That Survives

Most metric naming is haphazard. The convention that scales across teams and produces queryable names.

The pattern

domain.subject.action.unit. Example: http.request.duration.seconds. Predictable; greppable.

Lowercase. Period-separated. Singular nouns. Standard across the codebase.

Units always at the end. Time in seconds (or milliseconds, explicitly). Sizes in bytes. Rates per second.

Rules

Use periods or underscores consistently. Mixing is a smell. Most ecosystems prefer one or the other.

Avoid abbreviations that are not universal. 'http' is fine; 'cnxn' is not. Engineers should not need a glossary.

Boolean-named metrics are smell. metric_name with values 0 or 1 is fine; metric_name_active is awkward.

Labels vs metric names

Different metric per behaviour, label per dimension. http.request.duration with method label, not http.get.request.duration as a separate metric.

Cardinality matters. Each unique label combination is a separate time series. High-cardinality labels (user_id, request_id) belong in logs, not metrics.

Standard labels across services: service, environment, version, region. Consistency aids cross-service queries.

Enforcement

Linting at PR time. Custom linter rejects non-conforming names.

Migration support: aliasing old names to new. Old metric continues to work; new metric is the source of truth.

Quarterly audit: drift from convention. Surfaced; fixed.

Why this matters

Engineers can guess metric names. Reduces lookup; increases productivity.

Consistency aids cross-team queries. Operations dashboards composable from per-team metrics.

Long-term: metric names outlive teams and tools. Convention discipline pays for years.