Skip to main content
Clear, consistent metric names make monitoring easier to understand, query, and maintain. This guide covers practical naming conventions and what to instrument for different application types (online-serving systems, offline pipelines, and batch jobs). These recommendations align with Prometheus best practices to ensure interoperability with client libraries and tools.

​
Metric naming rules

Follow these core rules when naming metrics:
  • Use snake_case: all lowercase with underscores (for example http_requests_total).
  • Prefix the metric with the owning application or library: e.g., postgres_ → postgres_queue_size_bytes.
  • Make the metric name descriptive; use multiple words when needed (for example: queue_size).
  • Always include the base unit (seconds, bytes, meters, etc.) to avoid ambiguity. Prefer unprefixed base units such as seconds and bytes; avoid using prefixed units like kilobytes or microseconds in the metric name.
  • Respect reserved suffixes created by client libraries: _total, _count, _sum, and _bucket. Do not add these manually except when creating counter metrics yourself:
    • Use _total for counters (for example, http_requests_total).
    • Do not manually append _count, _sum, or _bucket for histograms or summaries — the client library will generate those.
Counters should use the _total suffix (see Prometheus naming best practices). Do not manually add _count, _sum, _bucket, or other reserved suffixes for metric types where the client library will create them automatically.
A compact name format to follow:
Examples of good and bad metric names:
Notes on the incorrect examples:
  • container_docker_restarts places the library name (docker) in the middle; prefer docker_container_restarts.
  • http_requests_sum is misleading — use _total for counters, not generic words like sum.
  • nginx_disk_free_kilobytes uses a prefixed unit; use bytes instead (for example nginx_disk_free_bytes).
  • dotnet_queue_waiting_time omits the unit — include seconds or another base unit (for example dotnet_queue_waiting_seconds).

​
What to instrument

Instrumentation choices depend on the type of system you run. Below are typical metrics to collect for each system type and why they matter.

​
Online-serving systems

(Examples: databases, web servers, APIs — systems expected to respond immediately.) Recommended metrics:
  • Total number of requests or queries (_total counters)
  • Number of errors (counters or error-rate gauges)
  • Latency distributions (histograms or summaries) — durations in seconds
  • Number of in-progress requests (gauges)
A presentation slide titled "What to Instrument" explaining that online-serving systems expect an immediate response. It lists metrics to monitor: number of queries/requests, number of errors, latency, and number of in-progress requests.

​
Offline processing systems

(Examples: streaming pipelines or long-running workers that process data continuously.) For each pipeline stage, measure:
  • Amount of work processed (counters)
  • Queued work size (gauges)
  • Work in progress (gauges)
  • Processing rate / throughput (derived from counters or a rate function)
  • Error and failure counts (counters)
These metrics help detect backpressure, stage stalls, or throughput regressions.

​
Batch jobs

(Batch jobs run periodically or ad hoc, often short-lived.) Challenges:
  • Short-lived jobs may not be scrapeable directly by a Prometheus server.
  • Use a push mechanism (for example, Prometheus Pushgateway) so the job can push metrics for later scraping.
Useful metrics to expose:
  • Time to process each stage (durations in seconds)
  • Overall runtime (seconds)
  • Success/failure counts (_total counters)
  • Total items processed and throughput (counters and/or derived rates)
A presentation slide titled "What to Instrument" explaining that batch jobs run on a regular schedule unlike continuously running offline-serving systems. It also notes batch jobs will require a pushGateway since they aren't continuously running to be scraped.

​
Quick reference: metrics by system type

By following these naming and instrumentation patterns, you’ll make your metrics easier to query, combine, and maintain across services and teams.

Watch Video

Practice Lab