Exposition formats

Metrics can be exposed to Prometheus using a simple text-basedexposition format. There are various client librariesthat implement this format for you. If your preferred language doesn't have a clientlibrary you can create your own.

NOTE: Some earlier versions of Prometheus supported an exposition format based onProtocol Buffers (aka Protobuf) inaddition to the current text-based format. As of version 2.0, however, Prometheus nolonger supports the Protobuf-based format. You can read about the reasoning behindthis change in thisdocument.

Text-based format

As of Prometheus version 2.0, all processes that expose metrics to Prometheus need to usea text-based format. In this section you can find some basic informationabout this format as well as a more detailed breakdown of theformat.

Basic info

AspectDescription
InceptionApril 2014
Supported inPrometheus version >=0.4.0
TransmissionHTTP
EncodingUTF-8, \n line endings
HTTP Content-Typetext/plain; version=0.0.4 (A missing version value will lead to a fall-back to the most recent text format version.)
Optional HTTP Content-Encodinggzip
Advantages- Human-readable- Easy to assemble, especially for minimalistic cases (no nesting required)- Readable line by line (with the exception of type hints and docstrings)
Limitations- Verbose- Types and docstrings not integral part of the syntax, meaning little-to-nonexistent metric contract validation- Parsing cost
Supported metric primitives- Counter- Gauge- Histogram- Summary- Untyped

Text format details

Prometheus' text-based format is line oriented. Lines are separated by a linefeed character (\n). The last line must end with a line feed character.Empty lines are ignored.

Line format

Within a line, tokens can be separated by any number of blanks and/or tabs (andmust be separated by at least one if they would otherwise merge with the previoustoken). Leading and trailing whitespace is ignored.

Comments, help text, and type information

Lines with a # as the first non-whitespace character are comments. They areignored unless the first token after # is either HELP or TYPE. Thoselines are treated as follows: If the token is HELP, at least one more tokenis expected, which is the metric name. All remaining tokens are considered thedocstring for that metric name. HELP lines may contain any sequence of UTF-8characters (after the metric name), but the backslash and the line feedcharacters have to be escaped as \ and \n, respectively. Only one HELPline may exist for any given metric name.

If the token is TYPE, exactly two more tokens are expected. The first is themetric name, and the second is either counter, gauge, histogram,summary, or untyped, defining the type for the metric of that name. Onlyone TYPE line may exist for a given metric name. The TYPE line for ametric name must appear before the first sample is reported for that metricname. If there is no TYPE line for a metric name, the type is set tountyped.

The remaining lines describe samples (one per line) using the following syntax(EBNF):

  1. metric_name [
  2. "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
  3. ] value [ timestamp ]

In the sample syntax:

  • metric_name and label_name carry the usual Prometheus expression language restrictions.
  • label_value can be any sequence of UTF-8 characters, but the backslash (\, double-quote ("}, and line feed (\n) characters have to be escaped as \, \", and \n, respectively.
  • value is a float represented as required by Go's ParseFloat() function. In addition to standard numerical values, Nan, +Inf, and -Inf are valid values representing not a number, positive infinity, and negative infinity, respectively.
  • The timestamp is an int64 (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by Go's ParseInt() function.

Grouping and sorting

All lines for a given metric must be provided as one single group, withthe optional HELP and TYPE lines first (in no particular order). Beyondthat, reproducible sorting in repeated expositions is preferred but notrequired, i.e. do not sort if the computational cost is prohibitive.

Each line must have a unique combination of a metric name and labels. Otherwise,the ingestion behavior is undefined.

Histograms and summaries

The histogram and summary types are difficult to represent in the textformat. The following conventions apply:

  • The sample sum for a summary or histogram named x is given as a separate sample named x_sum.
  • The sample count for a summary or histogram named x is given as a separate sample named x_count.
  • Each quantile of a summary named x is given as a separate sample line with the same name x and a label {quantile="y"}.
  • Each bucket count of a histogram named x is given as a separate sample line with the name x_bucket and a label {le="y"} (where y is the upper bound of the bucket).
  • A histogram must have a bucket with {le="+Inf"}. Its value must be identical to the value of x_count.
  • The buckets of a histogram and the quantiles of a summary must appear in increasing numerical order of their label values (for the le or the quantile label, respectively).

Text format example

Below is an example of a full-fledged Prometheus metric exposition, includingcomments, HELP and TYPE expressions, a histogram, a summary, characterescaping examples, and more.

  1. # HELP http_requests_total The total number of HTTP requests.
  2. # TYPE http_requests_total counter
  3. http_requests_total{method="post",code="200"} 1027 1395066363000
  4. http_requests_total{method="post",code="400"} 3 1395066363000
  5. # Escaping in label values:
  6. msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9
  7. # Minimalistic line:
  8. metric_without_timestamp_and_labels 12.47
  9. # A weird metric from before the epoch:
  10. something_weird{problem="division by zero"} +Inf -3982045
  11. # A histogram, which has a pretty complex representation in the text format:
  12. # HELP http_request_duration_seconds A histogram of the request duration.
  13. # TYPE http_request_duration_seconds histogram
  14. http_request_duration_seconds_bucket{le="0.05"} 24054
  15. http_request_duration_seconds_bucket{le="0.1"} 33444
  16. http_request_duration_seconds_bucket{le="0.2"} 100392
  17. http_request_duration_seconds_bucket{le="0.5"} 129389
  18. http_request_duration_seconds_bucket{le="1"} 133988
  19. http_request_duration_seconds_bucket{le="+Inf"} 144320
  20. http_request_duration_seconds_sum 53423
  21. http_request_duration_seconds_count 144320
  22. # Finally a summary, which has a complex representation, too:
  23. # HELP rpc_duration_seconds A summary of the RPC duration in seconds.
  24. # TYPE rpc_duration_seconds summary
  25. rpc_duration_seconds{quantile="0.01"} 3102
  26. rpc_duration_seconds{quantile="0.05"} 3272
  27. rpc_duration_seconds{quantile="0.5"} 4773
  28. rpc_duration_seconds{quantile="0.9"} 9001
  29. rpc_duration_seconds{quantile="0.99"} 76656
  30. rpc_duration_seconds_sum 1.7560473e+07
  31. rpc_duration_seconds_count 2693

Historical versions

For details on historical format versions, see the legacyClient Data Exposition Formatdocument.