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(notapi_latency)cache_size_bytes(notcache_size)request_rate_per_second(or use suffix_totalfor counters)
Consistent Suffixes for Metric Types
Adopt standard suffixes that signal the metric type:
_totalfor counters:http_requests_total_currentor no suffix for gauges:connections_current_secondsor_millisecondsfor histograms/summaries measuring duration_bytesfor 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.