Skip to content

Update OM1.1 for UTF-8 metric names and labels #2746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update OM1.1 for UTF-8 metric names and labels #2746

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
908e3a6
feat(om1.1): Add UTF-8 metric names and labels
ywwg Oct 2, 2025
0206e9b
tweak name sections
ywwg Oct 2, 2025
0b25d06
note
ywwg Oct 3, 2025
8564f6d
notes
ywwg Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 21 additions & 13 deletions docs/specs/om/open_metrics_spec_1_1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ author:
name: Rob Skillington
organization: Chronosphere
email: [email protected]
- ins: O. Williams
name: Owen Williams
organization: Grafana Labs
email: [email protected]
---

- Version: 1.1
Expand Down Expand Up @@ -56,7 +60,7 @@ Common examples of metric time series would be network interface counters, devic

## Data Model

This section MUST be read together with the ABNF section. In case of disagreements between the two, the ABNF's restrictions MUST take precedence. This reduces repetition as the text wire format MUST be supported.
This section MUST be read together with the ABNF section. In case of disagreements between the two, the ABNF's restrictions MUST take precedence. This reduces repetition as the text wire format MUST be supported.

### Data Types

Expand All @@ -80,7 +84,7 @@ Strings MUST only consist of valid UTF-8 characters and MAY be zero length. NULL

Labels are key-value pairs consisting of strings.

Label names beginning with underscores are RESERVED and MUST NOT be used unless specified by this standard. Label names MUST follow the restrictions in the ABNF section.
Label names beginning with two underscores are RESERVED and MUST NOT be used unless specified by this standard. Label names SHOULD follow the restrictions in the ABNF section under the `label-name` section. Label names MAY be any quoted escaped UTF-8 string as described in the ABNF section. Be aware that exposing UTF-8 metrics is still experimental and may reduce usability.

Empty label values SHOULD be treated as if the label was not present.

Expand Down Expand Up @@ -116,7 +120,7 @@ A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, H

##### Name

MetricFamily names are a string and MUST be unique within a MetricSet. Names SHOULD be in snake_case. Metric names MUST follow the restrictions in the ABNF section.
MetricFamily names are a string and MUST be unique within a MetricSet. Names SHOULD be in snake_case. Names SHOULD follow the restrictions in the ABNF section under `metricname`. Metric names MAY be any quoted and escaped UTF-8 string as described in the ABNF section. Be aware that exposing UTF-8 metrics is still experimental and may reduce usability, especially when suffixes are not included.

Colons in MetricFamily names are RESERVED to signal that the MetricFamily is the result of a calculation or aggregation of a general purpose monitoring system.

Expand Down Expand Up @@ -312,22 +316,24 @@ metricset = *metricfamily

metricfamily = *metric-descriptor *metric

metric-descriptor = HASH SP type SP metricname SP metric-type LF
metric-descriptor =/ HASH SP help SP metricname SP escaped-string LF
metric-descriptor =/ HASH SP unit SP metricname SP *metricname-char LF
metric-descriptor = HASH SP type SP (metricname / metricname-utf8) SP metric-type LF
metric-descriptor =/ HASH SP help SP (metricname / metricname-utf8) SP escaped-string LF
metric-descriptor =/ HASH SP unit SP (metricname / metricname-utf8) SP *metricname-char LF

metric = *sample

metric-type = counter / gauge / histogram / gaugehistogram / stateset
metric-type =/ info / summary / unknown

sample = metricname [labels] SP number [SP timestamp] [exemplar] LF
sample = metricname-and-labels SP number [SP timestamp] [exemplar] LF

exemplar = SP HASH SP labels SP number [SP timestamp]
metricname-and-labels = metricname [labels-in-braces] / name-in-braces
labels-in-braces = "{" [label *(COMMA label)] "}"
name-in-braces = "{" metricname-utf8 *(COMMA label) "}"

labels = "{" [label *(COMMA label)] "}"
label = label-key EQ DQUOTE escaped-string DQUOTE

label = label-name EQ DQUOTE escaped-string DQUOTE
exemplar = SP HASH SP labels-in-braces SP number [SP timestamp]

number = realnumber
; Case insensitive
Expand Down Expand Up @@ -366,16 +372,16 @@ HASH = "#"
SIGN = "-" / "+"

metricname = metricname-initial-char 0*metricname-char

metricname-char = metricname-initial-char / DIGIT
metricname-initial-char = ALPHA / "_" / ":"
metricname-utf8 = DQUOTE escaped-string DQUOTE

label-key = label-name / DQUOTE escaped-string DQUOTE
label-name = label-name-initial-char *label-name-char

label-name-char = label-name-initial-char / DIGIT
label-name-initial-char = ALPHA / "_"

escaped-string = *escaped-char
escaped-string = 1*escaped-char

escaped-char = normal-char
escaped-char =/ BS ("n" / DQUOTE / BS)
Expand Down Expand Up @@ -430,6 +436,8 @@ A double backslash SHOULD be used to represent a backslash character.
A single backslash SHOULD NOT be used for undefined escape sequences.
As an example, `\\\\a` is equivalent and preferable to `\\a`.

Escaping MUST also be applied to quoted UTF-8 strings.

##### Numbers

Integer numbers MUST NOT have a decimal point. Examples are `23`, `0042`, and `1341298465647914`.
Expand Down