Course contentsShow
← System Design
Lesson 1182 of 1,91930. Observability: MetricsFree lesson

Metric Naming Conventions

Understand best practices for naming metrics including units, prefixes, and consistency across services.

Metric Naming Conventions

What you'll learn: How to name metrics consistently and clearly so teams can understand, query, and maintain them across distributed systems.

Why Naming Matters

Imagine walking into a massive library where books are titled "Thing1," "Stuff_v2," and "DataPoint." You'd never find what you need. Metrics work the same way—poor naming creates confusion, duplicate metrics, and wasted time hunting for the right data during incidents.

Core Naming Principles

Use consistent structure: Most teams follow a hierarchical pattern like <namespace>_<subsystem>_<metric>_<unit>. For example: http_server_requests_total or database_connection_pool_active_connections.

Always include units: Never make engineers guess. Use suffixes like _seconds, _bytes, _total, _ratio, or _percent. Compare request_latency (ambiguous) with request_latency_seconds (crystal clear).

Use base units: Prefer seconds over milliseconds, bytes over kilobytes. Systems can always scale for display (0.005 seconds shows as "5ms"), but mixing units creates chaos. One service using latency_ms and another using latency_seconds breaks dashboards.

Plural for accumulating metrics: Counters that grow should use plural nouns: http_requests_total, not http_request_total. You're counting multiple requests over time.

Singular for instantaneous states: Gauges showing current values use singular: memory_usage_bytes, active_connection_count.

Consistency across services: If your payments service uses payment_processed_total, don't let checkout use checkout_txn_count. Establish organization-wide prefixes and patterns.

Common Patterns

  • Counters: <thing>_total → errors_total, bytes_sent_total
  • Durations: <operation>_duration_seconds → request_duration_seconds
  • Sizes: <resource>_size_bytes → cache_size_bytes

Key Takeaway: Good metric names are self-documenting, unit-explicit, and consistent across all services—they're the difference between debugging in minutes versus hours.