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

Metric Naming Conventions

Consistent naming schemes with namespaces, clear units, and hierarchical structure for maintainable metric catalogs.

Metric Naming Conventions

What you'll learn: How to design consistent, maintainable naming schemes for your metrics using namespaces, clear units, and hierarchical structures.

Why Naming Matters

Imagine walking into a massive library where books are titled "Book1," "Book2," "Thing37." Finding what you need would be impossible. Metrics are the same—without consistent naming conventions, your observability system becomes a chaotic mess where engineers waste time hunting for the right data or accidentally create duplicate metrics.

The Core Elements

Namespaces and Hierarchy
Use dot-separated or underscore-separated hierarchies that mirror your system's structure:

  • service.component.metric_name (e.g., payment.processor.requests_total)
  • Start with the broadest scope and drill down: company.product.service.feature.measurement

Include Units Explicitly
Never make engineers guess. Append units to metric names:

  • api_latency_seconds (not api_latency)
  • cache_size_bytes (not cache_size)
  • request_rate_per_second (or use suffix _total for counters)

Consistent Suffixes for Metric Types
Adopt standard suffixes that signal the metric type:

  • _total for counters: http_requests_total
  • _current or no suffix for gauges: connections_current
  • _seconds or _milliseconds for histograms/summaries measuring duration
  • _bytes for sizes

Readable and Descriptive
Use full words, not cryptic abbreviations. database_query_duration_seconds beats db_qry_dur_s. Your future self will thank you.

Maintainability

A well-designed naming scheme means new engineers can intuitively find metrics, dashboards auto-populate sensibly, and alert rules remain clear. Treat your metric catalog like an API—once published, changing names breaks downstream consumers.

Key Takeaway: Metric naming conventions using namespaces, explicit units, and consistent hierarchical patterns transform your metrics from chaotic data points into a navigable, maintainable observability catalog.