gke-ai-troubleshooting-tpu-performance-degradation

ML Diagnostics Workload Monitoring による GKE TPU のパフォーマンス低下のトラブルシューティング

ML Diagnostics Workload Monitoring の MonitoredEvent アナライザー レポートを 1-minute Cloud Monitoring system metrics および GKE ノードトポロジー ラベルと関連付け、Google Kubernetes Engine（GKE）での Cloud TPU トレーニングスループットの低下とステップ時間 の悪化（TPU デューティサイクルが 15%+ 低下）を診断し、軽減します。

---

Attribution

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 Usage Attribution を必ずお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内のコマンドは対象外）では、 gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-ai-troubleshooting-tpu-performance-degradation)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gke-ai-troubleshooting-tpu-performance-degradation) を追加してください。

前提条件

• ツール：以下をインストールします。 Google Cloud SDK（gcloud alpha mldiagnostics を使うには、alpha コンポーネントを含む gcloud が必要です）と 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 platform を参照）。Workload Monitoring はデフォルトで有効になっており、GKE ジョブタイプの jobset と job をサポートし、Configure GKE for ML Diagnostics に記載のとおり、GKE バージョン 1.36.0-gke.4681000 以降に対応しています。ワークロードが別のフレームワーク（PyTorch など）や別のカスタムリソースタイプを使用している場合、gcloud alpha mldiagnostics はそのワークロードの ML 実行や監視対象イベントを一覧表示しません。オンデマンドプロファイリング（ステップ 4 のパス A）には、さらに同ドキュメントに記載のクラスタ設定が必要です。
• 必要な IAM ロール：
  • Cluster Director Editor（roles/hypercomputecluster.editor）：ML Diagnostics platform の「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 platform（セクション：「IAM permissions」）
  • Configure GKE for ML Diagnostics（セクション：「Set up with gcloud CLI, Google Cloud console, or Terraform」、「Manual installation」、「Connection-operator」）
  • Workload monitoring with 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」）
  • Get started with the ML Diagnostics CLI（セクション：「List machine learning runs」、「Monitored-events commands」、「List profiler targets」、「Capture on-demand profiler sessions」）
  • Scale container resource requests and limits（セクション：「Identify workloads without resource requests or limits」）
  • Auto-repair nodes（セクション：「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」）
  • Deploy TPU workloads in GKE Standard（セクション：「Configure auto repair for TPU slice nodes」）
  • Get support（セクション：「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」の各セクションを参照）、次に振り分けます。 Path A: Workload resource bottlenecks （ワークロードの最適化とプロファイリング）。
• カテゴリ B：インフラストラクチャとネットワークファブリックのスロットリング（原因ノード）：
  • 発火したアナライザー（detectionState: "DETECTED"）が、特定のインスタンスにおけるインターコネクト、温度／電力のスロットリング、メモリ帯域幅、またはトップ・オブ・ラック（ToR）ネットワークの障害を示している場合（ Workload Monitoring and analyzers を参照）、次に振り分けます。 Path B: Infrastructure or network fabric throttling （原因となっている Compute Engine インスタンス ID を GKE ノードに対応付け、GKE を通じてノードの修復に対処し、Google Cloud Support にエスカレーションします）。
• カテゴリ C：PERFORMANCE_DEGRADATION イベントは発生したが、detectionState: "DETECTED" を報告するアナライザーがない場合：
  • PERFORMANCE_DEGRADATION イベントが存在する場合（analyzerReports のエントリーが detectionState: "NOT_DETECTED" となっている、 List all monitored events のサンプル出力など）、次に振り分けます。 Path C: Event fired with no DETECTED analyzer。

---

診断ワークフロー

ステップ 0：コンテキストを収集し、調査時間枠を設定する [Low Risk]

対象のパラメーターを収集します。デフォルトでは、{issue_time} を中心とした 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 を照会する [Low Risk]

1. アクティブまたは最近の ML 実行を一覧表示する：ML Diagnostics CLI リファレンスの 機械学習実行の一覧表示 へのリンクとともに、ユーザーに gcloud alpha mldiagnostics machine-learning-run list を提示し、{workload_name} に一致する {ml_run_id} を特定します。
2. パフォーマンス低下イベントを一覧表示する：ユーザーに Monitored-events コマンド へのリンクとともに gcloud alpha mldiagnostics monitored-events list を提示するか、 API を通じた Workload Monitoring 情報へのアクセス へのリンクとともに hypercomputecluster.googleapis.com/v1alpha API を提示し、 [{start_time}, {end_time}] の期間に PERFORMANCE_DEGRADATION イベントがないか確認します。
3. MonitoredEvent を説明する：同じ Monitored-events コマンド セクションへのリンクとともに、ユーザーに gcloud alpha mldiagnostics monitored-events describe を提示し、analyzerReports 配列 （analyzer、detectionState、details、recommendedActions）を確認します。
   • PERFORMANCE_DEGRADATION イベントが発生した場合は、1 分間隔のシステム指標と照合するためにステップ 2 を実行します。analyzerReports のエントリに detectionState: "DETECTED" がない場合は、 パス C：検出されたアナライザーがない状態でイベントが発生 に従います。
   • PERFORMANCE_DEGRADATION イベントが存在せず、ステップ 2 でデューティサイクルが安定している場合は、 パス D：正常なテレメトリー に従って TPU のパフォーマンス低下を除外します。

---

ステップ 2：1 分間隔の Cloud Monitoring システム指標と照合する [Low Risk]

Workload Monitoring ドキュメントの システム指標 セクションを参照して、TPU とホストデバイスについてエクスポートされた 1 分間隔の Cloud Monitoring 指標を確認し、読み取り専用の PromQL クエリを [{start_time}, {end_time}] の期間に実行して、アナライザーレポートと照合します。

# 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 ノードとトポロジーに対応付ける [Low Risk]

インフラストラクチャーアナライザーが details または recommendedActions に原因となった数値の Compute Engine インスタンス ID を報告した場合は、container.googleapis.com/instance_id を調べる次の読み取り専用 kubectl クエリを使って、その数値のインスタンス 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 を変更しないでください： ノードプールのマネージドインスタンスグループに対して、delete などの gcloud compute instance-groups managed コマンドを実行しないでください。ノードは、 パス B：インフラストラクチャまたはネットワークファブリックのスロットリング に記載されているように、GKE を介して操作してください。
2. ワークロードのリソース飽和を理由にノードをコルドンしないでください：HBM 容量、ホストメモリ、またはホスト CPU 使用率のアナライザーのみが問題を検出した場合は、 ノードをコルドンしたり置き換えたりしないでください。