Prometheus map_unit incorrectly normalizes percent ratio units such as %/s
Mantenedores costumam responder em até 2 dias
@knowprasad já está trabalhando nisso.
Desde 8/11/2026.
Avaliação
- Dificuldade
- 2/5
- Tempo estimado
- 1-3 horas
- Facilidade para iniciantes
- 84/100
- Tipo de issue
- Bug
- Clareza
- Claramente especificada
- Status de atividade
- Ativa
- Stack de tecnologia
- prometheus, python
- Domínio
- observability
Direção de pesquisa
O bug está em map_unit em exporter/opentelemetry-exporter-prometheus/src/opentelemetry/exporter/prometheus/_mapping.py, no caminho de unidades de razão em que o numerador é sanitizado antes da busca em _UNIT_MAPPINGS. Execute a reprodução da issue e depois verifique se %/s, %/min e %/h retornam percent_per_second, percent_per_min e percent_per_hour, respectivamente. Adicione testes de regressão em exporter/opentelemetry-exporter-prometheus/tests/ e confirme que os 41 testes existentes continuam passando.
Escrita pelo modelo de indexação a partir do texto da issue.
Descrição
Describe your environment
- Repository: open-telemetry/opentelemetry-python
- Branch: main
- Tested commit: 3462000f323b4f3d03c10d09b9d82c03119f2c59
- Operating system: Windows 11
- Python version: 3.10.9
- uv version: 0.13.5
- Package: opentelemetry-exporter-prometheus
My local main branch matched upstream/main, and the working tree was clean when I reproduced the issue.
What happened?
The Prometheus exporter's map_unit function does not correctly normalize compound ratio units when the numerator is the percent symbol.
The following standalone and compound units are normalized correctly:
- map_unit("%") returns "percent"
- map_unit("m/s") returns "meters_per_second"
- map_unit("By/s") returns "bytes_per_second"
However:
- map_unit("%/s") returns "__per_second"
- map_unit("%/min") returns "__per_min"
- map_unit("%/h") returns "__per_hour"
The percent unit is lost because the ratio-unit path sanitizes "%" into "_" before checking _UNIT_MAPPINGS, even though _UNIT_MAPPINGS contains the mapping "%": "percent".
In an end-to-end Prometheus export, a counter named "cpu.usage.rate" with unit "%/s" is exported as:
cpu_usage_rate___per_second_total
The generated name is syntactically valid for Prometheus, but it is semantically incorrect because the "percent" unit is lost during normalization.
Steps to Reproduce
From the repository root, run:
uv run python -c "from opentelemetry.exporter.prometheus._mapping import map_unit; print('percent:', map_unit('%')); print('meters per second:', map_unit('m/s')); print('percent per second:', map_unit('%/s'))"
The output is:
percent: percent
meters per second: meters_per_second
percent per second: __per_second
A minimal failing assertion is:
from opentelemetry.exporter.prometheus._mapping import map_unit
assert map_unit("%/s") == "percent_per_second"
The assertion currently fails because the actual value is "__per_second".
The same issue occurs with other percent ratio units:
assert map_unit("%/min") == "percent_per_min"
assert map_unit("%/h") == "percent_per_hour"
The current results are "__per_min" and "__per_hour", respectively.
Expected Result
Percent ratio units should preserve the existing percent mapping and normalize both parts of the compound unit.
Expected results:
- map_unit("%/s") returns "percent_per_second"
- map_unit("%/min") returns "percent_per_min"
- map_unit("%/h") returns "percent_per_hour"
For a counter named "cpu.usage.rate" with unit "%/s", the normalized Prometheus metric name should contain the suffix "percent_per_second", for example:
cpu_usage_rate_percent_per_second_total
Actual Result
The percent numerator is replaced with an underscore before the unit mapping is applied.
Actual results:
- map_unit("%/s") returns "__per_second"
- map_unit("%/min") returns "__per_min"
- map_unit("%/h") returns "__per_hour"
For a counter named "cpu.usage.rate" with unit "%/s", the end-to-end Prometheus output contains:
HELP cpu_usage_rate___per_second_total Test metric description
TYPE cpu_usage_rate___per_second_total counter
cpu_usage_rate___per_second_total{otel_scope_name="test_meter",otel_scope_schema_url="",otel_scope_version=""} 42.0
The metric name is syntactically valid, but the normalized unit is semantically incorrect because "percent" has been lost.
Additional context
The issue appears to be in:
exporter/opentelemetry-exporter-prometheus/src/opentelemetry/exporter/prometheus/_mapping.py
_UNIT_MAPPINGS already contains:
"%": "percent"
The standalone "%" case works because the direct mapping lookup happens before sanitization.
In the ratio-unit path, the numerator is sanitized first. Sanitizing "%" produces "_", so the subsequent lookup no longer finds the "%" mapping. The final value becomes "__per_second".
I ran the full Prometheus exporter test suite:
uv run pytest exporter/opentelemetry-exporter-prometheus/tests/
Result:
41 passed
The current tests cover standalone "%" and ratio units such as "m/s", but they do not appear to cover "%" as the numerator of a ratio unit.
I searched open and closed issues and pull requests using terms including map_unit, %/s, percent_per_second, __per_second, _UNIT_MAPPINGS, and ratio unit. I could not find existing work covering this behavior.
Issue #5766 and PR #5798 relate to annotation stripping in compound units, but they do not appear to address percent-symbol normalization in the ratio-unit path.
I would like to add regression coverage and work on a focused fix if the expected normalization is confirmed.
Would you like to implement a fix?
Yes
Tip
React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.
- Linguagem predominante
- Python
- Estrelas
- 2.7k
- Forks
- 1.1k
- Merge médio
- 4d 13min
- PRs com merge (30d)
- 38
Preparar o ambiente
- Sem Dockerfile nem arquivo Docker Compose
- Tem um modelo de pull request
- Ler o guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Mais de open-telemetry/opentelemetry-python
-
opentelemetry-configuration: OTLP HTTP exporter does not validate TLS files exist at startupTalvez já em andamento @Dotify71 assumiu há 5 dias. Aberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 78/100
open-telemetry/opentelemetry-python#5928 ·
Mantenedores costumam responder em até 2 dias
-
W3CBaggagePropagator drops a list-member over 4096 bytes that W3C Baggage requires it to propagateTalvez já em andamento @codedbyadiiii assumiu há 8 dias. Aberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 70/100
open-telemetry/opentelemetry-python#5913 ·
Mantenedores costumam responder em até 2 dias
-
otel.sdk.processor.{span,log}.queue.capacity uses synchronous UpDownCounter recorded once in __init__Talvez livre de novo Um pull request para esta issue foi fechado sem ser mesclado. Aberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 78/100
open-telemetry/opentelemetry-python#5891 ·
Mantenedores costumam responder em até 2 dias
-
OTLP HTTP exporter reports a 3xx response as a successful export, so redirected batches are dropped without any logTalvez já em andamento @d4rshnn assumiu há 18 dias. Abertabug
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 72/100
open-telemetry/opentelemetry-python#5865 · 1 comentário ·
Mantenedores costumam responder em até 2 dias
-
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 70/100
open-telemetry/opentelemetry-python#5700 · 1 comentário ·
Mantenedores costumam responder em até 2 dias
Todas as issues de open-telemetry/opentelemetry-python
Issues semelhantes
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 65/100
Deltares/numba_celltree#100 · 1 comentário ·
-
auto-reported bug
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 63/100
Mantenedores costumam responder em até 1 dia
-
soup airgap-bundle --bundle-size-cap nan, inf or a cap above ~1.67e299 GiB stops with an internal ValueError/OverflowError (exit 1) instead of a usage errorTalvez já em andamento @Keshemir assumiu hoje. Abertabug claimed difficulty:2
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 82/100
MakazhanAlpamys/Soup#3045 · 2 comentários ·
Mantenedores costumam responder em até 1 dia
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 76/100
dagster-io/skills#80 ·
-
bug
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 78/100
Mantenedores costumam responder em até 1 dia