patternjavascriptModerate
Custom metrics: designing metric names and label schemas
Viewed 0 times
metric namingprometheus conventionsnake_caseunit suffix_total counter_secondslabel schemacross-service query
Problem
Metrics have inconsistent names across services (request_count, numRequests, http.requests), making it impossible to write cross-service queries or maintain dashboards. Label schemas are inconsistent, preventing aggregation.
Solution
Adopt a consistent naming convention and label schema across all services.
Prometheus naming convention:
Example:
Rules:
Standard labels across all services:
Per-metric labels (low cardinality only):
Prometheus naming convention:
<namespace>_<subsystem>_<name>_<unit>Example:
http_requests_total, db_query_duration_seconds, cache_hit_ratioRules:
- Use snake_case, never camelCase or dots
- Include the unit in the name:
_seconds,_bytes,_total(for counters) _totalsuffix for counters (Prometheus convention)_ratiofor values between 0 and 1_infofor info metrics (constant labels describing a process)
Standard labels across all services:
// These labels should be consistent across every service
const STANDARD_LABELS = ['service', 'environment', 'version', 'region'];
// Applied as attributes on the OTel resource, not per-metric labelsPer-metric labels (low cardinality only):
// Good: bounded set of values
{ method: 'GET', status_code: '200', route: '/api/orders' }
// Bad: unbounded values
{ user_id: '...', order_id: '...', ip_address: '...' }Why
Consistent naming enables fleet-wide dashboards and cross-service comparison. The unit in the name prevents conversion errors (milliseconds vs seconds vs nanoseconds).
Gotchas
- Avoid abbreviations — 'ms' vs 'millis' vs 'milliseconds' causes confusion; use full unit names
- Don't include labels in the metric name — bad: http_get_requests_total, good: http_requests_total with method='GET' label
- Changing a metric name is a breaking change — existing dashboards and alerts break; version carefully
- OpenTelemetry uses dot-separated names by convention (http.request.duration) which are converted to underscores by the Prometheus exporter
Context
Establishing metrics standards across a microservices fleet
Revisions (0)
No revisions yet.