Data model

Prometheus fundamentally stores all data as timeseries: streams of timestampedvalues belonging to the same metric and the same set of labeled dimensions.Besides stored time series, Prometheus may generate temporary derived time seriesas the result of queries.

Metric names and labels

Every time series is uniquely identified by its metric name and optionalkey-value pairs called labels.

The metric name specifies the general feature of a system that is measured(e.g. httprequests_total - the total number of HTTP requests received). Itmay contain ASCII letters and digits, as well as underscores and colons. Itmust match the regex [a-zA-Z:][a-zA-Z0-9_:]*.

Note: The colons are reserved for user defined recording rules. They should notbe used by exporters or direct instrumentation.

Labels enable Prometheus's dimensional data model: any given combination oflabels for the same metric name identifies a particular dimensionalinstantiation of that metric (for example: all HTTP requests that used themethod POST to the /api/tracks handler). The query languageallows filtering and aggregation based on these dimensions. Changing any labelvalue, including adding or removing a label, will create a new time series.

Label names may contain ASCII letters, numbers, as well as underscores. Theymust match the regex [a-zA-Z][a-zA-Z0-9]*. Label names beginning with __are reserved for internal use.

Label values may contain any Unicode characters.

See also the best practices for naming metrics and labels.

Samples

Samples form the actual time series data. Each sample consists of:

  • a float64 value
  • a millisecond-precision timestamp

Notation

Given a metric name and a set of labels, time series are frequently identifiedusing this notation:

  1. <metric name>{<label name>=<label value>, ...}

For example, a time series with the metric name api_http_requests_total andthe labels method="POST" and handler="/messages" could be written likethis:

  1. api_http_requests_total{method="POST", handler="/messages"}

This is the same notation that OpenTSDB uses.