Tracking Issue

Relates to:

Original discussion
Brainstorming doc Quoting Prometheus Names
OTEL Attribute compatibility section

We are creating this issue as part of the OTEL Support milestone so it will be OTEL oriented but the problem is general to prometheus and has been around for a long time.

OTel allows UTF-8 in label names while Prometheus has a much more restrictive set. This is causing friction for users when using Prometheus. In particular, . (dot) is a very common character in OTel and we convert that to _ when converting to Prometheus. For example, service.version becomes service_version.

Proposals have been accepted to do this work:

• https://github.com/prometheus/proposals/blob/main/proposals/2023-08-21-utf8.md
• https://github.com/prometheus/proposals/blob/main/proposals/2023-11-13-utf8-migration.md Note: the migration proposal has been deprioritized due to higher-than-anticipated complexity and lack of concrete demand.

Minimum Viable Product ✅

MVP is defined as round-trip support for UTF-8 names and labels in the Go language with scraping and remote-write. This serves as an initial testing bed and implementation example for other language bindings.

• prom/common: update openmetrics_parse, promparse (UTF-8 support in validation, and some parsers and formatters common#537)
• prom/common: content negotiation in scraping (UTF8: Content negotiation (encoding side) common#570)
• prom/promtheus: content negotiation and flags (feat(utf8): utf-8 content negotiation and flags #14490)
• prom/client_golang: (Implement changes needed to support UTF8 metric and label names in Prometheus client_golang#1369)
• prom/prometheus: Update some parsers (UTF-8: Add partial support for parsing UTF-8 metric and label names #13271)
• prom/common: update text_parse (go version) (Update expfmt/text_parse.go to support the new UTF-8 syntax common#554)
• Go client library: no changes required
• Prometheus not actually validating legacy names when utf8 on globally but overrided in scrapeconfig #14728
• prom/prometheus: flip flag defaults in v3 branch (utf8: enable utf-8 support by default #14705)
• prom/prometheus: flip flag defaults in main (chore(v3): set UTF-8 default-on #14674)

Follow-ons

• Return an http error during scraping if metrics collide when escaped to underscores client_golang#1641
• UI support for UTF-8 #15202
• UTF-8: format_query endpoint returning invalid format #15243
• UTF-8: scrape fails with quoted "utf8" key in exemplar #15259
• Add support for utf8 names on /v1/label/:name/values endpoint #15399
• Change default validation mode to UTF-8 common#723
• query and query_range endpoints don't return utf8 labels in metric field when grouping by utf8 label  #15470
• Add UTF-8 support to testing framework and add UTF-8 tests #15528
• Investigation: Syntax checker may return warnings for metrics without a suffix #15791
• Prometheus 3.x unable to force dot to underscore translation #16027
• feat: Create way to configure explicit escaping mode other than UTF-8 or "default" #16034
• UTF-8 Tracking: Documentation and Standards #16093

Write-side tasks

• prom/pushgateway: (Support UTF-8 in metric and label names pushgateway#623)

OTLP

• UTF-8 support in Otel Prom SDK exporter (Add utf8 support to the prometheus exporter open-telemetry/opentelemetry-go#5755)
• Allow UTF-8 characters in metric and label names as opt-in feature #15258
• otlp endpoint: No metric translation by default #14990
• [exporter/prometheus] Implement Prometheus translation strategies. open-telemetry/opentelemetry-collector-contrib#35459

Read-side tasks

Mixed-block reading is deprioritized due to the difficult and lack of proven need

• enable querying of old data with new UTF-8 names #13765
• prom/prometheus: tsdb meta.json bump
• prom/prometheus: tsdb multiquerying for otel and other migration cases
• prom/prometheus: content negotiation in querying?
• prom/prometheus: update web/ui parser (UTF-8: Update typescript parser to support new syntax #13564)

Client Libraries

• UTF-8 Tracking: client library implementations #16092

Grafana user-visible changes ✅

Not directly related to Prometheus, but this is the bug I'm using for all the related work, so...

• Grafana Epic: Epic: Prometheus: Support UTF-8 metrics and labels grafana/grafana#91253
• grafana/grafana: Prometheus: Support forthcoming UTF-8 metric and label names in Prometheus grafana/grafana#74875
• grafana/mimir: UTF-8 character support for label and metric names grafana/mimir#10283

Other task refs

• Implement changes needed to support UTF-8 metric and label names in Prometheus common#527
• update prom3 migration guide
• identify other docs to update
• chore: deprecate X=Mimir-SkipLabelNameValidation once UTF-8 is supported grafana/mimir#9457

(This is a clone of #12630 that I own so I can edit the top-level comment and track work here)