spark-operations-cli

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには、 x-ms-fabric-skill: spark-operations-cli を付与する必要があります（az rest の場合：--headers "x-ms-fabric-skill=spark-operations-cli"）。 すべての LRO ポーリング、fabric_lro、およびリトライも対象です。スニペットでは省略されていますが、必ず追加してください。

更新の確認 — セッションごとに 1 回（必須） セッション中にこのスキルを初めて使用するときは、先に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出します。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルとリモートの package.json のバージョンを比較します。
• このセッション中にすでに確認済みの場合は、スキップしてください。

重要な注意事項

1. ワークスペース名からワークスペースの詳細（ID を含む）を確認するには、まずすべてのワークスペースを一覧表示し、その後 JMESPath フィルタリングを使用してください。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を確認するには、まずそのワークスペース内の該当する種類のアイテムをすべて一覧表示し、その後 JMESPath フィルタリングを使用してください。
3. スキルの使い分け：spark-operations-cli は、既存のジョブとセッションの読み取り専用のトリアージと診断に使用します。ノートブックの作成、新しいジョブの実行、または Spark の開発には、spark-authoring-cli を使用してください。対話型 PySpark 分析と Livy セッションの作成には、spark-consumption-cli を使用してください。

Spark Operations — CLI スキル

このスキルでは、Fabric REST API と CLI ツール（az rest）を使用して、Microsoft Fabric の Spark ジョブの失敗、Livy セッションの状態、パフォーマンスのボトルネックを診断できます。診断操作はすべて読み取り専用です。セッションのクリーンアップ（ゾンビセッションの停止など）には、ユーザーによる明示的な確認が必要です。Spark の開発とノートブックの作成には、spark-authoring-cli を使用してください。対話型 PySpark 分析には、spark-consumption-cli を使用してください。

目次

目次は目的別にまとめられています。進行中の障害をトリアージする場合は、診断ワークフローから始めてください。それより前のセクションは基本事項を参照するためのものです。

1. Fabric の基礎（概念）

タスク	リファレンス	備考
Fabric のトポロジと主要概念	COMMON-CORE.md § Fabric のトポロジと主要概念
環境 URL	COMMON-CORE.md § 環境 URL
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	オーディエンスが正しくないと 401 が発生します。認証に関する問題がある場合は、先にお読みください
コアのコントロールプレーン REST API	COMMON-CORE.md § コアのコントロールプレーン REST API
ページネーション	COMMON-CORE.md § ページネーション
長時間実行操作（LRO）	COMMON-CORE.md § 長時間実行操作（LRO）
レート制限とスロットリング	COMMON-CORE.md § レート制限とスロットリング
ジョブの実行	COMMON-CORE.md § ジョブの実行
キャパシティ管理	COMMON-CORE.md § キャパシティ管理
注意点とトラブルシューティング	COMMON-CORE.md § 注意点とトラブルシューティング
ベストプラクティス	COMMON-CORE.md § ベストプラクティス

2. CLI のセットアップと認証

タスク	参照先	備考
ツール選定の根拠	COMMON-CLI.md § ツール選定の根拠
Fabric でのワークスペースとアイテムの検索	COMMON-CLI.md § Fabric でのワークスペースとアイテムの検索	必須 — 最初にリンクを読むこと [名前からワークスペース ID、または名前、アイテムの種類、ワークスペース ID からアイテム ID を検索するために必要]
認証の手順	COMMON-CLI.md § 認証の手順	az login のフローとトークンの取得
az rest による Fabric コントロールプレーン API	COMMON-CLI.md § az rest による Fabric コントロールプレーン API	必ず --resource https://api.fabric.microsoft.com を渡してください。渡さないと az rest は失敗します
ページネーションのパターン	COMMON-CLI.md § ページネーションのパターン
長時間実行操作（LRO）のパターン	COMMON-CLI.md § 長時間実行操作（LRO）のパターン
注意点とトラブルシューティング（CLI 固有）	COMMON-CLI.md § 注意点とトラブルシューティング（CLI 固有）	az rest のオーディエンス、シェルのエスケープ、トークンの有効期限切れ
クイックリファレンス：az rest テンプレート	COMMON-CLI.md § クイックリファレンス：az rest テンプレート
クイックリファレンス：トークンのオーディエンス／CLI ツールの対応表	COMMON-CLI.md § クイックリファレンス：トークンのオーディエンス ↔ CLI ツールの対応表	各サービスで使用する --resource とツール

