The metric and label conventions presented in this document are not required for using Prometheus, but can serve as both a style-guide and a collection of best practices. Individual organizations may want to approach some of these practices, e.g. naming conventions, differently.
A metric name...
namespaceby client libraries. For metrics specific to an application, the prefix is usually the application name itself. Sometimes, however, metrics are more generic, 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)
totalas a suffix, in addition to the unit if applicable.
http_requests_total(for a unit-less accumulating count)
process_cpu_seconds_total(for an accumulating count with unit)
foobar_build_info(for a pseudo-metric that provides metadata about the running binary)
As a rule of thumb, either the
sum() or the
avg() over all dimensions of a
given metric should be meaningful (though not necessarily useful). If it is not
meaningful, split the data up into multiple metrics. For example, having the
capacity of various queues in one metric is good, while mixing the capacity of a
queue with the current number of elements in the queue is not.
Use labels to differentiate the characteristics of the thing that is being measured:
api_http_requests_total- differentiate request types:
api_request_duration_seconds- differentiate request stages:
Do not put the label names in the metric name, as this introduces redundancy and will cause confusion if the respective labels are aggregated away.
Prometheus does not have any units hard coded. For better compatibility, base units should be used. The following lists some metrics families with their base unit. The list is not exhaustive.
|Temperature||celsius||celsius is preferred over kelvin for practical reasons. kelvin is acceptable as a base unit in special cases like color temperature or where temperature has to be absolute.|
|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).
|Power||Prefer exporting a counter of joules, then
|Mass||grams||grams is preferred over kilograms to avoid issues with the kilo prefix.|
This documentation is open-source. Please help improve it by filing issues or pull requests.