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(nothttp_request_time)memory_usage_bytes(notmemory_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,_countautomatically
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.