3. Spark セッション、ノートブック、ジョブ（背景知識）

タスク	参照先	備考
Livy セッション管理	SPARK-CONSUMPTION-CORE.md § Livy セッション管理	セッションの作成、状態、ライフサイクル、終了
対話型データ探索	SPARK-CONSUMPTION-CORE.md § 対話型データ探索	ステートメントの実行、出力の取得、データの探索
ノートブックの実行とジョブ管理	SPARK-AUTHORING-CORE.md § ノートブックの実行とジョブ管理

4. Spark Monitoring API（主要なトリアージサーフェス）

タスク	参照	備考
Spark Monitoring API の概要	SPARK-MONITORING-CORE.md § Overview	GA 監視 API — アクティブなセッションは不要です
ワークスペースとアイテムのセッション一覧	SPARK-MONITORING-CORE.md § Workspace and Item-Level Session Listing	フィルターを使って、ワークスペース全体の Spark アプリを一覧表示します
Spark Advisor API	SPARK-MONITORING-CORE.md § Spark Advisor API	重要 — スキューの自動検出、タスクエラー、推奨事項
オープンソースの Spark History Server API	SPARK-MONITORING-CORE.md § Open-Source Spark History Server APIs	REST 経由でジョブ、ステージ、エグゼキューター、SQL クエリを取得します
ドライバーおよびエグゼキューターのログ API	SPARK-MONITORING-CORE.md § Driver and Executor Log APIs	アクティブなセッションなしでログを直接取得します
Livy Log API	SPARK-MONITORING-CORE.md § Livy Log API	バイトオフセットによるページネーションに対応したセッションレベルのログ
リソース使用量 API	SPARK-MONITORING-CORE.md § Resource Usage API	vCore のタイムライン、アイドル／実行中のコア、効率性の指標
監視 API を使った診断ワークフロー	SPARK-MONITORING-CORE.md § Diagnostic Workflow Using Monitoring APIs	監視 API を使ったステップごとのトリアージ

5. 診断ワークフロー（アクティブなトリアージはここから開始）

タスク	参照	備考
自動診断ワークフロー（全体）	automated-diagnostic-workflow.md	ステップ 1～7：特定 → 状態別に振り分け → 障害／パフォーマンス／リソース／健全性 → レポート。ステップ 1b の期限切れデータのフォールバックとレポートテンプレートを含みます
診断レベル	diagnostic-workflow.md § Diagnostic Tiers	レベル 1（オンライン REST）対レベル 2（ローカル SHS）
主な診断パターン	diagnostic-workflow.md § Key Diagnostic Patterns	症状 → 最初の確認項目 → 考えられる原因を検索
重大度のしきい値	diagnostic-workflow.md § Severity Thresholds	検出結果の分類に使うメトリックのしきい値
手動 CLI レシピ	diagnostic-workflow.md § Manual CLI Recipes	手動で使うアドホックな診断コマンド
パイプライン実行の診断	pipeline-diagnosis.md	パイプライン実行内のすべての Spark アクティビティを診断します（ステップ P1～P6）

6. ジョブ障害の診断

タスク	参照	備考
障害トリアージワークフロー	job-diagnostics.md § Failure Triage Workflow	障害を診断するためのステップごとの決定木
ジョブ障害の分類	job-diagnostics.md § Failure Classification	OOM、シャッフル、タイムアウト、依存関係、構成のエラー
REST 経由での Spark ログの読み取り	job-diagnostics.md § Reading Spark Logs via REST	Livy からドライバー／エグゼキューターのログを取得します
ジョブインスタンスの履歴	job-diagnostics.md § Job Instance History	最近の実行をクエリし、実行時間を比較して、リグレッションを検出します

