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

Metric Naming Conventions

Establishing consistent naming patterns with units, measurement types, and hierarchical namespaces.

Metric Naming Conventions

What you'll learn: How to name metrics consistently so they're self-documenting, easy to query, and maintainable at scale.

Why Naming Matters

Imagine a library where books are labeled "Thing1," "Thing2," "Stuff." You'd never find what you need. Metric names are the same—they're your primary documentation when investigating incidents at 3 AM or building dashboards. Good naming conventions make metrics instantly understandable and prevent confusion across teams.

Core Naming Principles

1. Include the unit: Never make engineers guess. Use _seconds, _bytes, _total, or _ratio suffixes:

  • http_request_duration_seconds (not http_request_time)
  • memory_usage_bytes (not memory_used)

2. Specify measurement type: Align with metric types you know:

  • Counters end in _total: http_requests_total
  • Gauges describe state: active_connections
  • Histograms include _bucket, _sum, _count automatically

3. Use hierarchical namespaces: Organize with prefixes, moving from general to specific:

  • application_component_operation_measurement_unit
  • Example: payment_processor_transactions_processed_total
  • This groups related metrics naturally when browsing

4. Snake_case convention: Use lowercase with underscores: cache_hit_ratio, not CacheHitRatio or cache-hit-ratio.

Practical Pattern

A well-named metric tells a story:

service_subsystem_action_measurement_unit

Example: api_database_queries_duration_seconds immediately tells you it's about the API's database query timing, measured in seconds.

Key Takeaway: Consistent metric naming with explicit units, clear measurement types, and hierarchical namespaces transforms raw numbers into self-documenting observability data that scales across your entire organization.