Prometheus map_unit incorrectly normalizes percent ratio units such as %/s
维护者通常 2 天内回复
评估
- 难度
- 2/5
- 预计耗时
- 1-3 小时
- 新手友好度
- 84/100
- Issue 类型
- 缺陷
- 描述清晰度
- 描述清楚
- 活跃度
- 活跃
- 技术栈
- prometheus, python
调研方向
问题出在 exporter/opentelemetry-exporter-prometheus/src/opentelemetry/exporter/prometheus/_mapping.py 中的 map_unit,具体是比率单位路径中,分子在 _UNIT_MAPPINGS 查找之前被清理的那段逻辑。运行 issue 中的复现步骤,然后检查 %/s、%/min 和 %/h 分别返回 percent_per_second、percent_per_min 和 percent_per_hour。在 exporter/opentelemetry-exporter-prometheus/tests/ 下添加回归测试,并确认现有的 41 个测试仍然通过。
由索引模型根据 Issue 内容生成。
描述
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.
- 主要语言
- Python
- 星标
- 2.7k
- 派生
- 1.1k
- 平均合并
- 4 天 13 分钟
- 30 天内合并 PR
- 38
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
open-telemetry/opentelemetry-python 的其他 Issue
-
opentelemetry-configuration: OTLP HTTP exporter does not validate TLS files exist at startup可能已有人在做 @Dotify71 于 5 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 78/100
open-telemetry/opentelemetry-python#5928 ·
维护者通常 2 天内回复
-
W3CBaggagePropagator drops a list-member over 4096 bytes that W3C Baggage requires it to propagate可能已有人在做 @codedbyadiiii 于 7 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 70/100
open-telemetry/opentelemetry-python#5913 ·
维护者通常 2 天内回复
-
otel.sdk.processor.{span,log}.queue.capacity uses synchronous UpDownCounter recorded once in __init__可能重新可做 关联的 PR 已关闭且未合并。 未关闭
难度 2/5 1-3 小时 新手友好度 78/100
open-telemetry/opentelemetry-python#5891 ·
维护者通常 2 天内回复
-
OTLP HTTP exporter reports a 3xx response as a successful export, so redirected batches are dropped without any log可能已有人在做 @d4rshnn 于 18 天前认领。 未关闭bug
难度 2/5 1-3 小时 新手友好度 72/100
open-telemetry/opentelemetry-python#5865 · 1 条评论 ·
维护者通常 2 天内回复
-
难度 1/5 1 小时以内 新手友好度 70/100
open-telemetry/opentelemetry-python#5700 · 1 条评论 ·
维护者通常 2 天内回复
查看 open-telemetry/opentelemetry-python 的全部 Issue
相似的 Issue
-
bug
难度 2/5 1-3 小时 新手友好度 78/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 66/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 75/100
docling-project/docling-pipelines#669 ·
维护者通常 1 天内回复
-
blocked kind/enhancement
难度 2/5 1-3 小时 新手友好度 78/100
opendatahub-io/agent-eval-harness#329 · 2 条评论 · 1 个 reaction ·
-
cc_wrapper crashes with ValueError on Windows when a path is on another drive可能已有人在做 @TrapsterDK 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 79/100
tweag/rules_haskell#2492 ·
维护者通常 1 天内回复