Prometheus logo

Prometheus

DocsDownloadCommunitySupport & TrainingBlog

Ctrl + K

GitHub Logo

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 be 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:

ProtocolMIME TypeParameters
PrometheusProtoapplication/vnd.google.protobufproto=io.prometheus.client.MetricFamily;encoding=delimited
PrometheusText0.0.4text/plainversion=0.0.4
PrometheusText1.0.0text/plainversion=1.0.0
OpenMetricsText0.0.1application/openmetrics-textversion=0.0.1
OpenMetricsText1.0.0application/openmetrics-textversion=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-utf8
  • 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

The scrape target SHOULD use the following process to select an appropriate Content-Type based on the list of protocols in the Accept header generated by Prometheus:

  1. It MUST use the protocol in the Accept header with the highest weighting that is supported by Prometheus.
  2. If no protocols are supported, the target MAY use a user-configured fallback scrape protocol.
  3. If no fallback is specified, the target MUST use PrometheusText0.0.4 as a last resort.

Content-Type Response

Targets SHOULD respond with a Content-Type header that matches one of the accepted formats. The Content-Type header MUST include:

  1. The appropriate MIME type.
  2. The version parameter.
  3. For text formats version 1.0.0 and above, the escaping scheme parameter.

Security Considerations

  1. Targets MUST validate the Accept header to prevent potential injection attacks
  2. The escaping scheme parameter MUST be validated to prevent protocol confusion
  3. Content-Type headers MUST be properly sanitized to prevent MIME type confusion

Examples

Default Accept Header

Accept: application/openmetrics-text;version=1.0.0;escaping=allow-utf8;q=0.5,application/openmetrics-text;version=0.0.1;q=0.4,text/plain;version=1.0.0;escaping=allow-utf8;q=0.3,text/plain;version=0.0.4;q=0.2,/;q=0.1

Protobuf-First Accept Header

Accept: application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited;q=0.5,application/
openmetrics-text;version=1.0.0;escaping=allow-utf8;q=0.4,application/openmetrics-text;version=0.0.1;q=0.3,text/plain;version=1.0.0;escaping=allow-utf8;q=0.2,text/plain;version=0.0.4;q=0.1,/;q=0.0

On this page