Kubernetes CPU 指标在 kubeletstats 接收器中：从 .cpu.utilization 过渡到 .cpu.usage

作者：Christos Markou (Elastic), Tyler Helmuth (Honeycomb), Dmitrii Anoshin (Cisco/Splunk) | 2025 年 5 月 30 日，星期五

OpenTelemetry Collector 的 kubeletstats 接收器是收集 Kubernetes 节点、Pod 和容器指标的关键组件。为了提高指标的准确性并遵循 OpenTelemetry 语义约定，我们正在更新 CPU 指标的命名和发出方式。

这篇博文解释了此更改的动机、对用户的影响、为本次更改引入的功能门的作用以及迁移指南。

为什么要进行此更改？

从历史上看，kubeletstats 接收器发出的 CPU 指标带有 .cpu.utilization 标签，例如

这些指标实际上代表 核心的原始 CPU 使用率，源自 Kubernetes Kubelet 的 UsageNanoCores 字段，这是一个绝对的 CPU 使用率度量（单位为纳核）。

术语“利用率”通常指的是一个相对指标，通常表示为已用 CPU 相对于总 CPU 容量或限制的比例或百分比。使用 .cpu.utilization 来表示绝对使用率值违反了语义约定，可能会使用户和期望利用率指标是相对指标的工具感到困惑。

为解决此语义不匹配问题，我们引入了新的 .cpu.usage 指标，以准确表示原始 CPU 使用率值

与此同时，旧的 .cpu.utilization 指标已被 标记为弃用。

请注意，到目前为止 .cpu.utilization 指标默认是启用的。为了平稳过渡，引入了一个名为 receiver.kubeletstats.enableCPUUsageMetrics 的功能门。

Alpha (v0.111.0): 该功能门已引入但默认禁用。用户需要显式启用它才能默认接收 .cpu.usage 指标而不是 .cpu.utilization。
Beta (v0.125.0): 该功能门已升级到 Beta 版并默认启用。在此状态下
- 默认会发出 .cpu.usage 指标。 - 尝试启用 .cpu.utilization 指标将失败。
- 如果需要，用户可以显式禁用功能门来暂时恢复已弃用的 .cpu.utilization 指标。
稳定版（即将推出）：该功能门将在多个版本中保持 Beta 状态，以便社区有充足的时间进行适应。将其移至稳定版的计划和讨论已在 Issue #39650 中跟踪。

将功能门在 Beta 状态保持多个版本的决定是基于以下因素：

这种方法最大限度地减少了中断，并有助于确保每个人都能顺利过渡。

从 kubeletstats 接收器中的 .cpu.utilization 过渡到 .cpu.usage 指标是确保 Kubernetes 指标符合语义最佳实践的重要一步。我们感谢社区在进行这些改进时所表现出的耐心和合作。

如果您有疑问、想分享反馈或需要迁移帮助，请加入我们的 CNCF Slack。

感谢您帮助我们构建更清晰、更可靠的 Kubernetes 可观测性！