Exposition formats

    As of Prometheus version 2.0, all processes that expose metrics to Prometheus need to use a text-based format. In this section you can find some basic information about this format as well as a more of the format.

    Prometheus’ text-based format is line oriented. Lines are separated by a line feed 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 (and must be separated by at least one if they would otherwise merge with the previous token). Leading and trailing whitespace is ignored.

    Comments, help text, and type information

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

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

    In the sample syntax:

    • metric_name and label_name carry the usual Prometheus expression language restrictions.
    • value is a float represented as required by Go’s 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

    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 text format. 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).

    Below is an example of a full-fledged Prometheus metric exposition, including comments, HELP and TYPE expressions, a histogram, a summary, character escaping examples, and more.

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

    Historical versions