GKE TPU 指标监控与故障排查指南：基于 GKE System Metrics 与 PromQL 的 TPU 工作负载观测

GKE TPU 指标监控与故障排查指南：基于 GKE System Metrics 与 PromQL 的 TPU 工作负载观测

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

导读

本文基于开源仓库 gke-ai-troubleshooting-tpu-metrics-monitoring 技能文档，系统讲解如何借助 GKE System Metrics（GKE 系统指标）与 PromQL 查询，对 GKE 上的 TPU 工作负载、节点与节点池进行持续监控与故障排查。文章覆盖从「验证 TPU 运行时指标配置」到「计算 MTTR/MTBI 可靠性指标」的完整 8 步诊断流程，读者学完后将能够：确认集群是否具备 TPU 指标导出能力、识别 TensorCore 利用率与 TPU 内存水位、判定节点与多主机节点池的健康状态、按类型与原因分析节点中断事件，并基于指标签名快速定位基础设施层面的根因。

前置条件与适用边界

本技能适用于 GKE 上 TPU（Tensor Processing Unit）工作负载的指标驱动监控与排障，典型场景包括：

• 监控 TensorCore 占空比（duty cycle）与 TPU 内存使用情况；
• 检查节点就绪（Ready）状态与多主机 TPU 节点池可用性；
• 分析主机维护（maintenance）或抢占（preemption）造成的中断；
• 计算 MTTR（Mean Time to Recovery）与 MTBI（Mean Time Between Interruptions）等可靠性指标。

不适用场景：通用非 TPU 的 GKE 工作负载监控（应使用 gke-basics 等基础技能）、以及非指标驱动的 TPU 调试（如日志类排障可参考仓库中 gke-ai-troubleshooting-tpu-vbar-oom 等配套技能）。

必需上下文变量

在开始任何查询前，需要先独立收集（可通过现有 GKE 与 Cloud 工具获取）以下上下文，或直接使用占位符替换：

变量	含义	是否必填
{project_id}	GCP 项目 ID	必填
{cluster_name}	GKE 集群名称	必填
{location}	GKE 集群所在地域或可用区	必填
{node_name}	具体 GKE 节点名称	可选
{node_pool_name}	GKE 节点池名称	可选

Step 1：验证 TPU 运行时指标配置

在分析运行时指标之前，必须确认工作负载已正确配置以导出这些指标，从而保证集群与容器环境具备自动抓取能力，并可观测到加速器健康状况。需要核对的先决条件如下：

• 容器端口：TPU 容器必须暴露containerPort: 8431（Prometheus 指标抓取所必需）；
• JAX 版本：若使用 JAX，版本需为0.4.14或更高（更早版本不会导出运行时指标）；
• GKE 版本：集群版本需为1.27.4-gke.900或更高（TPU 运行时指标支持的前提）；
• GKE System Metrics：集群需已启用 GKE 系统指标（供 Cloud Monitoring 摄取）。

这些版本门槛直接决定了后续查询能否取到数据，属于「先配置、后观测」的硬性前置条件。

Step 2：监控 TPU 运行时指标

配置正确后，以下指标即可在 Cloud Monitoring 中查询到，监控资源（monitored resources）为k8s_node与k8s_container。

容器级指标

指标	说明
kubernetes.io/container/accelerator/duty_cycle	过去采样周期（60 秒）内 TPU 芯片上 TensorCore 处于活跃处理状态的时间百分比
kubernetes.io/container/accelerator/memory_used	已分配的加速器内存字节数
kubernetes.io/container/accelerator/memory_total	加速器总内存字节数

节点级指标

指标	说明
kubernetes.io/node/accelerator/duty_cycle	节点维度 TensorCore 占空比
kubernetes.io/node/accelerator/memory_used	节点维度已用加速器内存
kubernetes.io/node/accelerator/memory_total	节点维度加速器总内存

低利用率签名解读

结合仓库中 failure_signatures.md 的故障签名定义：当duty_cycle或tensorcore_utilization在训练活跃期间长期低于0.2（20%），说明 TPU 严重利用不足，大概率是数据瓶颈或 batch size 过小所致，应从数据管线与训练配置层面排查，而非基础设施。

Step 3：检查节点状态条件

对于 GKE 版本1.32.1-gke.1357001或更高，可通过kubernetes_io:node_status_condition系列查询节点状态条件。

查询特定节点是否 Ready

