Metrics can be exposed to Prometheus using a simple text-based exposition format. There are various client libraries that implement this format for you. If your preferred language doesn't have a client library you can create your own.
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 detailed breakdown of the format.
| Aspect | Description |
|---|---|
| Inception | April 2014 |
| Supported in | Prometheus version >=0.4.0
|
| Transmission | HTTP |
| Encoding | UTF-8, \n line endings |
HTTP Content-Type |
text/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-Encoding |
gzip |
| Advantages |
|
| Limitations |
|
| Supported metric primitives |
|
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.
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.
Lines with a # as the first non-whitespace character are comments. They are
ignored unless the first token after # is either HELP or TYPE. Those
lines are treated as follows: If the token is HELP, at least one more token
is expected, which is the metric name. All remaining tokens are considered the
docstring for that metric name. HELP lines may contain any sequence of UTF-8
characters (after the metric name), but the backslash and the line feed
characters have to be escaped as \\ and \n, respectively. Only one HELP
line may exist for any given metric name.
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):
metric_name [
"{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
] 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.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.All lines for a given metric must be provided as one single group, with
the optional HELP and TYPE lines first (in no particular order). Beyond
that, reproducible sorting in repeated expositions is preferred but not
required, 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.
The histogram and summary types are difficult to represent in the text
format. The following conventions apply:
x is given as a separate sample named x_sum.x is given as a separate sample named x_count.x is given as a separate sample line with the same name x and a label {quantile="y"}.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).{le="+Inf"}. Its value must be identical to the value of x_count.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.
# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027 1395066363000
http_requests_total{method="post",code="400"} 3 1395066363000
# Escaping in label values:
msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9
# Minimalistic line:
metric_without_timestamp_and_labels 12.47
# A weird metric from before the epoch:
something_weird{problem="division by zero"} +Inf -3982045
# A histogram, which has a pretty complex representation in the text format:
# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.2"} 100392
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320
# Finally a summary, which has a complex representation, too:
# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.01"} 3102
rpc_duration_seconds{quantile="0.05"} 3272
rpc_duration_seconds{quantile="0.5"} 4773
rpc_duration_seconds{quantile="0.9"} 9001
rpc_duration_seconds{quantile="0.99"} 76656
rpc_duration_seconds_sum 1.7560473e+07
rpc_duration_seconds_count 2693
OpenMetrics is the an effort to standardize metric wire formatting built off of Prometheus text format. It is possible to scrape targets and it is also available to use for federating metrics since at least v2.23.0.
Utilizing the OpenMetrics format allows for the exposition and querying of Exemplars. Exemplars provide a point in time snapshot related to a metric set for an otherwise summarized MetricFamily. Additionally they may have a Trace ID attached to them which when used to together with a tracing system can provide more detailed information related to the specific service.
To enable this experimental feature you must have at least version v2.26.0 and add --enable-feature=exemplar-storage to your arguments.
Earlier versions of Prometheus supported an exposition format based on Protocol Buffers (aka Protobuf) in addition to the current text-based format. With Prometheus 2.0, the Protobuf format was marked as deprecated and Prometheus stopped ingesting samples from said exposition format.
However, new experimental features were added to Prometheus where the Protobuf format was considered the most viable option. Making Prometheus accept Protocol Buffers once again.
Here is a list of experimental features that, once enabled, will configure Prometheus to favor the Protobuf exposition format:
| feature flag | version that introduced it |
|---|---|
| native-histograms | 2.40.0 |
| created-timestamp-zero-ingestion | 2.50.0 |
For details on historical format versions, see the legacy Client Data Exposition Format document.
The current version of the original Protobuf format (with the recent extensions for native histograms) is maintained in the prometheus/client_model repository.
This documentation is open-source. Please help improve it by filing issues or pull requests.