7. Livy セッションの健全性

タスク	参照先	備考
セッションの健全性評価	session-health.md § Livy セッションのライフサイクル	セッションの状態、遷移、想定所要時間
アイドルセッションとゾンビセッションの検出	session-health.md § アイドルセッションとゾンビセッションの検出	リークしたセッションを検出してクリーンアップします
セッションリソースの監視	session-health.md § セッションリソースの監視	Livy 経由でメモリとエグゼキューターの使用状況を確認します
セッションの復旧パターン	session-health.md § セッションの復旧パターン	再起動戦略とセッションの置き換え

8. パフォーマンス診断

タスク	参照先	備考
パフォーマンスのアンチパターン	performance-patterns.md § アンチパターン	スピル、シャッフル、データの偏り、小さなファイル、collect の誤用
ステージとタスクの分析	performance-patterns.md § ステージとタスクの分析	REST 経由で Spark UI のメトリクスを読み取ります
最適化のレシピ	performance-patterns.md § 最適化のレシピ	パーティションの調整、ブロードキャスト結合、キャッシュ
容量とリソースの診断	performance-patterns.md § 容量とリソースの診断	CU の消費量、スロットリングの検出

9. オフライン／詳細分析ツール

タスク	参照先	備考
JobInsight のイベントログコピー	jobinsight-api.md § LogUtils.copyEventLog	オフライン分析のために、イベントログを Fabric から OneLake にコピーします
ローカル Spark History Server	spark-history-server.md § 概要	Spark UI 全体（DAG、タスク、SQL プラン）を確認できるよう、ローカル SHS を起動します

---

必須／推奨／回避

必ず行うこと

• 修復を試みる前に、必ずジョブ／セッションの状態を取得してください
• COMMON-CLI.md のワークスペースとアイテムの検出方法を使用してください。ID をハードコードしないでください
• 診断ステートメントを送信する前に、Livy セッションの状態を確認してください
• 体系的な診断には、障害トリアージのワークフローに従ってください
• 生ログを読む前に、必ず Spark Advisor API を確認してください。多くの場合、根本原因をすぐに特定できます
• Livy ベースの診断を試みる前に、監視 API（アクティブなセッションは不要）を使用してください
• ジョブ／セッションの状態は 10～30 秒間隔でポーリングし、診断は 30 分後にタイムアウトしてください
• 診断出力には必ず Notebook Snapshot の URL を含めてください。保持期間が最も長く、Fabric UI でセル単位の調査が可能になります

優先事項

• リグレッションと判断する前に、ジョブインスタンスの履歴を照会してベースラインを確立する

• 診断クエリでは新しいセッションを作成せず、既存のアイドル状態のセッションを再利用する

• ジョブの遅延を Spark コードのせいにする前に、容量の使用率を確認する

• 大規模な API レスポンスから特定のフィールドを抽出するには、JMESPath フィルタリングを使って az rest を使用する

• スキュー、タスクエラー、タイムアウトの検出には、手動でログを解析するより Spark Advisor API を使用する

• スケーリングを推奨する前に、Resource Usage API の coreEfficiency メトリックを使ってクラスターの使用率を定量化する

• 詳細な調査に入る前に、ジョブインスタンス履歴（直近5回の実行）を比較してリグレッションを検出する

• MLV の更新スケジュール、監視、実行履歴には、mlv-operations-cli を使用してください。根本原因となっている Spark ジョブの失敗（OOM、スキュー、シャッフルのスピル）の診断には、引き続きこのスキルを使用してください。MLV の更新は Spark ジョブとして実行され、ログには同じ監視 API からアクセスできます。

