Skip to content

feat(om2): relax the acceptance rules around unit and total suffixes #2714

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat(om2): relax the acceptance rules around unit and total suffixes #2714

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 9 additions & 1 deletion docs/specs/om/open_metrics_spec_2_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,8 @@ A MetricFamily MAY have zero or more Metrics. A MetricFamily MUST have a name, H

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.

Ingestors MAY accept duplicate MetricFamily names, provided that there is a mechanism to distinguish the resulting MetricPoints.

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.

MetricFamily names beginning with underscores are RESERVED and MUST NOT be used unless specified by this standard.
Expand All @@ -126,6 +128,8 @@ MetricFamily names beginning with underscores are RESERVED and MUST NOT be used

The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_total" as a counter called "foo" could create a "foo_total" in the text format.

Ingestors MAY accept conflicting MetricFamily names, provided that there is a mechanism to distinguish the resulting MetricPoints. It follows that ingestors MAY accept MetricFamily name without the type specific suffix.

Exposers SHOULD avoid names that could be confused with the suffixes that text format sample metric names use.

* Suffixes for the respective types are:
Expand All @@ -146,6 +150,8 @@ Type specifies the MetricFamily type. Valid values are "unknown", "gauge", "coun

Unit specifies MetricFamily units. If non-empty, it MUST be a suffix of the MetricFamily name separated by an underscore. Be aware that further generation rules might make it an infix in the text format.

Ingestors MAY accept MetricFamily name without unit suffix.

##### Help

Help is a string and SHOULD be non-empty. It is used to give a brief description of the MetricFamily for human consumption and SHOULD be short enough to be used as a tooltip.
Expand Down Expand Up @@ -492,7 +498,7 @@ A valid example for a foo_seconds metric with a unit of "seconds":
# UNIT foo_seconds seconds
```

An invalid example, where the unit is not a suffix on the name:
An invalid example (which MAY still be accepted by ingestors), where the unit is not a suffix on the name:

```
# TYPE foo counter
Expand Down Expand Up @@ -639,6 +645,8 @@ foo 18.0 456

The MetricPoint's Total Value Sample MetricName MUST have the suffix `_total`. If present, the MetricPoint's Created Timestamp MUST be inlined with the Metric point with a `ct@` prefix. If the value's timestamp is present, the Created Timestamp MUST be added right after it. If exemplar is present, the Created Timestamp MUST be added before it.

Ingestors MAY accept MetricPoint Total Value name without the `_total` suffix.

An example with a Metric with no labels, and a MetricPoint with no timestamp and no Created Timestamp:

```openmetrics-add-eof
Expand Down