Metric and label naming
The metric and label conventions presented in this document are not requiredfor using Prometheus, but can serve as both a style-guide and a collection ofbest practices. Individual organizations may want to approach some of these practices, e.g. naming conventions, differently.
Metric names
A metric name…
- …must comply with the data model for valid characters.
- …should have a (single-word) application prefix relevant to the domain themetric belongs to. The prefix is sometimes referred to as
namespace
byclient libraries. For metrics specific to an application, the prefix isusually the application name itself. Sometimes, however, metrics are moregeneric, like standardized metrics exported by client libraries. Examples:prometheus_notifications_total
(specific to the Prometheus server)process_cpu_seconds_total
(exported by many client libraries)http_request_duration_seconds
(for all HTTP requests)
- …must have a single unit (i.e. do not mix seconds with milliseconds, or seconds with bytes).
- …should use base units (e.g. seconds, bytes, meters - not milliseconds, megabytes, kilometers). See below for a list of base units.
- …should have a suffix describing the unit, in plural form. Note that an accumulating count has
total
as a suffix, in addition to the unit if applicable.httprequest_durationseconds
nodememory_usagebytes
httprequeststotal
(for a unit-less accumulating count)processcpuseconds_total
(for an accumulating count with unit)foobar_build_info
(for a pseudo-metric that provides metadata about the running binary)
- …should represent the same logical thing-being-measured across all labeldimensions.
- request duration
- bytes of data transfer
- instantaneous resource usage as a percentageAs a rule of thumb, either the
sum()
or theavg()
over all dimensions of agiven metric should be meaningful (though not necessarily useful). If it is notmeaningful, split the data up into multiple metrics. For example, having thecapacity of various queues in one metric is good, while mixing the capacity of aqueue with the current number of elements in the queue is not.
Labels
Use labels to differentiate the characteristics of the thing that is being measured:
api_http_requests_total
- differentiate request types:operation="create|update|delete"
api_request_duration_seconds
- differentiate request stages:stage="extract|transform|load"
Do not put the label names in the metric name, as this introduces redundancyand will cause confusion if the respective labels are aggregated away.
CAUTION: Remember that every unique combination of key-value labelpairs represents a new time series, which can dramatically increase the amountof data stored. Do not use labels to store dimensions with high cardinality(many different label values), such as user IDs, email addresses, or otherunbounded sets of values.
Base units
Prometheus does not have any units hard coded. For better compatibility, baseunits should be used. The following lists some metrics families with their base unit.The list is not exhaustive.
Family | Base unit | Remark |
---|---|---|
Time | seconds | |
Temperature | celsius | celsius is preferred over kelvin for practical reasons. |
Length | meters | |
Bytes | bytes | |
Bits | bytes | To avoid confusion combining different metrics, always use bytes, even where bits appear more common. |
Percent | ratio | Values are 0–1 (rather than 0–100). ratio is only used as a suffix for names like diskusage_ratio . The usual metric name follows the pattern A_per_B . |
Voltage | volts | |
Electric current | amperes | |
Energy | joules | |
Mass | grams | _grams is preferred over kilograms to avoid issues with the kilo prefix. |