この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/non-normative/k8s-migration/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

K8sセマンティック規約の安定化に伴う移行

K8sセマンティック規約の安定化は、まだWip（作業中）です。 このガイドでは、その過程で生じる破壊的変更をまとめており、ユーザーが今後の変更について事前に把握できるようにしています。

変更点の数が多く、影響を受けるユーザーの範囲が広いため、OpenTelemetryが公開している既存のK8s計装は、ユーザーが安定版のK8sセマンティック規約へ移行できるよう支援する移行計画を実装する必要があります。

OpenTelemetryが公開している既存のK8s計装が安定版のK8sセマンティック規約へ更新される際は、次のようになります。

• 既存のメジャーバージョンに環境変数OTEL_SEMCONV_STABILITY_OPT_INを導入すべきです（SHOULD）。この環境変数は次の値を受け付けます。
  • k8s — 安定版のK8s規約を出力し、それまで計装が出力していた古いK8s規約の出力を停止する。
  • k8s/dup — 古い規約と安定版の規約の両方を出力し、安定版のセマンティック規約への段階的な移行を可能にする。
  • これらの値がいずれも指定されない場合の既定の動作は、その計装がそれまで出力していた古いK8s規約のバージョンをそのまま出力し続けることです。
• 両方の規約セットを出力するようになった時点から少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチについて）保守する必要があります。
• 次のメジャーバージョンでこの環境変数を削除し、安定版のK8s規約のみを出力するようにしてもよいでしょう。

特にOpenTelemetry Collectorについては次のとおりです。

移行は、2つの異なるフィーチャーゲートを通じて行われます。新しいスキーマを有効にするsemconv.k8s.enableStableと、古いスキーマを無効にするsemconv.k8s.disableLegacyです。それぞれの挙動は次のとおりです。

• alpha版では、古いスキーマが既定で有効（semconv.k8s.disableLegacyの既定値はfalse）であり、新しいスキーマは既定で無効（semconv.k8s.enableStableの既定値はfalse）です。
• beta版・stable版では、古いスキーマが既定で無効（semconv.k8s.disableLegacyの既定値はtrue）であり、新しいスキーマは既定で有効（semconv.k8s.enableStableの既定値はtrue）です。
• 両方のスキーマを無効にするのはエラーです。
• --feature-gates=-semconv.k8s.disableLegacy,+semconv.k8s.enableStableとすることで、両方のスキーマを有効にできます。

変更点のまとめ

このセクションでは、複数のバージョンにわたるK8sセマンティック規約への変更をまとめます。それぞれの開始バージョンには、その規約を安定版にするために必要なすべての変更を示しています。

K8sのネットワークメトリクス

Collectorで実装されているK8sのネットワークメトリクス、具体的にはkubeletstatsレシーバーのメトリクスは、v1.29.0でセマンティック規約として導入されました。

その属性の変更点は次のとおりです。

旧（Collector）	新
interface	network.interface.name
direction	network.io.direction

K8s Nodeのallocatableメトリクス

Collectorで実装されているK8s Nodeのallocatableメトリクス、具体的にはk8sclusterレシーバーのメトリクスです。

Collectorの実装とセマンティック規約の間の変更点は次のとおりです。

旧（Collector）	新
k8s.node.allocatable_cpu （type: gauge）	k8s.node.cpu.allocatable （type: updowncounter）
k8s.node.allocatable_memory （type: gauge）	k8s.node.memory.allocatable （type: updowncounter）
k8s.node.allocatable_ephemeral_storage （type: gauge）	k8s.node.ephemeral_storage.allocatable （type: updowncounter）
k8s.node.allocatable_pods （type: gauge）	k8s.node.pod.allocatable （type: updowncounter）

K8s Deploymentのメトリクス

Collectorで実装されているK8s Deploymentのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクス名と型の変更点は次のとおりです。

旧（Collector）	新
k8s.deployment.desired （type: gauge）	k8s.deployment.pod.desired （type: updowncounter）
k8s.deployment.available （type: gauge）	k8s.deployment.pod.available （type: updowncounter）

K8s ReplicaSetのメトリクス

Collectorで実装されているK8s ReplicaSetのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクス名と型の変更点は次のとおりです。

旧（Collector）	新
k8s.replicaset.desired （type: gauge）	k8s.replicaset.pod.desired （type: updowncounter）
k8s.replicaset.available （type: gauge）	k8s.replicaset.pod.available （type: updowncounter）

