gke-ai-troubleshooting-tpu-performance-degradation

使用 ML Diagnostics 工作负载监控排查 GKE TPU 性能下降

通过关联 ML Diagnostics Workload Monitoring MonitoredEvent 分析器报告、1 分钟 Cloud Monitoring 系统指标和 GKE 节点拓扑标签，诊断并缓解 Google Kubernetes Engine（GKE）上 Cloud TPU 训练吞吐量下降和步长时间回归问题（TPU 占空比下降 15%+）。

---

归属信息

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

前提条件

• 工具：安装 Google Cloud SDK（gcloud，并为 gcloud alpha mldiagnostics 安装 alpha 组件）和 kubectl。
• Cloud Billing 和项目配置：确认已关联有效的结算账号 （gcloud billing projects describe {project_id}），完成身份验证 （gcloud auth login），设置目标项目（gcloud config set project {project_id}），并确保已启用 container.googleapis.com、 monitoring.googleapis.com 和 hypercomputecluster.googleapis.com。
• 支持的工作负载和 GKE 版本：Google Cloud ML Diagnostics 仅支持 TPU 上的 JAX（参见 ML Diagnostics 平台）。 Workload Monitoring 默认已启用，支持 jobset 和 job GKE 作业类型，并兼容 1.36.0-gke.4681000 及更高版本的 GKE，详见 为 ML Diagnostics 配置 GKE。 如果工作负载使用其他框架（例如 PyTorch）或其他自定义资源类型，gcloud alpha mldiagnostics 不会列出相关的 ML 运行或受监控事件。按需性能分析（步骤 4 路径 A）还要求按照该文档所述配置集群。
• 所需 IAM 角色：
  • Cluster Director Editor（roles/hypercomputecluster.editor），即 ML Diagnostics 平台 “IAM permissions”部分列出的角色，用于本技能中的 ML Diagnostics CLI 和 API 调用（ML 运行、受监控事件和按需性能分析器会话）
  • Monitoring Viewer（roles/monitoring.viewer），用于步骤 2 中的 PromQL 查询
  • Kubernetes Engine Viewer（roles/container.viewer），用于步骤 3 中的 kubectl get nodes 查询
  • 用于修复（[High Risk] 步骤）：Kubernetes Engine Cluster Admin （roles/container.clusterAdmin）
• 参考文档：
  • ML Diagnostics 平台 （章节：“IAM permissions”）
  • 为 ML Diagnostics 配置 GKE （章节：“Set up with gcloud CLI, Google Cloud console, or Terraform”、 “Manual installation”、“Connection-operator”）
  • 使用 ML Diagnostics 监控工作负载 （章节：“Workload Monitoring and analyzers”、“HBM Capacity Analyzer”、 “Host Memory Utilization Analyzer”、“CPU Utilization Analyzer”、“Access Workload Monitoring information through the API”、“List all monitored events”、“System Metrics”）
  • 开始使用 ML Diagnostics CLI （章节：“List machine learning runs”、“Monitored-events commands”、“List profiler targets”、“Capture on-demand profiler sessions”）
  • 扩缩容容器资源请求和限制 （章节：“Identify workloads without resource requests or limits”）
  • 自动修复节点 （章节：“Repair criteria”、“Verify node auto-repair is enabled for a Standard node pool”、“Enable auto-repair for an existing Standard node pool”、“Node auto repair in TPU slice nodes”）
  • 在 GKE Standard 中部署 TPU 工作负载 （章节：“Configure auto repair for TPU slice nodes”）
  • 获取支持 （章节：“Before you contact support”）

只读规则：仅运行只读诊断命令。绝不要排空、删除或重新创建节点，也不要运行任何其他会更改集群的命令。 向用户提供由他们自行应用的修复方法。

推荐修复方法时，请链接到说明该方法的文档部分。

---

分析器路由概览

默认情况下，Workload Monitoring 会将 TPU 占空比下降 15% 视为性能下降，触发 MonitoredEvent（type: PERFORMANCE_DEGRADATION），并运行其分析器。请参阅 Cloud TPU 官方文档中的 Workload Monitoring and analyzers 部分，了解完整的分析器定义、检测标准和子章节，并按类别转接修复：

• 类别 A：工作负载资源瓶颈（绝不隔离或替换节点）：
  • 当触发的分析器（detectionState: "DETECTED"）表明存在工作负载内存或主机 CPU 容量瓶颈时（请参阅 Workload monitoring with ML Diagnostics中的 “HBM Capacity Analyzer”、“Host Memory Utilization Analyzer”和“CPU Utilization Analyzer”章节）， 转接至 路径 A：工作负载资源瓶颈 （工作负载优化和性能分析）。
• 类别 B：基础设施和网络结构限流（问题节点）：
  • 当触发的分析器（detectionState: "DETECTED"）表明特定实例存在互连、热／电源限流、内存带宽或机架顶端（ToR）网络故障时（请参阅 Workload Monitoring and analyzers）， 转接至 路径 B：基础设施或网络结构限流 （将问题 Compute Engine 实例 ID 映射到 GKE 节点，通过 GKE 处理节点修复，并升级至 Google Cloud 支持团队）。
• 类别 C：触发了 PERFORMANCE_DEGRADATION 事件，但没有分析器报告 detectionState: "DETECTED"：
  • 当存在 PERFORMANCE_DEGRADATION 事件时（如 List all monitored events中的示例输出所示，其中 analyzerReports 条目的 detectionState 为 "NOT_DETECTED"）， 转接至 路径 C：事件已触发，但没有 DETECTED 分析器。

---

诊断工作流

步骤 0：收集上下文并设置调查时间范围 [低风险]