kubernetes_io:node_status_condition{monitored_resource="k8s_node", cluster_name="{cluster_name}", node_name="{node_name}", condition="Ready", status="True"}

列出处于非 Ready 条件且状态为 True 的节点

kubernetes_io:node_status_condition{monitored_resource="k8s_node", cluster_name="{cluster_name}", condition!="Ready", status="True"}

列出 NOT Ready 的节点

kubernetes_io:node_status_condition{monitored_resource="k8s_node", cluster_name="{cluster_name}", condition="Ready", status="False"}

集群全域（Fleet-wide）节点状态概览

avg by (condition,status)(avg_over_time(kubernetes_io:node_status_condition{monitored_resource="k8s_node"}[5m]))

节点未就绪签名

根据 failure_signatures.md：

• 指标：kubernetes.io/node/status_condition
• 签名：condition="Ready"、status="False"（或status="Unknown"）
• 含义：承载 TPU 的 GKE 节点不健康，该节点上的工作负载将被打断。

Step 4：检查节点池状态

针对多主机（multi-host）TPU 节点池，查询kubernetes_io:node_pool_status系列指标。

验证指定节点池是否 Running

kubernetes_io:node_pool_status{monitored_resource="k8s_node_pool", cluster_name="{cluster_name}", node_pool_name="{node_pool_name}", status="Running"}

按状态分组的节点池监控

count by (status)(count_over_time(kubernetes_io:node_pool_status{monitored_resource="k8s_node_pool"}[5m]))

可能的节点池状态：Provisioning、Running、Error、Reconciling、Stopping。

节点池错误签名

根据 failure_signatures.md：

• 指标：kubernetes.io/node_pool/status
• 签名：status="Error"
• 含义：多主机 TPU 节点池遇到错误（例如置备失败）。

Step 5：检查节点池可用性

查询多主机 TPU 节点池中所有节点是否可用，使用kubernetes_io:node_pool_multi_host_available指标：

avg by (node_pool_name)(avg_over_time(kubernetes_io:node_pool_multi_host_available{monitored_resource="k8s_node_pool", cluster_name="{cluster_name}"}[5m]))

取值含义：1（True，所有节点可用）或0（False，部分节点不可用）。多主机 TPU 通常依赖拓扑互联，任意一个节点不可用都可能拖垮整个切片训练，因此该指标是判断训练是否中断的关键信号。

Step 6：分析节点中断

通过kubernetes_io:node_interruption_count与kubernetes_io:node_pool_interruption_count查询 GKE 节点的中断计数。

中断类型与原因明细

sum by (interruption_type,interruption_reason)(sum_over_time(kubernetes_io:node_interruption_count{monitored_resource="k8s_node"}[5m]))

• 中断类型（Interruption Types）：TerminationEvent（终止事件）、MaintenanceEvent（维护事件）、PreemptionEvent（抢占事件）
• 中断原因（Interruption Reasons）：HostError（主机错误）、Eviction（驱逐）、AutoRepair（自动修复）

仅过滤主机维护（Host Maintenance）事件

sum by (interruption_type,interruption_reason)(sum_over_time(kubernetes_io:node_interruption_count{monitored_resource="k8s_node", interruption_reason="HW/SW Maintenance"}[5m]))

按节点池聚合的中断计数

sum by (node_pool_name,interruption_type,interruption_reason)(sum_over_time(kubernetes_io:node_pool_interruption_count{monitored_resource="k8s_node_pool", interruption_reason="HW/SW Maintenance", node_pool_name="{node_pool_name}"}[5m]))

抢占与主机错误签名

结合 failure_signatures.md 对中断结果进行判读：

• 节点抢占签名：interruption_type="PreemptionEvent"—— 节点被抢占（常见于 Spot VM），工作负载需要重新调度；
• 主机错误签名：interruption_type="TerminationEvent"且interruption_reason="HostError"—— 底层物理主机发生硬件错误，GKE 应触发 AutoRepair。

若查询结果中interruption_reason="HW/SW Maintenance"的计数大于 0，说明底层 Compute Engine VM 因计划内主机维护被中断。更详细的维护事件排查流程可参考仓库配套技能 gke-ai-troubleshooting-handle-disruption-gpu-tpu。

Step 7：计算恢复与中断可靠性指标

基于最近 7 天的数据，计算 MTTR（平均恢复时间）与 MTBI（平均中断间隔）。

