企业官网建设流程全解析

Kubernetes SIG Instrumentation 2023 年度报告全解读：从指标稳定性到链路追踪的可观测性演进

【免费下载链接】communityKubernetes Community Documentation项目地址: https://gitcode.com/GitHub_Trending/com/community

本篇文章以 SIG Instrumentation 2023 年度报告 为核心骨架，结合本仓库中该 SIG 的 宪章、README、指标稳定性规范、指标埋点指南、结构化日志指南 以及 sigs.yaml 中的子项目清单，系统梳理 Kubernetes 可观测性基石组件在 2023 年（对应 v1.27、v1.28、v1.29 三个发布周期）的关键进展。读完本文，你将掌握 SIG Instrumentation 的职责边界、当年六个核心 KEP 的技术内涵与毕业节奏、新增子项目 usage-metrics-collector 的定位，以及该 SIG 子项目与社区健康的全貌。

SIG Instrumentation 的职责：集群可观测性的"共建者"

在展开年度进展之前，先明确这个 SIG 在整个 Kubernetes 生态中的定位。根据 charter.md，SIG Instrumentation 的使命是：

通过指标（metrics）、日志（logging）、事件（events）和追踪（traces）四种信号，为所有 Kubernetes 组件定义集群可观测性的最佳实践，并开发所有集群都需要的相关组件（如 klog、kube-state-metrics）。

值得注意的是其边界：对非本 SIG 拥有的组件进行埋点不属于其职责范围，但它负责为任何贡献者提供埋点决策咨询，并通过寻找公共 API（如 resource/core metrics、custom metrics、external metrics API）来协调不同 SIG 对其它组件的指标需求。信号的处理（如把指标、日志摄入外部系统）也不在范围内。这一"共建者"定位解释了为何年度报告的主角是 KEP 毕业与公共组件，而非具体的监控后端。

2023 年度工作亮点：四项 KEP 毕业与一个新子项目

年度报告的第一部分列举了 2023 年最值得关注的工作，共五项：

1. 启动 SIG Instrumentation 导师计划（Mentorship Program）——目标是吸引并留住新贡献者；
2. 引入新子项目usage-metrics-collector，用于采集 kube 使用量与容量指标；
3. APIServer Tracing毕业到 stable；
4. Dynamic Cardinality Enforcement（动态基数限制）毕业到 stable；
5. Extending Metrics Stability（扩展指标稳定性）毕业到 beta；
6. Kubernetes Components Health SLIs（控制面组件健康 SLI）毕业到 stable。

这四项 KEP 毕业分别触及了 trace、metrics 两条可观测性主线的核心能力，下文会在 KEP 工作全景中逐一展开技术细节。而导师计划的启动与 usage-metrics-collector 的引入，则分别对应社区人力建设与子项目版图的扩张，同样会在后续章节详述。

2023 年 KEP 工作全景（v1.27 / v1.28 / v1.29）

年度报告第四部分给出了当年三个发布周期内推进的 KEP 清单，分为 Beta 与 Stable 两档。这是理解该 SIG 一年技术产出的关键表格，完整继承如下：

Beta 档（当年达到 Beta 里程碑）

Stable 档（当年达到 Stable 里程碑）

从这张表可以清晰看到该 SIG 一年的技术主线：一条线是 metrics（指标稳定性扩展、基数限制、Pod 资源指标），另一条线是 traces（API Server 与 Kubelet 的 OpenTelemetry 追踪），外加控制面组件健康 SLI。下面结合仓库内文档逐一展开。

APIServer Tracing 与 Kubelet OpenTelemetry Tracing：控制面组件级链路追踪就绪

这两个 KEP 一脉相承：为 Kubernetes 控制面的两个核心组件引入基于 OpenTelemetry 规范的链路追踪能力，让集群管理员能把 API Server 的请求处理链路、Kubelet 的 gRPC 调用链路接入统一的分布式追踪系统。2023 年，APIServer Tracing 在 v1.27 达到 beta（对应 KEP 647），并进一步毕业到 stable；Kubelet Tracing 则在 v1.28 达到 stable（对应 KEP 2831）。从 2022 年度报告 可以看到，这两个能力彼时已进入 beta，2023 年属于持续推进至稳定。

