gke-ai-troubleshooting-tpu-metrics-monitoring

GKE TPU 指标监控指南

此技能可让 Agent 使用 GKE 系统指标监控 GKE TPU 工作负载、节点和节点池，帮助诊断工作负载中断或性能问题是否由底层基础设施导致。

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-ai-troubleshooting-tpu-metrics-monitoring)"，并将 agent-skills/1.0 (skill:gke-ai-troubleshooting-tpu-metrics-monitoring) 添加到 User-Agent 标头中。

步骤 0：必要上下文

使用可用的 GKE 和 Cloud 工具独立收集所需上下文（例如集群详情或节点池名称），或使用提供的 {variable} 占位符：

• {project_id}：GCP 项目 ID。
• {cluster_name}：GKE 集群名称。
• {location}：GKE 集群位置（区域或可用区）。
• {node_name}：（可选）特定 GKE 节点的名称。
• {node_pool_name}：（可选）GKE 节点池的名称。

---

诊断步骤

步骤 1：验证 TPU 运行时指标配置 [低风险] [自动]

在分析运行时指标之前，请验证工作负载是否已配置为导出这些指标。这可确保集群和容器环境已设置好，以自动抓取指标并查看加速器运行状况。

• 操作：验证 Pod 规范和集群是否满足以下先决条件：
  • TPU 容器已开放 containerPort: 8431（Prometheus 抓取指标所必需）。
  • 如果使用 JAX，版本为 0.4.14 或更高（较早版本不会导出运行时指标）。
  • GKE 版本为 1.27.4-gke.900 或更高（TPU 运行时指标支持所必需）。
  • 集群已启用 GKE 系统指标（向 Cloud Monitoring 导入指标所必需）。

步骤 2：监控 TPU 运行时指标 [低风险] [自动]

如果配置正确，Cloud Monitoring 中将提供以下指标（受监控资源为 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
  • kubernetes.io/node/accelerator/memory_used
  • kubernetes.io/node/accelerator/memory_total

步骤 3：检查节点状态条件 [低风险] [自动]

查询 GKE 节点的状态条件（GKE 版本为 1.32.1-gke.1357001 或更高）。

• PromQL 查询（检查特定节点是否为 Ready）：

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

• PromQL 查询（列出条件为 True 且状态非 Ready 的节点）：

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

• PromQL 查询（列出状态为 NOT Ready 的节点）：

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

• PromQL 查询（整个 Fleet 的节点状态）：

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

步骤 4：检查节点池状态 [低风险] [自动]

查询多主机 TPU 节点池的状态。

• PromQL 查询（验证特定节点池是否正在运行）：

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

• PromQL 查询（按状态分组监控节点池）：

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

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

步骤 5：检查节点池可用性 [低风险] [自动]

查询多主机 TPU 节点池中的所有节点是否都可用。

• PromQL 查询（检查一段时间内的可用性）：

  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，部分节点不可用）。

步骤 6：分析节点中断 [低风险] [自动]

查询 GKE 节点的中断次数。

• PromQL 查询（中断及原因细分）：

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

  中断类型：TerminationEvent、MaintenanceEvent、PreemptionEvent。 中断原因：HostError、Eviction、AutoRepair。
• PromQL 查询（筛选 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]))
  

• PromQL 查询（按节点池汇总中断次数）：

  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]))
  

步骤 7：计算恢复和中断指标 [低风险] [自动]

计算过去 7 天的平均恢复时间（MTTR）和平均中断间隔（MTBI）。

• PromQL 查询（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]))
  

• PromQL 查询（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]))
  

步骤 8：监控 TPU 主机指标 [低风险] [自动]

对于 GKE 版本 1.28.1-gke.1066000 或更高版本，监控 TPU 主机性能。

• 容器指标：
  • kubernetes.io/container/accelerator/tensorcore_utilization：当前 TensorCore 的利用率百分比。
  • kubernetes.io/container/accelerator/memory_bandwidth_utilization：当前加速器内存带宽的使用百分比。
• 节点指标：
  • kubernetes.io/node/accelerator/tensorcore_utilization
  • kubernetes.io/node/accelerator/memory_bandwidth_utilization