Title: Don't escape UTF-8 names by default for OpenMetrics 2.0 · Issue #2517 · prometheus/client_java · GitHub
Open Graph Title: Don't escape UTF-8 names by default for OpenMetrics 2.0 · Issue #2517 · prometheus/client_java
X Title: Don't escape UTF-8 names by default for OpenMetrics 2.0 · Issue #2517 · prometheus/client_java
Description: When a scraper negotiates OpenMetrics 2.0 (Accept: application/openmetrics-text;version=2.0.0) without an escaping parameter, PrometheusScrapeHandler escapes UTF-8 metric and label names with EscapingScheme.DEFAULT (underscores). OpenMet...
Open Graph Description: When a scraper negotiates OpenMetrics 2.0 (Accept: application/openmetrics-text;version=2.0.0) without an escaping parameter, PrometheusScrapeHandler escapes UTF-8 metric and label names with Escap...
X Description: When a scraper negotiates OpenMetrics 2.0 (Accept: application/openmetrics-text;version=2.0.0) without an escaping parameter, PrometheusScrapeHandler escapes UTF-8 metric and label names with Escap...
Opengraph URL: https://github.com/prometheus/client_java/issues/2517
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Don't escape UTF-8 names by default for OpenMetrics 2.0","articleBody":"When a scraper negotiates OpenMetrics 2.0 (`Accept: application/openmetrics-text;version=2.0.0`) without an `escaping` parameter, `PrometheusScrapeHandler` escapes UTF-8 metric and label names with `EscapingScheme.DEFAULT` (underscores). **OpenMetrics 2.0 supports UTF-8 names natively and doesn't define an `escaping` parameter at all, so we could assume that scraper asking for 2.0.0 already supports UTF-8 names. In that case we shouldn't escape by default.**\n\nPrometheus main doesn't send `escaping` for OM 2.0 (\u003chttps://github.com/prometheus/prometheus/blob/961c9ba40923ca4d7adf4a7a9167e56d0406df83/scrape/scrape.go#L794-L800>), so UTF-8 names are currently escaped to underscores when scraping a Java target with OM 2.0. There's a Prometheus-side workaround in \u003chttps://github.com/prometheus/prometheus/compare/main...bwplotka/om2-accept-escaping>, but the default here should be fixed regardless.\n\nThe escaping scheme is chosen without looking at the selected format:\n\n- `EscapingScheme.fromAcceptHeader` returns `DEFAULT` when there's no `escaping` term: \u003chttps://github.com/prometheus/client_java/blob/9e9deb6b9e591c2a62b12882d8a987f120661b71/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/EscapingScheme.java#L29-L67>.\n- `PrometheusScrapeHandler` computes it before, and separately from, `findWriter`: \u003chttps://github.com/prometheus/client_java/blob/9e9deb6b9e591c2a62b12882d8a987f120661b71/prometheus-metrics-exporter-common/src/main/java/io/prometheus/metrics/exporter/common/PrometheusScrapeHandler.java#L73-L91>.\n- `ExpositionFormats.findWriter` picks the OM 2.0 writer: \u003chttps://github.com/prometheus/client_java/blob/9e9deb6b9e591c2a62b12882d8a987f120661b71/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/ExpositionFormats.java#L63-L86>.\n\nProposed change (pseudo code):\n\n```java\n// PrometheusScrapeHandler\nString acceptHeader = request.getHeader(\"Accept\");\nExpositionFormatWriter writer = expositionFormats.findWriter(acceptHeader);\nEscapingScheme escapingScheme = EscapingScheme.fromAcceptHeader(acceptHeader, defaultFor(acceptHeader));\n\n// Only default to UTF-8 when 2.0.0 was explicitly requested. With\n// contentNegotiation=false the OM 2.0 writer also serves OM 1.0 / unversioned\n// requests, e.g. from pre-3.0 Prometheus that can't parse UTF-8 names.\nEscapingScheme defaultFor(String acceptHeader) {\n return \"2.0.0\".equals(parseOpenMetricsVersion(acceptHeader))\n ? EscapingScheme.ALLOW_UTF8\n : EscapingScheme.DEFAULT;\n}\n\n// EscapingScheme\npublic static EscapingScheme fromAcceptHeader(@Nullable String acceptHeader, EscapingScheme fallback) {\n // Same parsing as today. An explicit escaping term always wins, also for OM 2.0\n // (e.g. a Prometheus with legacy name validation asking for underscores).\n // Return fallback instead of DEFAULT when the term is missing or unknown.\n}\n```\n\nExisting `fromAcceptHeader(String)` can keep delegating with `DEFAULT` to stay API compatible. Ideally the version and escaping term should come from the same Accept clause that `findWriter` matched. Today both helpers scan the whole header, so a parameter from another clause can leak in.\n\nTests to add (e.g. `ExpositionFormatsTest`, plus a scrape handler test):\n\n- `version=2.0.0` without `escaping` writes unescaped UTF-8 names.\n- `version=2.0.0;escaping=underscores` still escapes.\n- `version=1.0.0`, unversioned OpenMetrics and `text/plain` without `escaping` keep the underscores default, including with `contentNegotiation=false`.\n\nThe escaping schemes doc should get the same OM 2.0 exception, since its \"Default Behavior\" section says to use underscores whenever `escaping` is missing: \u003chttps://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/instrumenting/escaping_schemes.md#default-behavior>.\n\nMatching client_golang issue: https://github.com/prometheus/client_golang/issues/2149\n","author":{"url":"https://github.com/bwplotka","@type":"Person","name":"bwplotka"},"datePublished":"2026-10-03T14:44:30Z","url":"https://github.com/prometheus/client_java/issues/2517"}
| 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:9ded6fcc-101a-711c-f9d1-3f017ce39e21 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | E648:9AE98:216FB9:2C7C1D:6AFBB525 |
| html-safe-nonce | 913d491b416254e4d6dddaf44894afc23de3ffd991a1addd41f8d8d395e0823b |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFNjQ4OjlBRTk4OjIxNkZCOToyQzdDMUQ6NkFGQkI1MjUiLCJ2aXNpdG9yX2lkIjoiNjczMDMxODA5NjU2MjM2OTgyOSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 3b6069ccbdb40ef39ebf0f4f75cc35f7fa9f106c52b3f9aa313c834d7f603335 |
| hovercard-subject-tag | issue:5690634495 |
| 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/2517/issue_layout |
| twitter:image | https://opengraph.githubassets.com/42b7aca1c54588b74af5e04fabc1ee59f8dcb8d1082c054ece3a6d07d04f7ede/prometheus/client_java/issues/2517 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/42b7aca1c54588b74af5e04fabc1ee59f8dcb8d1082c054ece3a6d07d04f7ede/prometheus/client_java/issues/2517 |
| og:image:alt | When a scraper negotiates OpenMetrics 2.0 (Accept: application/openmetrics-text;version=2.0.0) without an escaping parameter, PrometheusScrapeHandler escapes UTF-8 metric and label names with Escap... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | bwplotka |
| 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