• MLV 失敗の分類 — 失敗した MLV の更新を診断する際は、詳細な調査に入る前にエラーを分類します。

  エラーパターン	カテゴリ	診断手順
  MLV_SPARK_SESSION_REQUEST_SUBMISSION_FAILED	インフラストラクチャ	容量が一時停止中または利用不可、Spark プールの設定ミスが考えられます。まず容量の状態を確認します。
  MLV_SELECTED_NOT_FOUND	設定	MLV テーブルが削除または名前変更されています。SHOW MATERIALIZED LAKE VIEWS IN schema を実行して、テーブルが存在することを確認します。
  OutOfMemoryError / SparkOutOfMemory	リソース	ソースデータがクラスターの容量を超えるほど増加しています。Spark Advisor でメモリ負荷を確認します。
  ShuffleBlockFetchFailed / data skew	パフォーマンス	データの分布が不均一です。Resource Usage API を使用して、スキューが発生しているパーティションを特定します。
  DeltaTableVersionNotFound	依存関係	ソーステーブルが保持期間のしきい値を下回るまで vacuum されています。delta.logRetentionDuration を延長します。
  ConstraintViolationException / ON MISMATCH	データ品質	DQ 制約によって行が削除されたか、処理に失敗しました。上流のソースデータの品質を確認します。
  タイムアウト（実行時間が24時間超）	スケール	リネージが大きすぎて1回の実行で処理できません。複数のレイクハウスに分けて、リネージグループを小さくします。

避けるべきこと

• アクティブなステートメントがあるか確認せずにセッションを終了する
• 診断クエリごとに新しいセッションを作成する（アイドル状態のセッションを再利用してください）
• Livy の実際のメモリメトリックを確認せずに OOM と決めつける
• 診断スクリプトでワークスペース ID やアイテム ID をハードコードする
• Admin API で容量のスロットリングを最初に確認せずにパフォーマンスを診断する
• busy 状態のセッションに診断ステートメントを送信する

---

例

例 1：失敗したノートブックを診断する

ユーザープロンプト：「ワークスペース Production のノートブック ETL_Daily が失敗したのはなぜですか？」

エージェントのワークフロー：

1. ワークスペースを workspaceId に、アイテムを itemId（Notebook）に解決します
2. 最近の Livy セッションを一覧表示し、Failed セッションを自動選択します
3. Spark Advisor に問い合わせ、エグゼキューターで TaskError: OutOfMemoryError を検出します
4. /stages に問い合わせ、ステージ5でデータスキュー（最大値と中央値の比が12倍）を確認します
5. 重大度が HIGH の検出結果と修正の推奨事項を含むレポートを提示します

例 2：停止した Livy セッションをトリアージする

ユーザープロンプト：「Livy セッション abc-1234 が starting 状態のまま停止しています」

エージェントのワークフロー：

1. セッション ID を直接使って、セッションの状態を照会します
2. ワークスペース内のすべてのセッションを一覧表示し、同時実行中のセッションが8つあること（容量の逼迫）を検出します
3. Livy ログを確認します。エラーはなく、キューに入っているだけです
4. 容量の競合を報告し、待機するかアイドル状態のセッションをキャンセルするよう推奨します

例 3：パイプライン失敗の根本原因

ユーザープロンプト：「ワークスペース Analytics のパイプライン実行 5678 を診断してください」

エージェントのワークフロー：

1. パイプラインを特定し、実行 5678 に対して queryActivityRuns を呼び出します
2. Notebook アクティビティを2つ検出します。一方は Succeeded、もう一方は Failed です
3. 失敗したアクティビティから output.result.error.{ename, evalue, traceback} を抽出します
4. セル単位で調査できる Notebook Snapshot URL を生成します
5. エラーの詳細、スナップショットへのリンク、推奨される修正方法を提示します

---

クイックスタート

環境設定

COMMON-CLI.md の環境検出を適用して、次を設定します。

• $FABRIC_API_BASE と $FABRIC_RESOURCE_SCOPE
• Livy の操作では $FABRIC_API_URL と $LIVY_API_PATH

認証：COMMON-CLI.md § Authentication Recipes に記載されているトークン取得方法を使用します。

---

自動診断ワークフロー

ユーザーが簡単なプロンプト（例：「ノートブック ETL_Pipeline を診断して」、「Spark アプリケーション abc-123 の問題を教えて」、「ワークスペース Production に問題がないか確認して」）を入力したら、このファストパスの概要に従います。詳しい手順、エッジケース（期限切れデータ、パイプラインのみのセッション）、レポートのテンプレート、保持に関する詳細は、references/automated-diagnostic-workflow.md を参照してください。

