diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md
index 646dfec8d..14f77be2a 100644
--- a/docs/instrumenting/exposition_formats.md
+++ b/docs/instrumenting/exposition_formats.md
@@ -3,33 +3,36 @@ title: Exposition formats
sort_rank: 6
---
-Metrics can be exposed to Prometheus using a simple [text-based](#text-based-format)
-exposition format. There are various [client libraries](/docs/instrumenting/clientlibs/)
-that implement this format for you. If your preferred language doesn't have a client
-library you can [create your own](/docs/instrumenting/writing_clientlibs/).
+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).
-## Text-based format
+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).
-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](#basic-info)
+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.
### Basic info
-| 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** | - 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
+| 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` with parameters:
- `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** |
- Human-readable
- Easy to assemble, especially for minimalistic cases (no nesting required)
- Readable line by line (with the exception of metadata)
|
+| **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
|
+| **Supported advanced features** | |
+
+### 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 +118,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).
-### Text format example
+### Example
Below is an example of a full-fledged Prometheus metric exposition, including
comments, `HELP` and `TYPE` expressions, a histogram, a summary, character
@@ -165,27 +168,88 @@ rpc_duration_seconds_count 2693
## OpenMetrics Text Format
-[OpenMetrics](https://github.com/OpenObservability/OpenMetrics) is the 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.
+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 two versions of OpenMetrics:
+
+* [1.0](../specs/om/open_metrics_spec.md)
+* [2.0 (draft)](../specs/om/open_metrics_spec_2_0.md)
+
+### Basic info
+
+| Aspect | Description |
+|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Inception** | November 2020 |
+| **Supported in** | Prometheus version `>=2.5.0` |
+| **Transmission** | HTTP |
+| **Encoding** | UTF-8, `\n` line endings, trailed with `# EOF`. |
+| **HTTP `Content-Type`** | `application/openmetrics-text` with parameters:
- `version=1.0.0` (a missing `version` value will lead to a fall-back to the most recent text OpenMetrics version.)
|
+| **Optional HTTP `Content-Encoding`** | `gzip` |
+| **Advantages** | - Human-readable
- Easy to assemble, especially for minimalistic cases (no nesting required)
- Readable line by line (with the exception of metadata)
|
+| **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
- GaugeHistogram
- Summary
- Info
- StateSet
- Untyped
|
+| **Supported advanced features** | - Unit metadata
- Exemplars (Counters, Histogram, GaugeHistogram)
- Created/Start Timestamps (Counter, Histogram, GaugeHistogram, Summary)
- UTF-8 metric names and label names
|
### Exemplars (Experimental)
Utilizing the OpenMetrics format allows for the exposition and querying of [Exemplars](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#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
+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.
-## Protobuf format
+## 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](#schema). 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.
+
+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 via `scrape_protocols` setting in Prometheus configuration.
+* [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 |
+|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **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` with parameters:
- `proto=io.prometheus.client.MetricFamily`
- `encoding=delimited`
|
+| **Optional HTTP `Content-Encoding`** | `gzip` |
+| **Advantages** | - Cross-Platform
- Size
- Forward/Backward Compatibility
- Strict Schema
- Supports Concatenation and Streaming
- Composite Values
|
+| **Limitations** | |
+| **Supported metric primitives** | - Counter
- Gauge
- Histogram
- GaugeHistogram
- Summary
- Untyped
|
+| **Supported advanced features** | - Unit metadata
- Exemplars (Counters, Histogram, GaugeHistogram)
- Created/Start Timestamps (Counter, Histogram, GaugeHistogram, Summary)
- Native (sparse and exponential) Histogram, GaugeHistogram
- UTF-8 metric names and label names
|
+
+### 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
-Earlier versions of Prometheus supported an exposition format based on [Protocol Buffers](https://developers.google.com/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.
+At the moment Prometheus protobuf is stable, but explicitly unversioned. Instead, it follows Prometheus versioning as a reference.
-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.
+### Schema
-When such features are enabled either by feature flag
-(`--enable-feature=created-timestamp-zero-ingestion`) or by setting the
-appropriate configuration option (`scrape_native_histograms: true`) then
-Protobuf will be favored over other exposition formats.
+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
diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md
index 79e2ad35d..79bbea9bc 100644
--- a/docs/specs/om/open_metrics_spec_2_0.md
+++ b/docs/specs/om/open_metrics_spec_2_0.md
@@ -392,15 +392,15 @@ Unknown SHOULD NOT be used. Unknown MAY be used when it is impossible to determi
A point in a metric with the unknown type MUST have a single value.
-# Data transmission & wire formats
-
-The text wire format MUST be supported and is the default. The protobuf wire format MAY be supported and MUST ONLY be used after negotiation.
+## Text Format
The OpenMetrics formats are Regular Chomsky Grammars, making writing quick and small parsers possible.
-The text format compresses well, and protobuf is already binary and efficiently encoded.
Partial or invalid expositions MUST be considered erroneous in their entirety.
+> NOTE: Previous versions of [OpenMetrics](https://prometheus.io/docs/specs/om/open_metrics_spec/#protobuf-format) used
+> to specify a [OpenMetric protobuf format](https://github.com/prometheus/OpenMetrics/blob/3bb328ab04d26b25ac548d851619f90d15090e5d/proto/openmetrics_data_model.proto). OpenMetrics 2.0 does not include the protobuf representation. For available formats, including the official [Prometheus protobuf wire format](https://prometheus.io/docs/instrumenting/exposition_formats/#protobuf-format), see [exposition formats documentation](https://prometheus.io/docs/instrumenting/exposition_formats).
+
### Protocol Negotiation
All ingestor implementations MUST be able to ingest data secured with TLS 1.2 or later. All exposers SHOULD be able to emit data secured with TLS 1.2 or later. ingestor implementations SHOULD be able to ingest data from HTTP without TLS. All implementations SHOULD use TLS to transmit data.
@@ -409,9 +409,7 @@ Negotiation of what version of the OpenMetrics format to use is out-of-band. For
Push-based negotiation is inherently more complex, as the exposer typically initiates the connection. Producers MUST use the oldest version of the standard (i.e. 1.0.0) unless requested otherwise by the ingestor.
-### Text format
-
-#### ABNF
+### ABNF
ABNF as per RFC 5234
@@ -572,7 +570,7 @@ cs-q-counts = cs-q-count *("," cs-q-count)
cs-q-count = realnumber ":" number
```
-#### Overall Structure
+### Overall Structure
UTF-8 MUST be used. Byte order markers (BOMs) MUST NOT be used. As an important reminder for implementers, byte 0 is valid UTF-8 while, for example, byte 255 is not.
@@ -612,7 +610,7 @@ acme_http_request_seconds:rate5m{path="/api/v1",method="GET"} {count:0.01,sum:2.
# EOF
```
-##### UTF-8 Quoting
+#### UTF-8 Quoting
Metric names not conforming to the ABNF definition of `metricname` MUST be
enclosed in double quotes and the alternative UTF-8 syntax MUST be used. In
@@ -642,7 +640,7 @@ Complete example:
# EOF
```
-##### Escaping
+#### Escaping
Where the ABNF notes escaping, the following escaping MUST be applied
Line feed, `\n` (0x0A) -> literally `\\n` (Bytecode 0x5c 0x6e)
@@ -655,28 +653,28 @@ As an example, `\\\\a` is equivalent and preferable to `\\a`.
Escaping MUST also be applied to quoted UTF-8 strings.
-##### Numbers
+#### Numbers
Integer numbers MUST NOT have a decimal point. Examples are `23`, `0042`, and `1341298465647914`.
Floating point numbers MUST be represented either with a decimal point or using scientific notation. Examples are `8903.123421` and `1.89e-7`. Floating point numbers MUST fit within the range of a 64-bit floating point value as defined by IEEE 754, but MAY require so many bits in the mantissa that results in lost precision. This MAY be used to encode nanosecond resolution timestamps.
-###### CompositeValues
+##### CompositeValues
CompositeValue is represented as structured data with fields. There MUST NOT be any whitespace around fields. See the ABNF for exact details about the format and possible values.
-##### Timestamps
+#### Timestamps
Timestamps SHOULD NOT use exponential float rendering for timestamps if nanosecond precision is needed as rendering of a float64 does not have sufficient precision, e.g. `1604676851.123456789`.
-#### MetricFamily
+### MetricFamily
There MUST NOT be an explicit separator between MetricFamilies. The next MetricFamily MUST be signalled with either metadata or a new sample metric name which cannot be part of the previous MetricFamily.
MetricFamilies MUST NOT be interleaved.
-##### MetricFamily metadata
+#### MetricFamily metadata
There are four pieces of metadata: The MetricFamily name, TYPE, UNIT and HELP. An example of the metadata for a counter Metric called foo is:
@@ -726,7 +724,7 @@ There MUST NOT be more than one of each type of metadata line for a MetricFamily
Aside from this metadata and the EOF line at the end of the message, you MUST NOT expose lines beginning with a #.
-##### Metric
+#### Metric
Metrics MUST NOT be interleaved.
@@ -759,7 +757,7 @@ See the UTF-8 Quoting section for specifics.
The rendering of values for a MetricPoint can include additional labels (e.g. the "le" label for a Histogram type), which MUST be rendered in the same way as a Metric's own LabelSet.
-#### MetricPoint
+### MetricPoint
MetricPoints MUST NOT be interleaved.
@@ -804,9 +802,9 @@ foo{entity="controller",env="prod",foo="bb"} 0.0
foo{entity="controller",env="prod",foo="ccc"} 0.0
```
-#### Metric types
+### Metric types
-##### Gauge
+#### Gauge
The Sample MetricName for the value of a MetricPoint for a MetricFamily of type Gauge MUST NOT have a suffix.
@@ -853,7 +851,7 @@ foo 17.0 123
foo 18.0 456
```
-##### Counter
+#### Counter
The MetricPoint's Total Value Sample MetricName SHOULD have the suffix `_total`. If present, the MetricPoint's Start Timestamp MUST be inlined with the Metric point with a `st@` prefix. If the value's timestamp is present, the Start Timestamp MUST be added right after it. If exemplar is present, the Start Timestamp MUST be added before it.
@@ -903,7 +901,7 @@ An example with a Metric with no labels, and a MetricPoint with a timestamp and
foo_total 17.0 1520879607.789 st@1520430000.123 # {trace_id="KOO5S4vxi0o"} 0.67 1520879606.1
```
-##### StateSet
+#### StateSet
The Sample MetricName for the value of a MetricPoint for a MetricFamily of type StateSet MUST NOT have a suffix.
@@ -930,7 +928,7 @@ foo{entity="replica",foo="bb"} 0.0
foo{entity="replica",foo="ccc"} 1.0
```
-##### Info
+#### Info
The Sample MetricName for the value of a MetricPoint for a MetricFamily of type Info MUST have the suffix `_info`. The Sample value MUST always be 1.
@@ -951,7 +949,7 @@ foo_info{entity="replica",name="prettier name",version="8.1.9"} 1.0
Metric labels and MetricPoint value labels MAY be in any order.
-##### Summary
+#### Summary
The MetricPoint's value MUST be a CompositeValue.
@@ -975,7 +973,7 @@ An example of a Metric with no labels and a MetricPoint with two quantiles and S
foo {count:0,sum:0.0,quantile:[0.95:123.7,0.99:150]} st@1520430000.123
```
-##### Histogram with Classic Buckets
+#### Histogram with Classic Buckets
The MetricPoint's value MUST be a CompositeValue.
@@ -994,7 +992,7 @@ An example of a Metric with no labels and a MetricPoint with Sum, Count, and Sta
foo {count:17,sum:324789.3,bucket:[0.0:0,1e-05:0,0.0001:5,0.1:8,1.0:10,10.0:11,100000.0:11,1e+06:15,1e+23:16,1.1e+23:17,+Inf:17]} st@1520430000.123
```
-##### Histogram with Native Buckets
+#### Histogram with Native Buckets
The MetricPoint's value MUST be a CompositeValue.
@@ -1030,7 +1028,7 @@ An example without any buckets in use:
acme_http_request_seconds{path="/api/v1",method="GET"} {count:0,sum:0,schema:3,zero_threshold:1e-4,zero_count:0} st@1520430000.123
```
-##### Histogram with both Classic and Native Buckets
+#### Histogram with both Classic and Native Buckets
If a Histogram MetricPoint has both Classic and Native buckets, the Sample for the Native Buckets MUST come first.
@@ -1044,7 +1042,7 @@ acme_http_request_seconds{path="/api/v1",method="GET"} {count:2,sum:1.2e2,schema
acme_http_request_seconds{path="/api/v1",method="GET"} {count:2,sum:1.2e2,bucket:[0.5:1,1:2,+Inf:2]}
```
-###### Exemplars
+##### Exemplars
Exemplars without Labels MUST represent an empty LabelSet as {}.
@@ -1058,7 +1056,7 @@ foo {count:17,sum:324789.3,schema:0,zero_threshold:1e-4,zero_count:0,positive_sp
foo {count:17,sum:324789.3,bucket:[0.01:0,0.1:8,1.0:11,10.0:17,+Inf:17]} st@1520430000.123 # {} 0.054 1520879607.7 # {trace_id="KOO5S4vxi0o"} 0.67 1520879602.890 # {trace_id="oHg5SJYRHA0"} 9.8 1520879607.789
```
-##### GaugeHistogram with Classic Buckets
+#### GaugeHistogram with Classic Buckets
The MetricPoint's value MUST be a CompositeValue.
@@ -1073,7 +1071,7 @@ An example of a Metric with no labels, and one MetricPoint value with no Exempla
foo {count:42,sum:3289.3,bucket:[0.01:20,0.1:25,1:34,+Inf:42]}
```
-##### GaugeHistogram with Native Buckets
+#### GaugeHistogram with Native Buckets
GaugeHistogram MetricPoints with Native Buckets follow the same syntax as Histogram MetricPoints with Native Buckets.
@@ -1082,13 +1080,13 @@ GaugeHistogram MetricPoints with Native Buckets follow the same syntax as Histog
acme_http_request_seconds{path="/api/v1",method="GET"} {count:59,sum:1.2e2,schema:7,zero_threshold:1e-4,zero_count:0,negative_spans:[1:2],negative_buckets:[5,7],positive_spans:[-1:2,3:4],positive_buckets:[5,7,10,9,8,8]} st@1520430000.123
```
-##### GaugeHistogram with both Classic and Native buckets
+#### GaugeHistogram with both Classic and Native buckets
If a GaugeHistogram MetricPoint has both Classic and Native buckets, the Sample for the Native Buckets MUST come first.
The order ensures that implementations can easily skip the Classic Buckets if the Native Buckets are preferred.
-##### Unknown
+#### Unknown
The sample metric name for the value of the MetricPoint for a MetricFamily of type Unknown MUST NOT have a suffix.
@@ -1099,32 +1097,6 @@ An example with a Metric with no labels and a MetricPoint with no timestamp:
foo 42.23
```
-### Protobuf format
-
-#### Overall Structure
-
-Protobuf messages MUST be encoded in binary and MUST have `application/openmetrics-protobuf; version=1.0.0` as their content type.
-
-All payloads MUST be a single binary encoded MetricSet message, as defined by the OpenMetrics protobuf schema.
-
-##### Version
-
-The protobuf format MUST follow the proto3 version of the protocol buffer language.
-
-##### Strings
-
-All string fields MUST be UTF-8 encoded.
-
-##### Timestamps
-
-Timestamp representations in the OpenMetrics protobuf schema MUST follow the published google.protobuf.Timestamp [timestamp] message. The timestamp message MUST be in Unix epoch seconds as an int64 and a non-negative fraction of a second at nanosecond resolution as an int32 that counts forward from the seconds timestamp component. It MUST be within 0 to 999,999,999 inclusive.
-
-#### Protobuf schema
-
-Protobuf schema is currently available [here](https://github.com/prometheus/OpenMetrics/blob/3bb328ab04d26b25ac548d851619f90d15090e5d/proto/openmetrics_data_model.proto).
-
-> NOTE: Prometheus and ecosystem does not support OpenMetrics protobuf schema, instead it uses similar `io.prometheus.client` [format](https://github.com/prometheus/client_model/blob/master/io/prometheus/client/metrics.proto). Discussions about the future of the protobuf schema in OpenMetrics 2.0 [are in progress](https://github.com/prometheus/OpenMetrics/issues/296).
-
## Design Considerations
### Scope
@@ -1459,11 +1431,7 @@ The port assigned by IANA for clients exposing data is <9099 requested for histo
If more than one metric endpoint needs to be reachable at a common IP address and port, operators might consider using a reverse proxy that communicates with exposers over localhost addresses. To ease multiplexing, endpoints SHOULD carry their own name in their path, i.e. `/node_exporter/metrics`. Expositions SHOULD NOT be combined into one exposition, for the reasons covered under "Supporting target metadata in both push-based and pull-based systems" and to allow for independent ingestion without a single point of failure.
-OpenMetrics would like to register two MIME types, `application/openmetrics-text` and `application/openmetrics-proto`.
-
-
+OpenMetrics would like to register the MIME type `application/openmetrics-text`