K8s ReplicationControllerのメトリクス

Collectorで実装されているK8s ReplicationControllerのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクス名と型の変更点は次のとおりです。

旧（Collector）	新
k8s.replication_controller.desired （type: gauge）	k8s.replicationcontroller.pod.desired （type: updowncounter）
k8s.replication_controller.available （type: gauge）	k8s.replicationcontroller.pod.available （type: updowncounter）

K8s StatefulSetのメトリクス

Collectorで実装されているK8s StatefulSetのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクスの型の変更点は次のとおりです。

旧（Collector）	新
k8s.statefulset.desired_pods （type: gauge）	k8s.statefulset.pod.desired （type: updowncounter）
k8s.statefulset.ready_pods （type: gauge）	k8s.statefulset.pod.ready （type: updowncounter）
k8s.statefulset.current_pods （type: gauge）	k8s.statefulset.pod.current （type: updowncounter）
k8s.statefulset.updated_pods （type: gauge）	k8s.statefulset.pod.updated （type: updowncounter）

K8s HorizontalPodAutoscalerのメトリクス

Collectorで実装されているK8s HorizontalPodAutoscalerのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクス名と型の変更点は次のとおりです。

旧（Collector）	新
k8s.hpa.desired_replicas （type: gauge）	k8s.hpa.pod.desired （type: updowncounter）
k8s.hpa.current_replicas （type: gauge）	k8s.hpa.pod.current （type: updowncounter）
k8s.hpa.max_replicas （type: gauge）	k8s.hpa.pod.max （type: updowncounter）
k8s.hpa.min_replicas （type: gauge）	k8s.hpa.pod.min （type: updowncounter）

K8s DaemonSetのメトリクス

Collectorで実装されているK8s DaemonSetのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクスの型の変更点は次のとおりです。

旧（Collector）	新
k8s.daemonset.current_scheduled_nodes （type: gauge）	k8s.daemonset.node.current_scheduled （type: updowncounter）
k8s.daemonset.desired_scheduled_nodes （type: gauge）	k8s.daemonset.node.desired_scheduled （type: updowncounter）
k8s.daemonset.misscheduled_nodes （type: gauge）	k8s.daemonset.node.misscheduled （type: updowncounter）
k8s.daemonset.ready_nodes （type: gauge）	k8s.daemonset.node.ready （type: updowncounter）

K8s Jobのメトリクス

Collectorで実装されているK8s Jobのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクスの型の変更点は次のとおりです。

旧（Collector）	新
k8s.job.active_pods （type: gauge）	k8s.job.pod.active （type: updowncounter）
k8s.job.failed_pods （type: gauge）	k8s.job.pod.failed （type: updowncounter）
k8s.job.desired_successful_pods （type: gauge）	k8s.job.pod.desired_successful （type: updowncounter）
k8s.job.max_parallel_pods （type: gauge）	k8s.job.pod.max_parallel （type: updowncounter）

K8s Cronjobのメトリクス

Collectorで実装されているK8s Cronjobのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクスの型の変更点は次のとおりです。

旧（Collector）	新
k8s.cronjob.active_jobs （type: gauge）	k8s.cronjob.job.active （type: updowncounter）

K8s Namespaceのメトリクス

Collectorで実装されているK8s Namespaceのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、v1.30.0でセマンティック規約として導入されました。

そのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.namespace.phase （type: gauge）。activeは1、terminatingは0	k8s.namespace.phase （type: updowncounter）。フェーズを示すk8s.namespace.phase属性を伴う

K8s ResourceQuotaリソース

Collectorで実装されているK8s ResourceQuotaの属性、具体的にはk8sclusterレシーバーの属性は、v1.31.0でセマンティック規約として導入されました。

変更点は次のとおりです。

旧（Collector）	新
k8s.resource_quota.{name,uid}	k8s.resourcequota.{name,uid}

K8s ReplicationControllerリソース

Collectorで実装されているK8s Replication Controllerの属性、具体的にはk8sclusterレシーバーの属性は、v1.31.0でセマンティック規約として導入されました。

変更点は次のとおりです。

旧（Collector）	新
k8s.replication_controller.{name,uid}	k8s.replicationcontroller.{name,uid}

K8s Containerのメトリクス

