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** |