prometheus/docs
1
0
Fork 0
mirror of https://github.com/prometheus/docs.git synced 2026-02-05 06:45:01 +01:00
Code Issues Releases Activity

docs(instrumenting): Update exposition_formats.md to include quoting syntax (#2800)

Browse Source 
Signed-off-by: Owen Williams <owen.williams@grafana.com>
This commit is contained in:
Owen Williams
2026-01-06 14:31:35 -05:00
committed by GitHub
parent 0cdf2d2437
commit cbea98f4e9
1 changed files with 29 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/instrumenting/exposition_formats.md
View File

@@ -54,24 +54,41 @@ 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 `"`
```
In the sample syntax:
* `metric_name` and `label_name` carry the usual Prometheus expression language restrictions.
* `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.
* `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 +130,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