Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

OpenMetrics 2.0: option to keep _total and unit suffixes, so switching from OM1 doesn't rename series

Aberta
  • Algo errado?
#2,518 4 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

@arnabnandy7 já está trabalhando nisso.

Desde 7/10/2026.

  • #2529 de @arnabnandy7 — aberto

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
62/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
java
Domínio
observability-sre

Direção de pesquisa

Start with OpenMetrics2TextFormatWriter.java and OpenMetrics2Properties, then compare their behavior with the OM1 expositionBaseName logic. Review docs/content/exporters/openmetrics2.md for the current naming contract. Done means OM2 can preserve _total and unit suffixes for existing metrics, with a documented default or opt-out matching the chosen design.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

With io.prometheus.openmetrics2.enabled, the OM2 writer exposes names exactly as passed to the builder. It never appends _total or the unit suffix:

https://github.com/prometheus/client_java/blob/9e9deb6b9e591c2a62b12882d8a987f120661b71/prometheus-metrics-exposition-textformats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetrics2TextFormatWriter.java#L174-L179

This is documented in https://github.com/prometheus/client_java/blob/9e9deb6b9e591c2a62b12882d8a987f120661b71/docs/content/exporters/openmetrics2.md#L57-L77, e.g. Counter("req").unit(BYTES) is req_bytes_total in OM1 but req in OM2.

The problem is that switching a target from OM1 to OM2 renames every counter, and every metric with a unit, that was instrumented the way client_java has always recommended (Counter.builder().name("events")). Prometheus then stores them as new series, so existing queries, dashboards and alerts silently stop matching.

[!NOTE]
I hit this with a demo that scrapes the same client_java app with OM1 and OM2 and diffs the stored series: the JVM metrics match (they already have the suffixes in their names), but http_requests_total (OM1) became http_requests (OM2), and http_request_size_bytes_total became http_request_size. Demo: https://35-204-166-191.sslip.io/, code: https://github.com/bwplotka/prometheus/pull/7.

The OM2 spec relaxed _total and the unit suffix from MUST to SHOULD, mainly for OpenTelemetry compatibility (https://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/guides/open_metrics_2_0_migration.md?plain=1#L140). Both are still recommended though (https://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/specs/om/open_metrics_spec_2_0.md?plain=1#L220 and https://github.com/prometheus/docs/blob/605cf81fefc2e8e91f8ba89bb1555ae52a43a318/docs/specs/om/open_metrics_spec_2_0.md?plain=1#L664). Today there is no way to get them in OM2 other than renaming every metric in code; OpenMetrics2Properties has no option for it.

Proposal:

  1. add a property, e.g. io.prometheus.openmetrics2.suffixes (or a naming mode), that keeps the OM1 suffix behaviour in the OM2 writer: append _total to counters and the unit suffix where missing, as expositionBaseName already does for OM1.
  2. I'd argue it should default to on, so that negotiating OM2 doesn't change any series names, and users who want names exactly as written (e.g. for OTel-style names) can opt out.

For comparison, client_golang keeps the names users register (which by convention include _total and the unit), so there OM1 and OM2 produce the same series.

Linguagem predominante
Java
Estrelas
2.3k
Forks
833
Merge médio
1d 9h
PRs com merge (30d)
73

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de prometheus/client_java

Todas as issues de prometheus/client_java

Issues semelhantes

Mais issues de Java

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.