From 746b143345433676cc0b75aaa72efe7040e6644d Mon Sep 17 00:00:00 2001 From: ADITYA-CODE-SOURCE Date: Tue, 5 May 2026 09:30:58 +0530 Subject: [PATCH] docs: clarify suffix-handling behavior after #1955 Signed-off-by: ADITYA-CODE-SOURCE --- CHANGELOG.md | 18 ++++++++++++++++++ docs/content/getting-started/registry.md | 14 ++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 72012dcc8..9435583af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. > diff --git a/docs/content/getting-started/registry.md b/docs/content/getting-started/registry.md index 45383d72a..c70cadb60 100644 --- a/docs/content/getting-started/registry.md +++ b/docs/content/getting-started/registry.md @@ -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`.