From 9ba90e211fc8a9e297ddc365c018b46033054c72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gy=C3=B6rgy=20Krajcsovits?= Date: Thu, 12 Nov 2026 08:41:02 +0100 Subject: [PATCH] docs(exposition): document Prometheus text format 1.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prometheus has requested `text/plain;version=1.0.0` (the PrometheusText1.0.0 scrape protocol) since 3.0, and prometheus/common now negotiates, encodes and decodes it, but the exposition formats page only described version 0.0.4. Add a Versions section describing both versions, and update the Basic info table. Version 1.0.0 is the same format with quoted UTF-8 metric and label names plus the `escaping` parameter. Note that Prometheus ignores the version when parsing, so it also ingests UTF-8 names sent as 0.0.4, which is not part of that format. Co-Authored-By: Claude Signed-off-by: György Krajcsovits --- docs/instrumenting/exposition_formats.md | 38 ++++++++++++++++++++---- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md index 525acb68e..071976f43 100644 --- a/docs/instrumenting/exposition_formats.md +++ b/docs/instrumenting/exposition_formats.md @@ -13,24 +13,50 @@ 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](#details) of the -format. +In this section you can find the [versions](#versions) of this format, some +[basic information](#basic-info) about it as well as a more +[detailed breakdown](#details) of the format. + +### Versions + +The version of the text format is carried in the `version` parameter of the +HTTP `Content-Type` header: + +* `0.0.4`: The original version. Metric and label names are limited to the + [legacy character set](../concepts/data_model.md#metric-names-and-labels). + A missing `version` is treated as `0.0.4`. +* `1.0.0`: The same format as `0.0.4`, extended with + [quoted metric and label names](#comments-help-text-and-type-information), so + that names outside of the legacy character set can be exposed unescaped. It + also adds the `escaping` parameter, which negotiates how such names are + escaped (see [escaping schemes](./escaping_schemes.md) and + [content negotiation](./content_negotiation.md)). Prometheus requests this + version as the `PrometheusText1.0.0` scrape protocol since version 3.0. + +Targets that expose UTF-8 names should respond with `version=1.0.0`. If the +scraper only accepts `0.0.4`, or requests an `escaping` scheme other than +`allow-utf-8`, the target must escape names using the requested scheme +(`underscores` by default). + +Prometheus itself does not check the `version` parameter when parsing the text +format, so it also ingests quoted UTF-8 names from a response that declares +`version=0.0.4` or no version. This is not part of the `0.0.4` format and other +consumers may reject such a response. ### Basic info | Aspect | Description | |--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Inception** | April 2014 | -| **Supported in** | Prometheus version `>=0.4.0` | +| **Supported in** |
  • `version=0.0.4`: Prometheus version `>=0.4.0`
  • `version=1.0.0`: Prometheus version `>=3.0.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.) | +| **HTTP `Content-Type`** | `text/plain` with parameters:
    • `version=0.0.4` or `1.0.0` (a missing `version` value is treated as `0.0.4`)
    • `escaping=` (`1.0.0` only)
    | | **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** | | +| **Supported advanced features** |
    • UTF-8 metric names and label names (`version=1.0.0`)
    | ### Details