Skip to content

docs: clarify suffix-handling behavior after #1955 #2097

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

Closed
ADITYA-CODE-SOURCE wants to merge 1 commit into from
Closed

docs: clarify suffix-handling behavior after #1955 #2097

Show file tree
Hide file tree
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
18 changes: 18 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,24 @@
> As part of the OM2 work, metric-name suffix handling moved from metric creation time to scrape
> time. A positive side effect is that metric names are now more flexible across the board, for
> example names ending in suffixes like `_total` are accepted where they were previously rejected.
> This is not just an internal model change and not just an OM2 change: it also affects
> user-visible exposition in OM1, OpenMetrics, and protobuf for some arbitrary metric names ending
> in suffix-like strings such as `.created`, `.total`, `.info`, or `.bucket`.
>
> For real counter and info semantics, the exposed names are mostly preserved:
>
> | Example | Before 1.6.0 | Since 1.6.0 |
> | --- | --- | --- |
> | `Counter("events")` | `events_total` | `events_total` |
> | `Counter("events_total")` | `events_total` | `events_total` |
>
> For arbitrary names ending in suffix-like strings, the exposed output may change:
>
> | Example | Before 1.6.0 | Since 1.6.0 |
> | --- | --- | --- |
> | `Gauge("test3.created")` | `test3` | `test3_created` |
> | `Gauge("test6.total")` | `test6` | `test6_total` |
>
> To keep the Prometheus and OM1 output unambiguous, the registry tracks claimed exposition names
> and still rejects registrations that would collide at scrape time.
>
Expand Down
14 changes: 14 additions & 0 deletions docs/content/getting-started/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,20 @@ Counter eventsTotal2 = Counter.builder()
Suffix handling happens at scrape time. This makes metric names more flexible while keeping the
exposed output unambiguous.

This is not just an internal validation change and not just an OpenMetrics 2.0 change. It also
affects user-visible exposition in Prometheus-facing formats for some arbitrary metric names ending
in suffix-like strings.

For real counter and info semantics, the exposed names are mostly preserved. For arbitrary metric
names ending in suffix-like strings, the exposed output may change.

| Metric builder input | Before 1.6.0 | Since 1.6.0 |
| ------------------------- | ------------ | ----------- |
| `Counter("events")` | `events_total` | `events_total` |
| `Counter("events_total")` | `events_total` | `events_total` |
| `Gauge("test3.created")` | `test3` | `test3_created` |
| `Gauge("test6.total")` | `test6` | `test6_total` |

The registry now tracks not only the metric names you register, but also the exposition names they
would claim in OpenMetrics 1.x and Prometheus text format, such as `_total`, `_count`, `_sum`,
`_bucket`, `_created`, and `_info`.
Expand Down