OM2: Discontinue OM Proto; specify PrometheusProto #2836
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -3,15 +3,17 @@ title: Exposition formats | |||||
| sort_rank: 6 | ||||||
| --- | ||||||
|
|
||||||
| As of Prometheus version 2.0, all processes that expose metrics to Prometheus must use | ||||||
| a **text** format, by default. An alternative, **protobuf** format may be used behind [the HTTP negotiation](./content_negotiation.md). | ||||||
|
|
||||||
| There are various [client libraries](./clientlibs.md) that implement those formats for you. If your preferred language doesn't have a client | ||||||
| library you can [create your own](./writing_clientlibs.md). | ||||||
|
|
||||||
| This document outlines officially supported exposition formats. | ||||||
|
|
||||||
| ## Prometheus Text Format | ||||||
|
|
||||||
| In this section you can find some [basic information](#basic-info) | ||||||
| about this format as well as a more [detailed breakdown](#text-format-details) of the | ||||||
| format. | ||||||
|
|
||||||
|
|
@@ -29,7 +31,7 @@ format. | |||||
| | **Limitations** | <ul><li>Verbose</li><li>Types and docstrings not integral part of the syntax, meaning little-to-nonexistent metric contract validation</li><li>Parsing cost</li></ul>| | ||||||
| | **Supported metric primitives** | <ul><li>Counter</li><li>Gauge</li><li>Histogram</li><li>Summary</li><li>Untyped</li></ul> | | ||||||
|
|
||||||
| ### Details | ||||||
|
|
||||||
| 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. | ||||||
|
|
@@ -115,7 +117,7 @@ format. The following conventions apply: | |||||
| * 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). | ||||||
|
|
||||||
| ### Example | ||||||
|
|
||||||
| Below is an example of a full-fledged Prometheus metric exposition, including | ||||||
| comments, `HELP` and `TYPE` expressions, a histogram, a summary, character | ||||||
|
|
@@ -165,8 +167,13 @@ rpc_duration_seconds_count 2693 | |||||
|
|
||||||
| ## OpenMetrics Text Format | ||||||
|
|
||||||
| OpenMetrics is 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 Prometheus v2.23.0. | ||||||
|
|
||||||
| There are currently three versions of OpenMetrics: | ||||||
|
|
||||||
| * [1.0](../specs/om/open_metrics_spec.md) | ||||||
| * [1.1](../specs/om/open_metrics_spec_1_1.md) | ||||||
| * [2.0](../specs/om/open_metrics_spec_2_0.md) | ||||||
|
|
||||||
| ### Exemplars (Experimental) | ||||||
|
|
||||||
|
|
@@ -176,16 +183,60 @@ with a tracing system can provide more detailed information related to the speci | |||||
|
|
||||||
| To enable this experimental feature you must have at least version v2.26.0 and add `--enable-feature=exemplar-storage` to your arguments. | ||||||
|
|
||||||
| ## Prometheus Protobuf Format | ||||||
|
|
||||||
| Prometheus officially supports [protobuf exposition format](https://developers.google.com/protocol-buffers/) in addition to | ||||||
| the text representation. | ||||||
|
|
||||||
| The payload MUST be encoded as a set of Protobuf messages representing MetricFamily. Messages MUST be encoded in binary and | ||||||
| prepended with their variadic unsigned-integer encoded size, which serves as a delimitation. The varint encoded size delimited | ||||||
| encoding offers streaming capabilities, especially important for large scrape targets. | ||||||
|
|
||||||
| The payload MUST have `application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited` as their content type. | ||||||
|
Member
There was a problem hiding this comment. This is already documented in the content negotiation page, right? do we mention that here again? |
||||||
|
|
||||||
| All string fields MUST be UTF-8 encoded. | ||||||
|
|
||||||
| Prometheus 3.0 [prefers the text-based protocols by default](./content_negotiation.md#default-accept-header) unless: | ||||||
| * Manual preference settings in via `scrape_protocols` setting in Prometheus configuration. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| * [Protobuf format first](./content_negotiation.md#protobuf-first-accept-header) when certain features are enabled e.g.: | ||||||
| * `--enable-feature=created-timestamp-zero-ingestion` or `--enable-feature=st-storage` | ||||||
| * Appropriate configuration option (`scrape_native_histograms: true`) | ||||||
|
|
||||||
| > In Prometheus 2.0, the Protobuf format was marked as deprecated, but since then this decision was reverted. From Prometheus 3.0, the Prometheus Proto is actively used and maintained, supplementing text-based formats. | ||||||
|
|
||||||
| ### Basic info | ||||||
|
|
||||||
| | Aspect | Description | | ||||||
|
Member
Author
There was a problem hiding this comment. FYI: Taken from historical, yet still up-to-date Matt P. document https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?tab=t.0#heading=h.enginc5vuf3z |
||||||
| |--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | ||||||
| | **Inception** | April 2014 | | ||||||
| | **Supported in** | Prometheus version `>=0.4.0` | | ||||||
| | **Transmission** | HTTP | | ||||||
| | **Encoding** | 32-Bit Varint-Encoded Record Length-Delimited Protocol Buffer Messages of `io.prometheus.client.MetricFamily` | | ||||||
| | **HTTP `Content-Type`** | `application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited` | | ||||||
| | **Optional HTTP `Content-Encoding`** | `gzip` | | ||||||
| | **Advantages** | <ul><li>Cross-Platform</li><li>Size</li><li>Forward/Backward Compatibility</li><li>Strict Schema</li><li>Supports Concatenation and Streaming</li></ul> | | ||||||
| | **Limitations** | <ul><li>Not human readable</li></ul> | | ||||||
| | **Supported metric primitives** | <ul><li>Counter</li><li>Gauge</li><li>Histogram</li><li>Summary</li><li>Untyped</li></ul> | | ||||||
|
Contributor
There was a problem hiding this comment. Not sure if we want to list somewhere that it supports exemplars and native histograms? |
||||||
|
|
||||||
| ### When to use Proto over Text? | ||||||
|
|
||||||
| The text format is human-readable, compresses well and is efficient enough for programming use, but Prometheus community also | ||||||
| maintains the protobuf formats, because: | ||||||
|
|
||||||
| * It increases the quality and velocity of new features that can be safely tested in the backward/forward compatible way. | ||||||
| * Protobuf helps with the exposer/ingestor implementations, given the code generation and flexibility features. | ||||||
| * In (surprisingly rare) cases binary encoding can be more efficiently encoded/decoded. | ||||||
|
|
||||||
| You can learn more in [the PromCon 2025 talk](https://www.youtube.com/watch?v=9EgWpkpfl-I&list=PLj6h78yzYM2P534LgwCVm3GQdxLcSt7We&index=3). | ||||||
|
|
||||||
| ### Versioning | ||||||
|
|
||||||
| At the moment Prometheus protobuf is stable, but explicitly unversioned to lean towards the backward and forward compatibility factor. | ||||||
|
Contributor
There was a problem hiding this comment. What does "lean towards the backward and forward compatibility factor" mean? |
||||||
| Instead, it follows Prometheus versioning as a reference. | ||||||
|
|
||||||
| ### Schema | ||||||
|
|
||||||
| Protobuf schema, identified as `io.prometheus.client` is maintained in Prometheus repository [here](https://github.com/prometheus/prometheus/blob/main/prompb/io/prometheus/client/metrics.proto). Schema is also available in [buf registry](https://buf.build/prometheus/prometheus/docs/main:io.prometheus.client). | ||||||
|
|
||||||
| ## HTTP Content-Type requirements | ||||||
|
|
||||||
|
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think we use normative language anywhere else in this doc page. Lets stick with "must" instead of MUST unless we want to turn the whole thing into a specification.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we can even remove the word altogether. "The payload is encoded..." is clear enough already 🤔