Prometheus map_unit incorrectly normalizes percent ratio units such as %/s
Maintainer thường phản hồi trong vòng 2 ngày
@knowprasad đang làm issue này rồi.
Từ ngày 8/11/2026.
Đánh giá
- Độ khó
- 2/5
- Thời gian dự kiến
- 1-3 giờ
- Mức phù hợp với người mới
- 84/100
- Loại issue
- Lỗi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức độ hoạt động
- Sôi nổi
- Công nghệ
- prometheus, python
- Lĩnh vực
- observability
Hướng nghiên cứu
Lỗi nằm ở map_unit trong exporter/opentelemetry-exporter-prometheus/src/opentelemetry/exporter/prometheus/_mapping.py, ở nhánh xử lý đơn vị tỷ lệ, nơi tử số được làm sạch trước khi tra cứu trong _UNIT_MAPPINGS. Chạy lại tái hiện từ issue, sau đó kiểm tra rằng %/s, %/min và %/h lần lượt trả về percent_per_second, percent_per_min và percent_per_hour. Thêm các kiểm thử hồi quy trong exporter/opentelemetry-exporter-prometheus/tests/ và xác nhận rằng 41 kiểm thử hiện có vẫn đều chạy thành công.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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.
- Ngôn ngữ chính
- Python
- Star
- 2.7k
- Fork
- 1.1k
- Merge trung bình
- 4 ngày 13 phút
- Pull request đã merge (30 ngày)
- 38
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của open-telemetry/opentelemetry-python
-
opentelemetry-configuration: OTLP HTTP exporter does not validate TLS files exist at startupCó thể đã có người làm @Dotify71 đã nhận 5 ngày trước. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
open-telemetry/opentelemetry-python#5928 ·
Maintainer thường phản hồi trong vòng 2 ngày
-
W3CBaggagePropagator drops a list-member over 4096 bytes that W3C Baggage requires it to propagateCó thể đã có người làm @codedbyadiiii đã nhận 7 ngày trước. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
open-telemetry/opentelemetry-python#5913 ·
Maintainer thường phản hồi trong vòng 2 ngày
-
otel.sdk.processor.{span,log}.queue.capacity uses synchronous UpDownCounter recorded once in __init__Có thể làm lại được Pull request cho issue này đã bị đóng mà không được merge. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
open-telemetry/opentelemetry-python#5891 ·
Maintainer thường phản hồi trong vòng 2 ngày
-
OTLP HTTP exporter reports a 3xx response as a successful export, so redirected batches are dropped without any logCó thể đã có người làm @d4rshnn đã nhận 18 ngày trước. Đang mởbug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
open-telemetry/opentelemetry-python#5865 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 2 ngày
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 70/100
open-telemetry/opentelemetry-python#5700 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 2 ngày
Tất cả issue của open-telemetry/opentelemetry-python
Issue tương tự
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 66/100
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
docling-project/docling-pipelines#669 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
blocked kind/enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
opendatahub-io/agent-eval-harness#329 · 2 bình luận · 1 reaction ·
-
cc_wrapper crashes with ValueError on Windows when a path is on another driveCó thể đã có người làm @TrapsterDK đã nhận hôm nay. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 79/100
tweag/rules_haskell#2492 ·
Maintainer thường phản hồi trong vòng 1 ngày