From 498aa999f74762775d055a1149d9acf8d512258a Mon Sep 17 00:00:00 2001 From: Owen Williams Date: Tue, 16 Dec 2025 14:11:53 -0500 Subject: [PATCH 1/3] docs(instrumenting): Update exposition_formats.md to include quoting syntax Signed-off-by: Owen Williams --- docs/instrumenting/exposition_formats.md | 61 ++++++++++++++++-------- 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md index 4084e5744..eafaa7fa7 100644 --- a/docs/instrumenting/exposition_formats.md +++ b/docs/instrumenting/exposition_formats.md @@ -17,17 +17,17 @@ format. ### Basic info -| Aspect | Description | -|--------|-------------| -| **Inception** | April 2014 | -| **Supported in** | Prometheus version `>=0.4.0` | -| **Transmission** | HTTP | -| **Encoding** | UTF-8, `\n` line endings | -| **HTTP `Content-Type`** | `text/plain; version=0.0.4` (A missing `version` value will lead to a fall-back to the most recent text format version.) | -| **Optional HTTP `Content-Encoding`** | `gzip` | -| **Advantages** | | -| **Limitations** | | -| **Supported metric primitives** | | +| Aspect | Description | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Inception** | April 2014 | +| **Supported in** | Prometheus version `>=0.4.0` | +| **Transmission** | HTTP | +| **Encoding** | UTF-8, `\n` line endings | +| **HTTP `Content-Type`** | `text/plain; version=0.0.4` (A missing `version` value will lead to a fall-back to the most recent text format version.) | +| **Optional HTTP `Content-Encoding`** | `gzip` | +| **Advantages** | | +| **Limitations** | | +| **Supported metric primitives** | | ### Text format details @@ -54,24 +54,42 @@ line may exist for any given metric name. If the token is `TYPE`, exactly two more tokens are expected. The first is the metric name, and the second is either `counter`, `gauge`, `histogram`, -`summary`, or `untyped`, defining the type for the metric of that name. Only -one `TYPE` line may exist for a given metric name. The `TYPE` line for a -metric name must appear before the first sample is reported for that metric -name. If there is no `TYPE` line for a metric name, the type is set to -`untyped`. +`summary`, or `untyped`, defining the type for the metric of that name. Only one +`TYPE` line may exist for a given metric name. The `TYPE` line for a metric name +must appear before the first sample is reported for that metric name. If there +is no `TYPE` line for a metric name, the type is set to `untyped`. Metric names +not corresponding to the legacy Prometheus metric name character set must be +quoted and escaped. The remaining lines describe samples (one per line) using the following syntax ([EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form)): ``` -metric_name [ - "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}" -] value [ timestamp ] +metric_name_or_labels value [ timestamp ] + +metric_name_or_labels = metric_name [ "{" labels "}" ] | "{" quoted_metric_name [ "," labels ] "}" + +metric_name = identifier + +quoted_metric_name = `"` escaped_string `"` + +labels = [ label_pairs ] + +label_pairs = label_pair { "," label_pair } [ "," ] + +label_pair = label_name "=" `"` escaped_string `"` + +label_name = identifier | `"` escaped_string `"` + +escaped_string = (any UTF-8 characters, but backslash, double-quote, and line feed must be escaped) ``` In the sample syntax: -* `metric_name` and `label_name` carry the usual Prometheus expression language restrictions. +* `identifier` carries the usual Prometheus expression language restrictions. +* When `metric_name` is quoted with double quotes, it appears inside the braces instead of outside. +* `label_name` may be optionally enclosed in double quotes. +* Metric and label names not corresponding to the usual Prometheus expression language restrictions must use the quoted syntaxes. * `label_value` can be any sequence of UTF-8 characters, but the backslash (`\`), double-quote (`"`), and line feed (`\n`) characters have to be escaped as `\\`, `\"`, and `\n`, respectively. * `value` is a float represented as required by Go's [`ParseFloat()`](https://golang.org/pkg/strconv/#ParseFloat) function. In addition to standard numerical values, `NaN`, `+Inf`, and `-Inf` are valid values representing not a number, positive infinity, and negative infinity, respectively. * The `timestamp` is an `int64` (milliseconds since epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds), represented as required by Go's [`ParseInt()`](https://golang.org/pkg/strconv/#ParseInt) function. @@ -113,6 +131,9 @@ http_requests_total{method="post",code="400"} 3 1395066363000 # Escaping in label values: msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9 +# UTF-8 metric and label names: +{"my.dotted.metric", "error.message"="Not Found"} + # Minimalistic line: metric_without_timestamp_and_labels 12.47 From b29658c76ee6af134c66f7fc954181484eec5fce Mon Sep 17 00:00:00 2001 From: Owen Williams Date: Tue, 16 Dec 2025 14:14:32 -0500 Subject: [PATCH 2/3] revert reformat Signed-off-by: Owen Williams --- docs/instrumenting/exposition_formats.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md index eafaa7fa7..fd9583fae 100644 --- a/docs/instrumenting/exposition_formats.md +++ b/docs/instrumenting/exposition_formats.md @@ -17,17 +17,17 @@ format. ### Basic info -| Aspect | Description | -| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Inception** | April 2014 | -| **Supported in** | Prometheus version `>=0.4.0` | -| **Transmission** | HTTP | -| **Encoding** | UTF-8, `\n` line endings | -| **HTTP `Content-Type`** | `text/plain; version=0.0.4` (A missing `version` value will lead to a fall-back to the most recent text format version.) | -| **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 type hints and docstrings)
| -| **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
| +| Aspect | Description | +|--------|-------------| +| **Inception** | April 2014 | +| **Supported in** | Prometheus version `>=0.4.0` | +| **Transmission** | HTTP | +| **Encoding** | UTF-8, `\n` line endings | +| **HTTP `Content-Type`** | `text/plain; version=0.0.4` (A missing `version` value will lead to a fall-back to the most recent text format version.) | +| **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 type hints and docstrings)
| +| **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
| ### Text format details From 19c97adb760cddd4c0c4e5a216b31210a5ff1786 Mon Sep 17 00:00:00 2001 From: Owen Williams Date: Wed, 17 Dec 2025 09:03:04 -0500 Subject: [PATCH 3/3] note Signed-off-by: Owen Williams --- docs/instrumenting/exposition_formats.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md index fd9583fae..39e7f09c3 100644 --- a/docs/instrumenting/exposition_formats.md +++ b/docs/instrumenting/exposition_formats.md @@ -80,13 +80,12 @@ label_pairs = label_pair { "," label_pair } [ "," ] label_pair = label_name "=" `"` escaped_string `"` label_name = identifier | `"` escaped_string `"` - -escaped_string = (any UTF-8 characters, but backslash, double-quote, and line feed must be escaped) ``` In the sample syntax: * `identifier` carries the usual Prometheus expression language restrictions. +* `escaped_string` consists of any UTF-8 characters, but backslash, double-quote, and line feed must be escaped. * When `metric_name` is quoted with double quotes, it appears inside the braces instead of outside. * `label_name` may be optionally enclosed in double quotes. * Metric and label names not corresponding to the usual Prometheus expression language restrictions must use the quoted syntaxes.