Prometheus map_unit incorrectly normalizes percent ratio units such as %/s

未关闭 适合新手
#5,875 1 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 2 天内回复

@knowprasad 已经在做这个了。

开始于 2026年11月8日。

  • #5899 来自 @knowprasad —— 未关闭
  • #5910 来自 @2Zest —— 已关闭,未合并

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
84/100
Issue 类型
缺陷
描述清晰度
描述清楚
活跃度
活跃
技术栈
prometheus, python
领域
observability

调研方向

问题出在 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 内容生成。

描述

bug
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

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

open-telemetry/opentelemetry-python 的其他 Issue

查看 open-telemetry/opentelemetry-python 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。