SPEC: clarify what output format we require for /metrics

[donbourne]

We need to decide whether we expect compliant implementations to export metrics in Prometheus format or OpenMetrics format.

The MP metrics spec, as currently written, says that it supports OpenMetrics text format, but in reality it supports Prometheus format (the Prometheus and OpenMetrics formats have diverged somewhat since the previous MP Metrics spec was written)

Micrometer's PrometheusMeterRegistry supports collecting scrapes in either Prometheus or OpenMetrics format (though at the moment the Units line and _created line found in OpenMetrics format are not supported), so it would be relatively easy for Micrometer-based implementations to accomodate exporting metrics in either format.

OpenTelemetry is discussing accepting and producing metrics in the OpenMetrics format (see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/openmetrics-guidelines.md), but also mentions it needs to interoperate with the Prometheus format.

I suggest we adopt the same approach here as is described in the OpenTelemetry spec (https://opentelemetry.io/docs/reference/specification/metrics/sdk_exporters/prometheus/) which says...

• A Prometheus Exporter is a Pull Metric Exporter which reports metrics by responding to the Prometheus scraper requests.

• A Prometheus Exporter MUST support Pull mode.

• A Prometheus Exporter MUST NOT support Push mode.

• A Prometheus Exporter MUST only support Cumulative Temporality.

• A Prometheus Exporter MUST support version 0.0.4 of the Text-based format.

• A Prometheus Exporter MAY support OpenMetrics Text Format, including the Exemplars.

[donbourne]

original thought on this was that we would require implementations to support Prometheus format text output from /metrics, but that they may also support OpenMetrics format... but that raises the question -- how would an implementation be expected to allow the choice between the two formats when making a call to /metrics?

[tjquinno]

Transcribed from gitter...

I see at least two use cases:

• an administrator wants to set up which format the service uses by default (sounds like a config setting), and
• a client wants to request a specific format.

There seems to be no official IANA media type for either Prometheus or OpenMetrics. That said, this issue OpenObservability/OpenMetrics#79 shows that OpenMetrics folks pondered this question and there's a related PR that adopted a particular name but I don't see the name in the IANA mime types catalog so it's hard to know what to make of that.

Yet, there is evidence (code) that application/openmetrics-text; version=1.0.0; charset=utf-8 is in use, at least in some places. (e.g., spring-projects/spring-boot#28130). This uses the media type proposed in the OpenMetrics issue linked above.

So, even though that is not an official cataloged media type according to IANA there does seem to be some use of it in the wild. We could consider Accept as a way for clients to request what they want when accessing /metrics. Off the cuff, I would guess that Accept: text/plain would request Prometheus format, whereas Accept: application/openmetrics-text would request Prometheus format.

Failing that, there's always a query parameter such as ?format=openmetrics or ?format=prometheus.

[donbourne]

I see also at https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#iana-considerations-iana the following:

EDITOR’S NOTE: application/openmetrics-text is in active use since 2018, application/openmetrics-proto is not yet in active use.