エントリーポイント（ユーザーが指定する情報）

ユーザーが指定する情報	エージェントが解決する情報
ワークスペース名	→ workspaceId（ワークスペース一覧と名前フィルターを使用）
ノートブック／SJD／レイクハウス名	→ itemId（アイテム一覧と名前／種類フィルターを使用）
パイプライン名＋実行 ID	→ 子 Spark アクティビティ → pipeline-diagnosis.md を参照
Livy セッション ID または Spark アプリ ID	→ そのまま使用
具体的な情報がない場合	→ ワークスペース名＋アイテム名を尋ねます

アイテムタイプごとの API パス

アイテムタイプ	Livy セッションのパス	ジョブインスタンスのパス
ノートブック	/notebooks/{id}/livySessions	/items/{id}/jobs/instances
Spark ジョブ定義	/sparkJobDefinitions/{id}/livySessions	/items/{id}/jobs/instances
レイクハウス	/lakehouses/{id}/livySessions	/lakehouses/{id}/jobs/instances

すべてのセッション API パスは次の形式に従います：$FABRIC_API_URL/workspaces/$workspaceId/<itemTypePath>/$itemId/livySessions/$livyId/applications/$appId/<endpoint>。SPARK-MONITORING-CORE.md を参照してください。

手順の概要

手順	タイミング	アクション	自動フラグのルール
1. 解決と検出	常に	ワークスペース → アイテムを解決し、最近の Livy セッションを一覧表示します。曖昧さがなければ自動で選択し、それ以外の場合はユーザーに確認します	—
1b. フォールバック	セッションが 404 / Spark Monitoring データの期限切れ	queryActivityRuns（パイプライン）→ Job Instance の failureReason を試し、Notebook Snapshot の URL を構築します	リファレンス § 手順 1b を参照
2. 状態に応じた分岐	手順 1 の後	Failed → 3+4+5 · Succeeded/InProgress → 4+5 · Cancelled → ログ+3 · idle/busy/starting → 6 · dead/killed/error → 3+6	—
3. 失敗の分析	Failed / Cancelled / dead	次の順にクエリします：Spark Advisor → ドライバーの stderr → Job Instance → エグゼキューターのログ → Livy のログ → リソース使用量。根本原因が明らかになった時点で停止します。	job-diagnostics.md § クイックリファレンステーブル と照合
4. パフォーマンス	常に（手順 1b の経路を除く）	/stages、/allexecutors	skew max/median > 3× · spill diskBytesSpilled > 0 · GC jvmGcTime/executorRunTime > 20% · shuffle > 1 GB · tasks < 100ms
5. リソース使用率	常に（手順 1b の経路を除く）	/resourceUsage	coreEfficiency < 0.3 → HIGH · idleTime/duration > 0.4 → MEDIUM
6. セッションの健全性	アイドル／ゾンビの確認	GET /workspaces/$workspaceId/spark/livySessions	idle かつ最近のステートメントがない → ゾンビ · starting が想定時間を超過 → 容量の問題
7. レポートの作成	最後	重要度順の検出結果テーブル + Notebook Snapshot リンク + 修正案	テンプレートについてはリファレンス § 手順 7を参照

重要な原則：常に最初に Spark Advisor を確認してください。事前に計算済みのため、ログを解析しなくてもほとんどの根本原因を特定できます。パイプラインの実行では、queryActivityRuns（ename、evalue、traceback、セル／行）から最も詳細なエラーデータを取得できます。pipeline-diagnosis.mdを参照してください。

データ保持に関する警告：Spark Monitoring API のデータ（ログ、ステージ、Advisor）は通常、セッション終了後 数分から数時間 で期限切れになります。失敗は速やかに診断してください。API が 404 を返した場合は、リファレンスの手順 1b に進んでください。

Tier 2 へのエスカレーション：データの切り捨て、HTTP 408/504、または DAG／SQL プランの可視化が必要な場合は、オフライン Spark History Server ワークフローを提案してください。