Collectorで実装されているK8s Containerのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、以下でセマンティック規約として導入されました。

• #2178（TODO: SemConvのバージョンが利用可能になったら差し替える）
• #2074
• #2197
• #3558（CPUとメモリのリサイズ: desired/currentの分割）
• #3559（CPUメトリクス）
• #3646（メモリメトリクス）

そのメトリクスの変更点は次のとおりです。

旧（Collector）	新（SemConv）
k8s.container.cpu_limit（type: gauge）	k8s.container.cpu.limit.desired、k8s.container.cpu.limit.current（type: updowncounter）
k8s.container.cpu_request（type: gauge）	k8s.container.cpu.request.desired、k8s.container.cpu.request.current（type: updowncounter）
k8s.container.memory_limit（type: gauge）	k8s.container.memory.limit.desired、k8s.container.memory.limit.current（type: updowncounter）
k8s.container.memory_request（type: gauge）	k8s.container.memory.request.desired、k8s.container.memory.request.current（type: updowncounter）
k8s.container.storage_limit（type: gauge）	k8s.container.storage.limit（type: updowncounter）
k8s.container.storage_request（type: gauge）	k8s.container.storage.request（type: updowncounter）
k8s.container.ephemeralstorage_limit（type: gauge）	k8s.container.ephemeral_storage.limit（type: updowncounter）
k8s.container.ephemeralstorage_request（type: gauge）	k8s.container.ephemeral_storage.request（type: updowncounter）
k8s.container.restarts（type: gauge）	k8s.container.restart.count（type: updowncounter）
k8s.container.ready（type: gauge）	k8s.container.ready（type: updowncounter）
k8s.container.cpu_limit_utilization（type: gauge）	k8s.container.cpu.limit.utilization（type: gauge）
k8s.container.cpu_request_utilization（type: gauge）	k8s.container.cpu.request.utilization（type: gauge）

注: CPUとメモリのlimitおよびrequestについて、SemConvはそれぞれをdesired（specから取得）とcurrent（コンテナのstatusから取得）に分割しています。これは、K8sコンテナのリソースリサイズをサポートするためです。

K8s ResourceQuotaのメトリクス

Collectorで実装されているK8s ResourceQuotaのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、github.com/open-telemetry/semantic-conventions/pull/2113でセマンティック規約として導入されました。

これらのメトリクスは完全に再設計されました。変更点は次のとおりです。

旧（Collector）	新
k8s.resource_quota.hard_limit	k8s.resourcequota.{resource}.hard
k8s.resource_quota.used	k8s.resourcequota.{resource}.used
{resource}属性	種類ごとに異なるメトリクスへ分割

OpenShift ClusterResourceQuotaのメトリクス

Collectorで実装されているOpenShift ClusterResourceQuotaのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、github.com/open-telemetry/semantic-conventions/pull/2779でセマンティック規約として導入されました。

これらのメトリクスは完全に再設計されました。変更点は次のとおりです。

旧（Collector）	新
openshift.clusterquota.hard_limit	openshift.clusterquota.{resource}.hard
openshift.clusterquota.used	openshift.clusterquota.{resource}.used
{resource}属性	種類ごとに異なるメトリクスへ分割

K8s Nodeのconditionメトリクス

Collectorで実装されているK8s Nodeのconditionメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#2077でセマンティック規約として導入されました。

そのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.node.condition_*	k8s.node.condition.statusメトリクス [0,1]。異なるconditionを示すk8s.node.condition.type属性と、true/false/unknownを示すk8s.node.condition.status属性を伴う

K8s Filesystemのメトリクス

Collectorで実装されているK8s Filesystemのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#2392でセマンティック規約として導入されました。

そのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.node.filesystem.available gauge	k8s.node.filesystem.available updowncounter
k8s.node.filesystem.capacity gauge	k8s.node.filesystem.capacity updowncounter
k8s.node.filesystem.usage gauge	k8s.node.filesystem.usage updowncounter
k8s.pod.filesystem.available gauge	k8s.pod.filesystem.available updowncounter
k8s.pod.filesystem.capacity gauge	k8s.pod.filesystem.capacity updowncounter
k8s.pod.filesystem.usage gauge	k8s.pod.filesystem.usage updowncounter
container.filesystem.available gauge	container.filesystem.available updowncounter
container.filesystem.capacity gauge	container.filesystem.capacity updowncounter
container.filesystem.usage gauge	container.filesystem.usage updowncounter