其底层依赖的是 k8s-trace-instrumenter.md 与 k8s-trace-reviewer.md 两份开发文档所描述的工具链与审查规范，用于辅助开发者对代码自动注入追踪埋点，并保证追踪代码的审查质量。

Dynamic Cardinality Enforcement：给指标基数戴上"安全帽"

KEP 2305 解决的是监控系统中长期存在的指标基数爆炸问题：当某个指标的标签组合无限增长（例如把用户 ID、错误信息等"外部标签"直接打进指标里），下游监控系统的内存与查询性能会被拖垮。该 KEP 在 v1.28 达到 beta 并在当年毕业到 stable，为 Kubernetes 组件提供了动态的基数限制能力——当指标基数超过阈值时，服务端可以按策略进行限制或截断。

这与仓库中 metric-instrumentation.md 的埋点规范一脉相承：该文档明确警告"常见错误是考虑那些过于具体、从而破坏时间聚合的维度，典型的是用户 ID 或错误信息"，并要求"在埋点时就应该知道某个标签所有可能的取值全集"。动态基数限制正是为这种失控场景兜底的运行时机制。此外，文档还指出 pod 名、节点名、命名空间这类"外部标签"通常不应进入组件自身的埋点（kube-state-metrics 是例外），而应由采集端附加——这正是基数治理的第一道防线。

Kubernetes Component Health SLIs：让"组件健康"可以量化

KEP 3466 为 Kubernetes 控制面组件（如 kube-apiserver、kube-controller-manager、kube-scheduler、kubelet 等）定义了标准化的健康指标 SLI（Service Level Indicator），在 v1.29 达到 stable。它把"组件是否健康"从模糊的定性判断转化为可聚合、可告警的量化指标，为集群管理员与 SRE 提供了统一的健康观测口径。

Expose Pod Resource Request Metrics：从使用量到"期望值"

KEP 1748 在 v1.27 达到 stable，其目标是把 Pod 的资源请求（requests）与限制（limits）以指标形式暴露出来。这一能力补全了资源观测的视角：此前 metrics-server 提供的是实际使用量（usage），而调度、配额与容量规划往往还依赖声明的期望值（request/limit）。两者结合，才能回答"集群里真正被预留了多少资源"这类问题。这也呼应了 SIG 宪章中关于 core metrics pipeline（供调度器、kubectl 与自动扩缩容消费的指标链路）的定位。

Extending Metrics Stability：把稳定性契约从指标扩展到更多维度

KEP 3498 是对 KEP-1209 指标稳定性框架 的扩展。2023 年度报告的高亮部分记录其毕业到 beta，KEP 清单中则列出其在 v1.28 推进至 stable 档（两处记录分别反映了当年不同阶段的里程碑状态）。要理解这个 KEP 的意义，需要先掌握指标稳定性框架的核心机制。

根据仓库中的 metric-stability.md，Kubernetes 指标共分四档稳定性等级：

• Alpha：没有任何稳定性保证，可随时修改或删除，所有新指标都从这一档起步；
• Beta：契约较宽松——生命周期内不得删除标签，但可以新增标签；可以标记 deprecated；不得删除或修改指标类型；
• Stable：保证"不变化"——未经至少 3 个发布（或 9 个月，取较长者）的弃用期不得删除或重命名；类型不可修改；标签既不能新增也不能删除；
• Internal：仅供内部使用的指标，与 Alpha 类似无稳定性保证，但显式标记为非公共 API。

配套的弃用生命周期为：Stable metric -> Deprecated metric -> Hidden metric -> Deletion。弃用后的指标描述文本会被加上(Deprecated since x.y)前缀并发出告警日志；经过弃用期后会变为 hidden，不再自动注册到指标端点，但管理员可以通过--show-hidden-metrics-for-version=<previous minor release>参数显式启用，作为迁移的"逃生舱"。

