Name metrics with a domain prefix, a clear noun, a unit suffix and, for counters, _total. Use base units such as seconds and bytes, and express percentages as ratios from 0 to 1. Agreeing these rules once saves hours of unit mistakes during incidents.
Why names matter
A graph that says "latency" and a value of 250 leaves a question: milliseconds or seconds? A chart showing 0.25 or 25 for the same disk usage invites a wrong alert threshold. Naming conventions are cheap protection against that class of error.
The Prometheus naming practices are widely used even outside Prometheus. These points come from that page.
The rules
- Start with a single word prefix for the application or domain, such as http or process.
- Use one unit per metric. Do not mix seconds and milliseconds in the same name.
- Use base units: seconds for time and bytes for data.
- Put the unit at the end, in plural form: http_request_duration_seconds, node_memory_usage_bytes.
- Express percentages as ratios from 0 to 1 with a _ratio suffix, such as disk_usage_ratio.
- Use _total for counters that accumulate, such as process_cpu_seconds_total.
- Use _info for pseudo metrics that carry metadata about the running software.
Names versus labels
Put the thing being measured in the name, and the dimensions in labels. A metric like api_http_requests_total with an operation label of create, update or delete is better than three separate metrics. Do not repeat the label name in the metric name, because if you aggregate the label away the name becomes misleading.
Keep a metric to one measured quantity. The page advises that if summing or averaging across the label values would not be meaningful, split them into separate metrics.
Counters, gauges and what to alert on
A counter only goes up, so you graph and alert on its rate. A gauge goes up and down, such as queue depth. Naming the type into the metric, with _total for counters, helps anyone reading a query know which function applies.
A team checklist
When reviewing a new metric, check:
- Is the unit in the name and a base unit?
- Is the name free of the label names?
- Does summing over each label make sense?
- Is the label set small and bounded?
- Is there a description string that says what is counted?
What about logs?
The same thinking helps with log fields. A field called duration with no unit is a future bug. Name it duration_ms or, better, follow the same base unit rule and call it duration_seconds.
Quick check
Should I use milliseconds because they are easier to read?
Store base units and convert at display time. Dashboards can show milliseconds while the stored metric stays in seconds.
Do these rules apply without Prometheus?
The ideas carry over to most metrics systems, though check your tool's own naming rules before renaming.
Sources
Last reviewed: 19 October 2026.