收集目标参数。默认查询 {issue_time} 前后各 30 分钟的 60 分钟时间范围 `[T - 30m, T

• 30m]`：

• {project_id}：Google Cloud 项目 ID
• {location}：ML 运行和 GKE 集群所在的 Google Cloud 区域（例如 us-central1）
• {cluster_name}：GKE 集群名称
• {workload_name} / {ml_run_id}：JobSet／工作负载名称或 ML Diagnostics 运行 ID
• {issue_time}：观测到吞吐量下降的时间戳（T，ISO-8601 UTC）
• {start_time}：T - 30m
• {end_time}：T + 30m

---

步骤 1：查询 ML 运行和 monitoredEvents [低风险]

1. 列出活跃或近期的 ML 运行：向用户提供 gcloud alpha mldiagnostics machine-learning-run list，并附上 ML Diagnostics CLI 参考中的 列出机器学习运行 链接，找到与 {workload_name} 匹配的 {ml_run_id}。
2. 列出性能下降事件：向用户提供 gcloud alpha mldiagnostics monitored-events list，并附上 Monitored-events 命令 链接；也可以使用 hypercomputecluster.googleapis.com/v1alpha API，并附上 通过 API 访问信息工作负载监控 链接，检查 [{start_time}, {end_time}] 期间是否发生 PERFORMANCE_DEGRADATION 事件。
3. 描述 MonitoredEvent：向用户提供 gcloud alpha mldiagnostics monitored-events describe，并附上同一 Monitored-events 命令 章节的链接，然后检查 analyzerReports 数组（analyzer、 detectionState、details 和 recommendedActions）。
   • 如果触发了 PERFORMANCE_DEGRADATION 事件，请执行步骤 2，使用 1 分钟系统指标进行佐证；如果其 analyzerReports 条目中没有任何一项的 detectionState: "DETECTED"，请遵循 路径 C：事件已触发，但没有检测到的分析器。
   • 如果不存在 PERFORMANCE_DEGRADATION 事件，且步骤 2 中的占空比保持稳定，请遵循 路径 D：遥测数据正常，排除 TPU 性能下降。

---

步骤 2：关联 1 分钟 Cloud Monitoring 系统指标 [低风险]

查阅工作负载监控文档中的 系统指标 章节，了解为 TPU 和主机设备导出的 1 分钟 Cloud Monitoring 指标，并在 [{start_time}, {end_time}] 时间范围内运行只读 PromQL 查询，以佐证分析器报告：

# 1. Node TPU duty cycle (look for the drop on the affected nodes)
kubernetes_io:node_accelerator_duty_cycle{
  monitored_resource="k8s_node",
  project_id="{project_id}",
  cluster_name="{cluster_name}"
}

# 2. HBM utilization ratio by node (around 0.90 is approaching the limit)
sum by (node_name) (
  kubernetes_io:node_accelerator_memory_used{
    monitored_resource="k8s_node",
    project_id="{project_id}",
    cluster_name="{cluster_name}"
  }
)
/
sum by (node_name) (
  kubernetes_io:node_accelerator_memory_total{
    monitored_resource="k8s_node",
    project_id="{project_id}",
    cluster_name="{cluster_name}"
  }
)

# 3. Host memory and CPU allocatable utilization
kubernetes_io:node_memory_allocatable_utilization{
  monitored_resource="k8s_node",
  project_id="{project_id}",
  cluster_name="{cluster_name}"
}

kubernetes_io:node_cpu_allocatable_utilization{
  monitored_resource="k8s_node",
  project_id="{project_id}",
  cluster_name="{cluster_name}"
}

---

步骤 3：将问题实例 ID 映射到 GKE 节点和拓扑 [低风险]

当基础设施分析器在 details 或 recommendedActions 中报告问题 Compute Engine 实例的数字 ID 时，使用以下只读 kubectl 查询检查 container.googleapis.com/instance_id，将这些数字实例 ID 映射到 GKE Node 名称和物理拓扑区块：

kubectl get nodes -l cloud.google.com/gke-tpu-accelerator \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\tinstance_id="}{.metadata.annotations.container\.googleapis\.com/instance_id}{"\tblock="}{.metadata.labels.cloud\.google\.com/gce-topology-block}{"\tsubblock="}{.metadata.labels.cloud\.google\.com/gce-topology-subblock}{"\thost="}{.metadata.labels.cloud\.google\.com/gce-topology-host}{"\n"}{end}'

---

步骤 4：按分析器类别进行修复

仅加载并遵循与步骤 1 中分析器类别相匹配的参考文件：

• 路径 A（工作负载资源瓶颈——HBM、主机内存或主机 CPU 利用率）：阅读 路径 A：工作负载资源瓶颈。
• 路径 B（基础设施、热、ICI、内存带宽或网络结构 限流）：阅读 路径 B：基础设施或网络结构限流。
• 路径 C（已触发 PERFORMANCE_DEGRADATION 事件，且所有分析器均为 NOT_DETECTED）：阅读 路径 C：事件已触发，但没有检测到的分析器。
• 路径 D（没有 PERFORMANCE_DEGRADATION 事件，且遥测数据稳定）：阅读 路径 D：遥测数据正常。

---

防护措施

1. 绝不要通过 Compute Engine 更改由 GKE 管理的实例组或 VM： 不要运行 gcloud compute instance-groups managed 命令（例如 delete）来操作节点池的托管实例组。请通过 GKE 处理节点，具体说明见 路径 B：基础设施或网络结构限流。
2. 绝不要因工作负载资源饱和而隔离节点：如果只有 HBM 容量、主机内存或主机 CPU 利用率分析器检测到问题，请勿隔离或替换节点。