指标埋点的落地路径在 metric-instrumentation.md 中有完整示例，例如使用k8s.io/component-base/metrics定义并注册一个 stable 级别的请求计数器：

requestCounter = compbasemetrics.NewCounterVec( &compbasemetrics.CounterOpts{ Name: "apiserver_request_total", Help: "Counter of apiserver requests broken out for each verb, dry run value, group, version, resource, scope, component, and HTTP response code.", StabilityLevel: compbasemetrics.STABLE, }, []string{"verb", "dry_run", "group", "version", "resource", "subresource", "scope", "component", "code"}, ) // 注册到 legacyregistry legacyregistry.MustRegister(requestCounter) // 使用指标 requestCounter.WithLabelValues(*verb, *resource, client, strconv.Itoa(*httpCode)).Inc()

该文档还规定了从 Alpha 毕业到 Beta、再从 Beta 毕业到 Stable 的硬性要求：毕业到 Beta需通过用例验证、遵循 Prometheus 命名规范、确认指标基数有界、具备行为级测试、进入 stable metrics 列表，并需 SIG Instrumentation 做 API 审查；毕业到 Stable则额外要求指标至少在 Beta 档停留两个发布周期，且需所属 SIG leads 与 SIG Instrumentation 双重批准。这与 2023 年多项指标类 KEP 密集毕业的节奏形成了完整的因果闭环——正是这套契约框架的成熟，才支撑起了当年的稳定化进程。

新增子项目 usage-metrics-collector：采集"使用量与容量"

年度报告的子项目部分标记了 2023 年的版图变化：新增 usage-metrics-collector，其余子项目继续推进。该子项目（kubernetes-sigs 组织下）的目标是采集集群的资源使用量（usage）与容量（capacity）指标，与 metrics-server 提供的实时使用量形成互补——它更多面向容量规划与长期趋势分析场景。在 sigs.yaml 中，usage-metrics-collector 被登记为 SIG Instrumentation 的正式子项目，拥有独立的 OWNERS 文件。

子项目全景与社区健康：哪些地方最需要帮助

年度报告的子项目清单完整列出了 SIG 的职责版图。结合 README.md 与 sigs.yaml，2023 年继续运营的子项目包括：

• custom-metrics-apiserver：自定义指标 API 的参考实现框架，外部系统（如 Prometheus）通过它把指标以 Custom Metrics API 的形式暴露给 Kubernetes；
• instrumentation / instrumentation-addons / instrumentation-tools：SIG 组织协调层及配套工具；
• klog：Kubernetes 官方日志库（glog 的长期维护分支），正在向 logr 接口平滑迁移；
• kube-state-metrics：从 API Server 读取对象状态并暴露为kube_*前缀指标（业务逻辑类指标）；
• metric-stability-framework：即k8s.io/component-base/metrics，指标稳定性框架的实现载体；
• metrics：k8s.io/metrics公共指标 API 及配套仓库；
• metrics-server：核心指标管道（resource metrics API）的参考实现，服务调度器、kubectl top 与 HPA；
• prometheus-adapter：Prometheus 与 Custom/External Metrics API 之间的适配器；
• structured-logging：结构化日志改造相关的组件集合。

此外，WGStructured Logging作为关联工作组继续运转。

报告第二部分明确点名了三个活跃 OWNERS 不足（少于 2 位）、最需要外部支援的子项目：

• kubernetes-sigs/custom-metrics-apiserver
• kubernetes-sigs/metrics-server
• kubernetes-sigs/prometheus-adapter

这三个恰好都是指标 API 管道上的关键节点——metrics-server、custom-metrics-apiserver、prometheus-adapter。对于想参与 Kubernetes 可观测性生态的开发者，它们是当前投入产出比最高的切入点。从 2022 年度报告 可以看到，这三个子项目的 OWNERS 短缺问题已持续存在（prometheus-adapter 曾只有 1 位活跃 approver、metrics-server 的 approver 均已过时），2023 年依然被列为需要帮助的对象，属于该 SIG 持续性的治理痛点。

