K8s 语义约定稳定性迁移

K8s 语义约定的稳定性仍在开发中。本指南收集了在此过程中发生的重大更改，以便用户可以提前了解即将发生的更改。

由于修改数量庞大且受影响的用户众多，OpenTelemetry发布的现有 K8s 仪器需要实施迁移计划，以协助用户过渡到稳定的 K8s 语义约定。

当 OpenTelemetry发布的现有 K8s 仪器更新到稳定的 K8s 语义约定后，它们

• 应在其现有主版本中引入一个名为 OTEL_SEMCONV_STABILITY_OPT_IN 的环境变量，该变量接受
  • k8s - 发出稳定的 k8s 约定，并停止发出该仪器先前发出的旧 k8s 约定。
  • k8s/dup - 同时发出旧的和稳定的 k8s 约定，允许分阶段推出稳定的语义约定。
  • 默认行为（如果没有这些值之一）是继续发出该仪器先前发出的任何版本的旧 k8s 约定。
• 需要维护（至少包括安全修补）其现有主版本，自开始同时发出两套约定之日起至少六个月。
• 可以在其下一个主版本中删除该环境变量，并仅发出稳定的 k8s 约定。

特别是对于 OpenTelemetry Collector

过渡将通过两个不同的功能门来实现。一个用于启用新模式，名为 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 节点可分配指标

Collector 实现的 K8s 节点可分配指标，特别是 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 StatefulsSet 指标

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)，1 表示活动，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

其指标的更改如下：

旧（Collector）	新
k8s.container.cpu_limit (type: gauge)	k8s.container.cpu.limit (type: updowncounter)
k8s.container.cpu_request (type: gauge)	k8s.container.cpu.request (type: updowncounter)
k8s.container.memory_limit (type: gauge)	k8s.container.memory.limit (type: updowncounter)
k8s.container.memory_request (type: gauge)	k8s.container.memory.request (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)

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]，带有 k8s.node.condition.type 属性指示不同的条件，以及 k8s.node.condition.status 属性指示 true/false/unknown。

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	k8s.pod.memory.paging.faults，属性 system.paging.fault.type 设置为 minor
k8s.pod.memory.major_page_faults	k8s.pod.memory.paging.faults，属性 system.paging.fault.type 设置为 major

Container memory 指标

Collector 实现的 Container memory 指标，特别是 k8scluster 接收器，在 #1490 中被引入为语义约定。

这些指标的更改如下：

旧（Collector）	新
container.memory.page_faults	container.memory.paging.faults，属性 system.paging.fault.type 设置为 minor
container.memory.major_page_faults	container.memory.paging.faults，属性 system.paging.fault.type 设置为 major

K8s Node memory 指标

Collector 实现的 K8s Node memory 指标，特别是 k8scluster 接收器，在 #1490 中被引入为语义约定。

这些指标的更改如下：

旧（Collector）	新
k8s.node.memory.page_faults	k8s.node.memory.paging.faults，属性 system.paging.type 设置为 minor
k8s.node.memory.major_page_faults	k8s.node.memory.paging.faults，属性 system.paging.type 设置为 major

Container Runtime

在 v1.Y.Z 中的语义约定更改后，container runtime 变得更具描述性。

其属性的更改如下：

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

K8s Pod Status Phase and Reason

Collector 实现的 K8s Pod Status Phase and Reason 指标，特别是 k8scluster 接收器，在 #2075 中被引入为语义约定。

其指标的更改如下：

旧（Collector）	新
k8s.pod.status_reason 指标 [1,6]	k8s.pod.status.reason 指标 [0,1]，带有指示不同原因的属性 k8s.pod.status.reason
k8s.pod.phase 指标 [1, 5]	k8s.pod.status.phase 指标 [0,1]，带有指示不同阶段的属性 k8s.pod.phase