Title: Move suffix handling from creation time to scrape time (current release) · Issue #1941 · prometheus/client_java · GitHub
Open Graph Title: Move suffix handling from creation time to scrape time (current release) · Issue #1941 · prometheus/client_java
X Title: Move suffix handling from creation time to scrape time (current release) · Issue #1941 · prometheus/client_java
Description: Part of #1942 (full design rationale). Summary Today, Counter.Builder strips _total and PrometheusNaming rejects names ending with _total/_info at creation time. Then at exposition time, the format writers append _total back. This confli...
Open Graph Description: Part of #1942 (full design rationale). Summary Today, Counter.Builder strips _total and PrometheusNaming rejects names ending with _total/_info at creation time. Then at exposition time, the format...
X Description: Part of #1942 (full design rationale). Summary Today, Counter.Builder strips _total and PrometheusNaming rejects names ending with _total/_info at creation time. Then at exposition time, the format...
Opengraph URL: https://github.com/prometheus/client_java/issues/1941
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Move suffix handling from creation time to scrape time (current release)","articleBody":"\nPart of #1942 (full design rationale).\n\n## Summary\n\nToday, `Counter.Builder` strips `_total` and\n`PrometheusNaming` rejects names ending with `_total`/`_info`\nat creation time. Then at exposition time, the format writers\nappend `_total` back. This conflicts with OM2's principle\nthat metric names should not be modified.\n\nThe fix: stop rejecting these suffixes, and let each format\nwriter own its suffix conventions at scrape time.\n\n## Key table\n\nFormat writers adapt at scrape time.\n\n| User provides | OM1 | OTel | OTel preserve |\n|---|---|---|---|\n| `Counter(\"events\")` | `events_total` | `events` | `events` |\n| `Counter(\"events_total\")` | `events_total` | `events` | `events_total` |\n| `Counter(\"req_bytes\").unit(BYTES)` | `req_bytes_total` | name `req`, unit `By` | name `req_bytes`, unit `By` |\n| `Counter(\"req\").unit(BYTES)` | `req_bytes_total` | name `req`, unit `By` | name `req`, unit `By` |\n| `Gauge(\"connections\")` | `connections` | `connections` | `connections` |\n| `Gauge(\"events_total\")` | `events_total` | `events_total` | `events_total` |\n\n- Rows 1+2 cannot coexist — the registry detects the\n collision and rejects the second registration.\n- OTel strips `_total` from **Counters** only (type-aware).\n Gauges keep `_total`.\n- OTel preserve = name as provided.\n\n## Design decisions\n\n### `getPrometheusName()` stays unchanged\n\n`Counter.builder().name()` and `Info.builder().name()`\ncontinue to strip `_total`/`_info` so that\n`getPrometheusName()` returns the base name. This avoids a\npublic API break.\n\nThe original (unstripped) name is stored separately and used\nby format writers for smart-append logic.\n\n### Two-layer collision detection\n\n- **Primary key**: `prometheusName` (the stripped base name,\n same as today). `Counter(\"events\")` and\n `Counter(\"events_total\")` both map to `events`.\n- **Secondary index**: set of all OM1 names a metric would\n produce. When registering, check for intersection with\n already-reserved names. This catches cross-type collisions\n like `Gauge(\"events_total\")` + `Counter(\"events\")` which\n both produce `events_total` in OM1.\n\nThis is necessary because removing `_total`/`_info` from\nreserved suffixes allows `Gauge(\"events_total\")` for the\nfirst time. Without the secondary index, the cross-type\ncollision would go undetected.\n\n### `sanitizeMetricName` follows naturally\n\n`sanitizeMetricName()` strips whatever is in\n`RESERVED_METRIC_NAME_SUFFIXES`. Once all reserved suffixes\nare removed from that list, it stops stripping them\nautomatically. The contract (\"returns a name that passes\n`validateMetricName`\") is unchanged.\n\n## What to change\n\n### 1. Collision detection in `PrometheusRegistry`\n\nWhen registering a metric, compute the OM1 names it would\nproduce. Reject if any collide with an already-registered\nmetric's OM1 names.\n\nThis replaces today's blanket rejection of `_total` names\nwith precise collision checks:\n- `Gauge(\"foo_total\")` + `Histogram(\"foo\")` -> **no\n collision** (OM1: `foo_total` vs\n `foo_count`/`foo_sum`/`foo_bucket`). Fixes #1321.\n- `Gauge(\"foo_total\")` + `Counter(\"foo\")` -> **collision**\n in OM1 (`foo_total` vs `foo_total`). Correctly rejected.\n- `Gauge(\"foo_count\")` + `Histogram(\"foo\")` -> **collision**\n in OM1. Fixes the known gap documented in\n `PrometheusNaming`.\n\nOM1 suffixes to check: `_total` (Counter), `_info` (Info),\n`_bucket`/`_count`/`_sum` (Histogram/Summary), `_created`\n(Counter/Histogram/Summary).\n\n### 2. Smart-append in OM1/protobuf writers\n\nChange `_total` appending from \"always append\" to \"append\nonly if not already present.\" Same for `_info`.\n\n### 3. Remove reserved suffixes + store original name\n\n- Remove all entries from `RESERVED_METRIC_NAME_SUFFIXES`\n in `PrometheusNaming`\n- `validateMetricName()` stops rejecting these suffixes\n- `sanitizeMetricName()` stops stripping them\n (automatically)\n- Store the original user-provided name alongside the\n stripped `prometheusName` for use by format writers\n- `Counter.builder().name()` and `Info.builder().name()`\n keep stripping (preserves `getPrometheusName()` behavior)\n\nCollision detection still checks OM1 structural names\n(`_total`, `_info`, `_bucket`, `_count`, `_sum`,\n`_created`) — this is about preventing ambiguous exposition\noutput, not about restricting user names.\n\n### 4. Scrape filter compatibility\n\n`scrape(Predicate\u003cString> includedNames)` tests both the\noriginal name and the `prometheusName` against the\npredicate, so filtering works regardless of which form the\ncaller uses.\n\n### 5. OTel exporter: `preserve_names` flag\n\nAdd `preserve_names` to `ExporterOpenTelemetryProperties`.\n\n#### `preserve_names` = `false` (default)\n\nLegacy behavior, kept for backward compatibility. The\nexporter transforms metric names:\n- Counter `_total` suffix is stripped\n (`http_requests_total` -> `http_requests`)\n- Unit suffix is stripped from the name and moved to the\n OTel unit metadata field\n (`http_request_duration_seconds` -> name\n `http_request_duration`, unit `s`)\n\nThis changes the names users defined, which can be confusing\nregardless of whether you come from an OTel or Prometheus\nbackground.\n\n#### `preserve_names` = `true`\n\nNames are passed through exactly as the user wrote them.\nNo appending, no stripping:\n- `Counter(\"events\")` -> `events`\n- `Counter(\"events_total\")` -> `events_total`\n- `Counter(\"req\").unit(BYTES)` -> name `req`, unit `By`\n- `Histogram(\"dur\").unit(SECONDS)` -> name `dur`, unit `s`\n\nUnit metadata is always set from `.unit()` if provided.\n\n`preserve_names` becomes the default in the next major\nrelease (#1943).\n\n## Backward compatibility\n\n- `Counter.builder().name(\"events\")` -> `prometheusName`\n `events`, OM1: `events_total`, OTel: `events`.\n **Same as today.**\n- `Counter.builder().name(\"events_total\")` ->\n `prometheusName` `events`, OM1: `events_total`, OTel\n legacy: `events`. **Same as today.**\n- `Gauge(\"events_total\")` -> OM1: `events_total`, OTel:\n `events_total`. **New capability** (previously rejected).\n- `sanitizeMetricName(\"foo_total\")` -> `foo_total`\n (was `foo`). **Fixes #1321.**\n- `sanitizeMetricName(\"foo_created\")` -> `foo_created`\n (was `foo`). **Intentional** — all reserved suffixes\n removed.\n- Simpleclient bridge: `sanitizeMetricName` returns\n `events_total` -> goes into `CounterSnapshot` metadata ->\n format writers smart-append correctly.\n **Output unchanged.**\n\n## `disableSuffixAppending` not needed\n\nSuffix behavior is per-format, not a standalone config flag.\nOM2 config (#1939) should focus on `contentNegotiation`,\n`compositeValues`, `exemplarCompliance`,\n`nativeHistograms`. Suffix handling follows the format\nautomatically.","author":{"url":"https://github.com/zeitlinger","@type":"Person","name":"zeitlinger"},"datePublished":"2026-03-10T10:01:37Z","url":"https://github.com/prometheus/client_java/issues/1941"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:498fb501-7e2e-29c3-de84-4f23ba32c9fd |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B96C:E2D7:5CDDEF:7EB63A:6AFBC0AE |
| html-safe-nonce | e78f06d369ac5df504a34a4b2c6b42c39552a02ee2372b2bb6077efab5de53d1 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCOTZDOkUyRDc6NUNEREVGOjdFQjYzQTo2QUZCQzBBRSIsInZpc2l0b3JfaWQiOiIyMTMzMjMzMTQ1ODc1MjUxMzc0IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 4002ae4f75e789f11f038d95ffaf878694180cf88f3d8d611f76938b4abdea62 |
| hovercard-subject-tag | issue:4050696340 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/prometheus/client_java/1941/issue_layout |
| twitter:image | https://opengraph.githubassets.com/c3687b82c533a6923cf2a3d785137fee605708d0ebd0e322fa325ad0d5104cb7/prometheus/client_java/issues/1941 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/c3687b82c533a6923cf2a3d785137fee605708d0ebd0e322fa325ad0d5104cb7/prometheus/client_java/issues/1941 |
| og:image:alt | Part of #1942 (full design rationale). Summary Today, Counter.Builder strips _total and PrometheusNaming rejects names ending with _total/_info at creation time. Then at exposition time, the format... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | zeitlinger |
| hostname | github.com |
| expected-hostname | github.com |
| None | 2b2ef9c1578c18d8ed27027940544c958743213cf4461659f14d3ccdf51e162c |
| turbo-cache-control | no-preview |
| go-import | github.com/prometheus/client_java git https://github.com/prometheus/client_java.git |
| octolytics-dimension-user_id | 3380462 |
| octolytics-dimension-user_login | prometheus |
| octolytics-dimension-repository_id | 7997879 |
| octolytics-dimension-repository_nwo | prometheus/client_java |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 7997879 |
| octolytics-dimension-repository_network_root_nwo | prometheus/client_java |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | e4cce0e99cf61481a318ff12c2e8580153a6c7c6 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width