Prometheus map_unit incorrectly normalizes percent ratio units such as %/s
Maintainers usually reply within 2 days
@knowprasad is already working on this.
Since Nov 8, 2026.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 84/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- prometheus, python
- Domain
- observability
Research direction
The bug is in map_unit in exporter/opentelemetry-exporter-prometheus/src/opentelemetry/exporter/prometheus/_mapping.py, in the ratio-unit path where the numerator is sanitized before the _UNIT_MAPPINGS lookup. Run the reproduction from the issue, then check that %/s, %/min and %/h return percent_per_second, percent_per_min and percent_per_hour. Add regression tests under exporter/opentelemetry-exporter-prometheus/tests/ and confirm the existing 41 tests still pass.
Written by the indexing model from the issue text.
Description
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.
- Dominant language
- Python
- Stars
- 2.7k
- Forks
- 1.1k
- Avg merge
- 4d 13m
- Merged PRs (30d)
- 38
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from open-telemetry/opentelemetry-python
-
opentelemetry-configuration: OTLP HTTP exporter does not validate TLS files exist at startupPossibly taken @Dotify71 claimed this 5 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
open-telemetry/opentelemetry-python#5928 ·
Maintainers usually reply within 2 days
-
W3CBaggagePropagator drops a list-member over 4096 bytes that W3C Baggage requires it to propagatePossibly taken @codedbyadiiii claimed this 7 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
open-telemetry/opentelemetry-python#5913 ·
Maintainers usually reply within 2 days
-
otel.sdk.processor.{span,log}.queue.capacity uses synchronous UpDownCounter recorded once in __init__May be free again A pull request for this issue was closed without being merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
open-telemetry/opentelemetry-python#5891 ·
Maintainers usually reply within 2 days
-
OTLP HTTP exporter reports a 3xx response as a successful export, so redirected batches are dropped without any logPossibly taken @d4rshnn claimed this 18 days ago. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
open-telemetry/opentelemetry-python#5865 · 1 comment ·
Maintainers usually reply within 2 days
-
Difficulty 1/5 Under an hour Newbie friendliness 70/100
open-telemetry/opentelemetry-python#5700 · 1 comment ·
Maintainers usually reply within 2 days
All issues in open-telemetry/opentelemetry-python
Similar issues
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
docling-project/docling-pipelines#669 ·
Maintainers usually reply within 1 day
-
blocked kind/enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
opendatahub-io/agent-eval-harness#329 · 2 comments · 1 reaction ·
-
cc_wrapper crashes with ValueError on Windows when a path is on another drivePossibly taken @TrapsterDK claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 79/100
tweag/rules_haskell#2492 ·
Maintainers usually reply within 1 day