kubeletstats レシーバーにおける Kubernetes CPU メトリクス: .cpu.utilization から .cpu.usage への移行

By Christos Markou (Elastic), Tyler Helmuth (Honeycomb), Dmitrii Anoshin (Cisco/Splunk) |

Blog posts are not updated after publication. This post is more than a year old, so its content may be outdated, and some links may be invalid. Cross-verify any information before relying on it.

OpenTelemetry Collector の kubeletstats レシーバーは、Kubernetes のノード、Pod、コンテナのメトリクスを収集するための重要なコンポーネントです。 メトリクスの精度を向上させ、OpenTelemetry セマンティック規約に準拠するため、CPU メトリクスの命名と出力方法を更新しています。

このブログ記事では、この変更の背景にある動機、ユーザーへの影響、この変更のために導入されたフィーチャーゲートの役割、および移行のガイダンスについて説明します。

なぜこの変更が必要なのか

歴史的に、 kubeletstats レシーバーは .cpu.utilization というラベルを持つ CPU メトリクスを出力していました。 たとえば以下のようなものです。

これらのメトリクスは実際にはCPU使用量（コア数）の生の値を表しており、Kubernetes Kubelet の UsageNanoCores フィールドから導出されたもので、CPU使用量の絶対値（ナノコア単位）を示します。

utilization（利用率）という用語は一般的に、使用済み CPU の合計 CPU 容量や制限に対する比率やパーセンテージとして表される相対的なメトリクスを指します。 絶対的な使用量の値に .cpu.utilization を使用することは、セマンティック規約に違反しており、利用率メトリクスが相対的であると期待するユーザーやツールに混乱を招く可能性があります。

何が変わるのか

このセマンティック上のミスマッチに対処するため、CPU使用量の生の値を正しく表す新しい .cpu.usage メトリクスを導入しました。

同時に、レガシーの .cpu.utilization メトリクスは非推奨としてマークされました。

フィーチャーゲート: receiver.kubeletstats.enableCPUUsageMetrics

.cpu.utilization メトリクスはこれまでデフォルトで有効になっていました。 移行をスムーズに管理するため、receiver.kubeletstats.enableCPUUsageMetrics という名前のフィーチャーゲートが導入されました。

  • Alpha （v0.111.0）: フィーチャーゲートが導入されましたが、デフォルトでは無効でした。 ユーザーは .cpu.utilization のかわりに .cpu.usage メトリクスをデフォルトで受け取るには、明示的に有効にする必要がありました。
  • Beta （v0.125.0）: フィーチャーゲートは Beta に昇格し、デフォルトで有効になりました。 この状態では次のようになります。
    • .cpu.usage メトリクスがデフォルトで出力されます。
    • .cpu.utilization メトリクスを有効にしようとすると失敗します。
    • 必要に応じて、フィーチャーゲートを明示的に無効にすることで、非推奨の .cpu.utilization メトリクスを一時的に復元できます。
  • Stable（今後予定）: フィーチャーゲートは、コミュニティが適応するための十分な時間を確保するため、数リリースの間 Beta のまま維持されます。 Stable への移行の計画と議論は Issue #39650 で追跡されています。

これはあなたにとって何を意味するのか

既存ユーザーへの影響

  • v0.125.0以降にアップグレードすると、Collector はデフォルトで .cpu.usage メトリクスを出力するようになります。
  • .cpu.utilization メトリクスに依存しているモニタリングダッシュボード、アラートルール、クエリは動作しなくなるか、期待どおりに機能しなくなります。
  • 非推奨の .cpu.utilization メトリクスは最終的に削除される予定のため、長期的な互換性のためにも更新が必要です。
  1. .cpu.utilization メトリクスへの参照がないか、オブザーバビリティパイプラインを監査してください。
  2. 新しい .cpu.usage メトリクスを使用するように、ダッシュボード、アラート、クエリを更新してください。
  3. ステージング環境でフィーチャーゲートを有効にして（または v0.125.0以降のデフォルト有効状態を利用して）、新しいメトリクスをテストしてください。
  4. .cpu.utilization が将来のリリースで削除されることを考慮して、移行のタイムラインを計画してください。
  5. GitHub issues や PR のディスカッションを通じて、OpenTelemetry コミュニティとの関わりを維持してください。

なぜフィーチャーゲートを Beta のまま維持するのか

フィーチャーゲートを複数のリリースにわたって Beta のまま維持する決定は、以下の理由に基づいています。

  • 多くの本番オブザーバビリティパイプラインにとって、kubeletstats の CPU メトリクスが極めて重要であること。
  • ユーザーやベンダーがツールを適応・更新するための十分な時間を確保する必要があること。
  • 変更が恒久的になる前に、フィードバックを収集し、予期しない問題に対処する機会を得ること。

このアプローチにより、混乱を最小限に抑え、すべてのユーザーにとってスムーズな移行を実現します。

まとめ

kubeletstats レシーバーにおける .cpu.utilization から .cpu.usage メトリクスへの移行は、Kubernetes メトリクスがセマンティックのベストプラクティスに準拠するための重要なステップです。 これらの改善を進めるにあたり、コミュニティの忍耐と協力に感謝いたします。

質問がある場合、フィードバックを共有したい場合、または移行のサポートが必要な場合は、CNCF Slack にご参加ください。

より明確で信頼性の高い Kubernetes オブザーバビリティの構築にご協力いただき、ありがとうございます！

最終更新 October 17, 2026: [ja] add translation of content/en/blog/2025/kubeletstats-receiver-metrics-deprecation.md (#12077) (ae7a5ce3)