Scrape protocol content negotiation

Abstract

This document specifies the protocol negotiation mechanism used by Prometheus when scraping metrics from targets. It defines the Accept header format, supported Content Types, and the negotiation process for determining the best available format for metric exposition.

Introduction

Prometheus supports multiple formats for scraping metrics, including both text-based and binary protobuf formats. Based on the value of the Accept header, the target will pick the best available Content Type for its reply.

Protocol Types

Supported Protocols

The following protocols are supported by Prometheus:

1. PrometheusProto - Binary protobuf format
2. PrometheusText0.0.4 - Prometheus text format version 0.0.4
3. PrometheusText1.0.0 - Prometheus text format version 1.0.0
4. OpenMetricsText0.0.1 - OpenMetrics text format version 0.0.1
5. OpenMetricsText1.0.0 - OpenMetrics text format version 1.0.0

Protocol Headers

Each protocol MUST be associated with a specific MIME type and version:

Protocol	MIME Type	Parameters
PrometheusProto	application/vnd.google.protobuf	proto=io.prometheus.client.MetricFamily;encoding=delimited
PrometheusText0.0.4	text/plain	version=0.0.4
PrometheusText1.0.0	text/plain	version=1.0.0
OpenMetricsText0.0.1	application/openmetrics-text	version=0.0.1
OpenMetricsText1.0.0	application/openmetrics-text	version=1.0.0

Accept Header Construction

The Accept header is constructed by Prometheus to indicate what formats it supports.

Basic Format

The Accept header MUST be constructed as follows:

1. For each protocol supported by the target:
   • The protocol's MIME type and parameters MUST be specified.
   • For protobuf protocols, an encoding of "delimited" MUST be specified.
   • For PrometheusText1.0.0 and OpenMetricsText1.0.0, the escaping scheme parameter SHOULD be appended.
   • A quality value (q) parameter SHOULD be appended.
2. A catch-all */* with the lowest quality value SHOULD be appended.

Quality Values

Quality values SHOULD be assigned in descending order based on the protocol's position in the Accept header:

• First protocol: q=0.{n+1}
• Second protocol: q=0.{n}
• And so on, where n is the number of supported protocols

Escaping Scheme

For PrometheusText1.0.0 and OpenMetricsText1.0.0 protocols, the Accept header SHOULD include an escaping scheme parameter: escaping=<scheme>

Where <scheme> MUST be one of:

• allow-utf-8
• underscores
• dots
• values

See Escaping Schemes spec for details on how the escaping schemes function.

Compression

The Accept-Encoding header SHOULD be set to:

• gzip if compression is enabled
• identity if compression is disabled

Selection of Format