社区建设：导师计划与 KubeCon 发声

年度报告同时记录了该 SIG 在社区层面做的两件事：

1. SIG Instrumentation Mentorship Program：2023 年启动的导师计划，目标是吸引并留存新贡献者。对于上文提到的 OWNERS 短缺问题，这是从人力源头上的应对举措——通过结构化辅导降低新人进入 klog、kube-state-metrics、metrics-server 等子项目的门槛。此前 2022 年度报告 也提到"我们有导师计划，并且已经招收学员/导师"，可见该计划在 2023 年正式落地成型。
2. KubeCon NA '23 社区分享：SIG 在 KubeCon North America 2023 上做了 "SIG Instrumentation Introduction and Deep Dive" 的演讲，向整个云原生社区同步进展。

持续运转的工作组：Structured Logging

报告标记 WG Structured Logging 在 2023 年继续运转。结合 logging.md 可以看到该工作组的完整技术脉络：Kubernetes 正在从传统 klog 的 C 风格格式化日志迁移到基于 logr 接口的结构化日志与上下文日志（Contextual Logging）。核心调用范式是klog.InfoS/klog.ErrorS（及带 verbosity 的klog.V(n).InfoS），例如：

klog.InfoS("Received HTTP request", "method", "GET", "URL", "/metrics", "latency", time.Second)

而 klog 的职责被收窄为"管理日志配置（SetLogger、获取 logger）"，传统klog.Infof等非结构化方法不再推荐使用。日志格式上，text 格式（默认，保持与 klog 后向兼容）与 JSON 格式（--logging-format=json启用，机器可读、支持logr.MarshalLog结构化元数据）并行支持。具体迁移步骤可参考 migration-to-structured-logging.md。

年度运营自检：治理与文档的例行维护

年度报告末尾的 Operational 部分记录了 SIG 依 sig-governance.md 完成的年度例行运营任务，全部勾选完成：

• 审阅并更新 README.md；
• 审阅并更新 CONTRIBUTING.md 及其它贡献文档（devel 目录与贡献者指南）；
• 审阅并更新 sigs.yaml 中的子项目列表及其关联的 OWNERS 文件；
• 确认 sigs.yaml 中登记的 SIG 负责人（chairs、tech leads、subproject leads）准确且活跃；
• 确保 2023 年的会议纪要与会话记录已从 README.md 正确链接。

值得一提的是，README.md 的头部注明该文件是自动生成的，对它的修改应提交到根目录的 sigs.yaml 而非直接编辑文件本身，生成机制见 generator 目录。这也是阅读该 SIG 各类"列表类"文档时的重要背景知识。

总结：2023 年是把契约与管道做"实"的一年

综合来看，SIG Instrumentation 的 2023 年可以概括为三条主线：

1. 契约成熟：以 Extending Metrics Stability（KEP 3498）和 Dynamic Cardinality Enforcement（KEP 2305）为代表，指标从"能埋"走向"有界、有承诺、可治理"，配合仓库内 metric-stability.md 与 metric-instrumentation.md 形成完整的开发-审查-毕业闭环；
2. 追踪落地：APIServer Tracing 与 Kubelet OpenTelemetry Tracing 双双走向稳定，控制面组件级链路追踪成为可开箱即用的能力；
3. 社区与版图扩张：导师计划启动、usage-metrics-collector 子项目落地，同时通过 KubeCon 演讲与年度运营自检维持治理健康。

对于想要深入参与 Kubernetes 可观测性建设的读者，本仓库内 sig-instrumentation 目录下的年度报告、charter、README 与 devel 开发文档 是体系化的入口；而 metrics-server、custom-metrics-apiserver、prometheus-adapter 这三个亟需 OWNERS 的子项目，则是贡献者当前最值得关注的落点。

【免费下载链接】communityKubernetes Community Documentation项目地址: https://gitcode.com/GitHub_Trending/com/community