MTTR：平均恢复时间

sum(sum_over_time(kubernetes_io:node_pool_accelerator_times_to_recover_sum{monitored_resource="k8s_node_pool", cluster_name="{cluster_name}"}[7d])) / sum(sum_over_time(kubernetes_io:node_pool_accelerator_times_to_recover_count{monitored_resource="k8s_node_pool",cluster_name="{cluster_name}"}[7d]))

该公式用「恢复时间总和 ÷ 恢复事件次数」计算节点池加速器的平均恢复时长。

MTBI：平均中断间隔

sum(count_over_time(kubernetes_io:node_memory_total_bytes{monitored_resource="k8s_node", node_name=~"gke-tpu.*|gk3-tpu.*", cluster_name="{cluster_name}"}[7d])) / sum(sum_over_time(kubernetes_io:node_interruption_count{monitored_resource="k8s_node", node_name=~"gke-tpu.*|gk3-tpu.*", cluster_name="{cluster_name}"}[7d]))

该公式用「观测时间窗口内的采样次数 ÷ 中断次数」估算平均中断间隔，其中node_name=~"gke-tpu.*|gk3-tpu.*"正则用于限定 TPU 节点命名前缀（gke-tpu与gk3-tpu），避免把非 TPU 节点计入分母。

Step 8：监控 TPU 主机指标

对于 GKE 版本1.28.1-gke.1066000或更高，可进一步监控 TPU 主机（host）的性能表现。

容器级指标

指标	说明
kubernetes.io/container/accelerator/tensorcore_utilization	当前 TensorCore 利用率百分比
kubernetes.io/container/accelerator/memory_bandwidth_utilization	当前加速器内存带宽利用率百分比

节点级指标

指标	说明
kubernetes.io/node/accelerator/tensorcore_utilization	节点维度 TensorCore 利用率
kubernetes.io/node/accelerator/memory_bandwidth_utilization	节点维度内存带宽利用率

该组指标与 Step 2 的duty_cycle一起，构成判断「TPU 是否真正跑满」的双重视角：duty_cycle反映时间维度上的活跃占比，tensorcore_utilization反映瞬时算力占用，二者结合可区分「计算单元闲置」与「算力未打满」两种瓶颈形态。

配套脚本与验证方式

本技能在仓库中附带 validate_queries.sh 校验脚本。运行方式为：

export PROJECT_ID="{project_id}" bash skills/cloud/gke-ai-troubleshooting-tpu-metrics-monitoring/scripts/validate_queries.sh

脚本逻辑说明：

• 要求显式设置PROJECT_ID环境变量，未设置时直接报错退出（避免误用gcloud默认项目）；
• 由于本技能定位为「纯指标（PromQL）驱动的观测」，不包含 Cloud Logging LQL 查询，脚本会打印No Cloud Logging LQL queries defined in this skill to validate.并跳过日志查询校验；
• 脚本以set -e严格模式运行，任何非预期失败都会中断执行，便于在 CI 中早期发现问题。

对比参考：仓库中 gke-ai-troubleshooting-jobset-interruption 的校验脚本则通过curl调用 Cloud Monitoring Prometheus API 对 PromQL 做编译期 dry-run，说明此类技能普遍遵循「查询模板 + 脚本校验」的可维护模式。

典型排查路径总结

综合上述 8 个步骤，一套完整的基础设施根因排查路径如下：

1. 确认数据通路：核对containerPort: 8431、JAX ≥0.4.14、GKE ≥1.27.4-gke.900、GKE System Metrics 已启用（Step 1）；
2. 判断是「性能问题」还是「可用性问题」：先用duty_cycle/tensorcore_utilization判断 TPU 是否被有效利用（Step 2、Step 8），低于 20% 优先查数据管线；
3. 逐层定位中断来源：节点层查node_status_condition（Step 3）→ 节点池层查node_pool_status与node_pool_multi_host_available（Step 4、Step 5）→ 事件层查node_interruption_count按类型/原因细分（Step 6）；
4. 量化影响并持续观测：用 MTTR / MTBI 评估恢复速度与中断频率（Step 7），为容量规划与调度策略（如 Reserved/On-Demand、Compact Placement）提供数据依据。

整个流程完全基于 GKE System Metrics 与 PromQL，无需在集群中部署额外采集器，即可形成从「单点故障确认」到「长期可靠性量化」的完整闭环。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills