diff --git a/docs/instrumenting/exposition_formats.md b/docs/instrumenting/exposition_formats.md index 4084e5744..39e7f09c3 100644 --- a/docs/instrumenting/exposition_formats.md +++ b/docs/instrumenting/exposition_formats.md @@ -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