3. 可观测性三大支柱在升级场景的应用：指标、日志与链路如何覆盖升级事件

Kubernetes 集群升级是一个典型的“状态机”过程：从预检、控速、节点排空、组件替换到后验证，每一步都可能引入故障。单一数据源无法完整描述升级的“健康度”。可观测性的三大支柱——指标（Metrics）、日志（Logs）、链路（Traces）——分别从聚合统计、事件记录和请求因果三个维度覆盖升级事件，形成互补的观测网格。

3.1 三大支柱在升级场景中的角色矩阵

下表从数据特征、升级事件覆盖范围、典型工具三个维度对比三大支柱在升级场景中的分工：

3.2 指标（Metrics）：升级过程的“仪表盘”

指标是升级过程中最直接的“健康信号”。通过预定义的聚合指标，运维团队可以实时判断升级是否在安全边界内运行。核心指标分为三类：

• 进度类指标：已升级节点数、剩余节点数、当前批次完成率。
• 风险类指标：节点排空失败率、Pod 驱逐超时次数、API Server 错误率（5xx）。
• 资源类指标：节点内存/CPU 使用率、etcd 磁盘空间、控制平面组件重启次数。

以下是一个典型的升级进度 Prometheus 记录规则示例：

# 记录每个升级批次的节点状态
- record: upgrade:node_phase_total
  expr: count by (upgrade_id, phase) (kube_node_info{phase=~"draining|upgrading|restarting|completed"})

# 记录排空失败率（5分钟滑动窗口）
- record: upgrade:drain_failure_ratio
  expr: |
    sum(rate(upgrade_drain_failure_total[5m]))
    /
    (sum(rate(upgrade_drain_attempt_total[5m])) > 0)

3.3 日志（Logs）：升级事件的“黑匣子”

日志提供了升级过程中最细粒度的上下文。当指标显示异常时，日志是定位根因的第一入口。升级场景中需要重点采集的日志源包括：

• kubelet 日志：节点排空、Pod 驱逐、容器重启事件。
• kube-apiserver 日志：认证失败、资源冲突、Webhook 调用超时。
• 集群升级控制器日志：批次决策、控速逻辑、回滚触发条件。
• 节点初始化脚本日志：包管理器输出、kubelet 启动参数变更。

日志结构化是升级可观测性的关键。推荐使用 JSON 格式并包含以下字段：

{
  "timestamp": "2025-03-21T14:30:00Z",
  "upgrade_id": "ug-20250321-v1.28-v1.29",
  "node": "worker-03",
  "phase": "draining",
  "event": "pod_eviction_timeout",
  "pod": "nginx-abc123",
  "namespace": "production",
  "duration_seconds": 300,
  "error": "PodDisruptionBudget 'pdb-nginx' minAvailable violation"
}

3.4 链路（Traces）：升级影响的“因果链”

链路追踪在升级场景中常被忽视，但它恰恰是理解“升级导致服务降级”因果关系的唯一手段。升级过程中，组件版本变更、Webhook 配置更新、API 版本废弃都会改变请求路径。链路追踪可以回答以下问题：

• 升级后，某个请求是否因为 API 版本不匹配而失败？
• MutatingWebhookConfiguration 更新后，Pod 创建请求的延迟是否增加？
• 控制平面升级期间，etcd 写入延迟是否影响了所有写请求？

以下是一个升级场景下的链路追踪上下文传播示例（OpenTelemetry）：

// 在升级控制器中创建根 Span
tracer := otel.Tracer("upgrade-controller")
ctx, span := tracer.Start(context.Background(), "node-upgrade",
    trace.WithAttributes(
        attribute.String("upgrade.id", "ug-20250321-v1.28-v1.29"),
        attribute.String("node.name", "worker-03"),
        attribute.String("phase", "draining"),
    ),
)
defer span.End()

// 在排空操作中创建子 Span
drainCtx, drainSpan := tracer.Start(ctx, "drain-node")
// 执行排空逻辑...
drainSpan.SetAttributes(
    attribute.Int("pods.evicted", 12),
    attribute.Int("pods.failed", 1),
)
drainSpan.End()

3.5 三大支柱的协同覆盖模型

下图展示了指标、日志、链路如何协同覆盖一次完整的节点升级事件生命周期：

3.6 升级事件统一标签体系

要实现三大支柱的协同，必须建立统一的标签（Label / Tag）体系。推荐的最小标签集如下：