K8s Pod Volumeのメトリクス

Collectorで実装されているK8s Pod Volumeのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#2319でセマンティック規約として導入されました。

これらのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.volume.available	k8s.pod.volume.available
k8s.volume.capacity	k8s.pod.volume.capacity
k8s.volume.inodes	k8s.pod.volume.inode.count
k8s.volume.inodes.free	k8s.pod.volume.inode.free
k8s.volume.inodes.used	k8s.pod.volume.inode.used

K8s Pod Memoryのメトリクス

Collectorで実装されているK8s Pod Memoryのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#1490でセマンティック規約として導入されました。

これらのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.pod.memory.page_faults	system.paging.fault.type属性をminorに設定したk8s.pod.paging.faults
k8s.pod.memory.major_page_faults	system.paging.fault.type属性をmajorに設定したk8s.pod.paging.faults

Containerのメモリメトリクス

Collectorで実装されているContainerのメモリメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#1490でセマンティック規約として導入されました。

これらのメトリクスの変更点は次のとおりです。

旧（Collector）	新
container.memory.page_faults	system.paging.fault.type属性をminorに設定したcontainer.paging.faults
container.memory.major_page_faults	system.paging.fault.type属性をmajorに設定したcontainer.paging.faults

K8s Nodeのメモリメトリクス

Collectorで実装されているK8s Nodeのメモリメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#1490でセマンティック規約として導入されました。

これらのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.node.memory.page_faults	system.paging.type属性をminorに設定したk8s.node.paging.faults
k8s.node.memory.major_page_faults	system.paging.type属性をmajorに設定したk8s.node.paging.faults

コンテナランタイム

コンテナランタイムは、v1.Y.Zでセマンティック規約に導入された変更により、より詳細になりました。

その属性の変更点は次のとおりです。

旧属性	新属性
container.runtime	container.runtime.name

K8s PodのStatus PhaseとReason

Collectorで実装されているK8s PodのStatus PhaseとReasonのメトリクス、具体的にはk8sclusterレシーバーのメトリクスは、#2075でセマンティック規約として導入されました。

そのメトリクスの変更点は次のとおりです。

旧（Collector）	新
k8s.pod.status_reason メトリクス [1,6]	異なるreasonを示すk8s.pod.status.reason属性を伴うk8s.pod.status.reasonメトリクス [0,1]
k8s.pod.phase メトリクス [1, 5]	異なるphaseを示すk8s.pod.phase属性を伴うk8s.pod.status.phaseメトリクス [0,1]

K8sのラベルとアノテーション

Collectorで実装されているK8sのラベルとアノテーションの属性、具体的にはk8sattributesプロセッサーの属性は、#625（Pod）、#2130（Node）、#2166（Namespace）でセマンティック規約として導入されました。

上記のレシーバーとは異なり、k8sattributesプロセッサーはOTEL_SEMCONV_STABILITY_OPT_IN環境変数ではなく、独自のフィーチャーゲートprocessor.k8sattributes.EmitV1K8sConventionsとprocessor.k8sattributes.DontEmitV0K8sConventionsによってこの移行を制御します。詳細は、プロセッサーのSemantic Conventions Compatibilityのドキュメントを参照してください。

これらの属性の変更点は次のとおりです。

旧（Collector）	新
k8s.pod.labels.<key>	k8s.pod.label.<key>
k8s.pod.annotations.<key>	k8s.pod.annotation.<key>
k8s.node.labels.<key>	k8s.node.label.<key>
k8s.node.annotations.<key>	k8s.node.annotation.<key>
k8s.namespace.labels.<key>	k8s.namespace.label.<key>
k8s.namespace.annotations.<key>	k8s.namespace.annotation.<key>

K8s Pod/Nodeおよびコンテナのメモリ使用量

Collectorで実装されているメモリ使用量のメトリクス、具体的にはkubeletstatsレシーバーのメトリクスは、プロジェクト全体の整合性を取るため#3889でInstrumentの型が変更されました。

変更点は次のとおりです。

旧（Collector）	新
k8s.pod.memory.usage gauge	k8s.pod.memory.usage updowncounter
k8s.node.memory.usage gauge	k8s.node.memory.usage updowncounter
container.memory.usage counter	container.memory.usage updowncounter