sparkforensics-mcp

SparkForensics

Spark ジョブの実行が遅いですか？SparkForensics が原因と対処法を明らかにします。

Spark のイベントログを取り込むと、どのステージがなぜ遅いのか、どう修正すればよいのかを、証拠に基づいて分析します。クラスターへのインストールは不要で、データがマシンの外に出ることもありません。

**今すぐ試す →**自分のイベントログを使って試せます。インストールもアカウントもアップロードも不要です。ガイド付きの使い方はドキュメントをご覧ください。

Spark に付属する History Server では、生のメトリクスを確認できます。しかし、ステージ 14 で偏った結合キーが原因で 40GB がスピルしたことや、コールドスタートがジョブの 3 分の 1 を占めていることまではわかりません。SparkForensics は同じイベントログを読み込み、分析結果を提示します。

SparkForensics を選ぶ理由

• データはマシン上に保持されます。ログファイルを読み込んでダッシュボードを確認するだけで、どこにもアップロードされません。ローカルサーバーモードでは、小さな Node コンパニオンが追加され、Spark History Server から実行を取得することもできます。
• イベントログはストリーミングされ、Web Worker 内でメインスレッドとは別に解析されるため、240MB 以上（または複数 GB）の NDJSON ログを読み込んでもタブがフリーズしません。
• 25 種類の分析項目で、偏り、シャッフル、スピル、GC の負荷、処理の遅いタスク、コールドスタート、キャッシュ／メモリ使用率、自動スケーリングの頻繁な変動、ジョブ／ステージの失敗、パーティションサイズを網羅します。さらに、SQL Plan Advisor（重複するサブツリー、小さなファイル、ブロードキャストのサイズ設定）と設定監査も備えています。各検出器としきい値は検出器の表で確認できます。
• 「最初に修正すべき項目」では、重大度だけでなく、推定実行時間への影響に基づいてすべての分析結果を並べ替えるため、最初に取り組むべき修正が先頭に表示されます。
• 実行比較（A/B）モードでは、同じジョブの 2 回の実行間でステージを構造的に照合し、あらゆる差異ではなく、性能が悪化したステージを表示します。
• 各分析結果では、ログから確認できた内容と確認できなかった内容を追跡するため、警告を信頼できる場合と、手動で確認すべきヒントにとどまる場合を判断できます。
• ヘッドレス CLI（sparkforensics-analyze）は、予算のしきい値（最大実行時間、偏り、スピル、失敗率など）に照らして実行を評価し、違反があればゼロ以外の終了コードを返します。そのため、性能の後退をビルドの失敗として検出できます。実行データはローカルのイベントログファイル／ディレクトリから取得できるほか、--shs-base-urlを指定すれば Spark History Server から直接取得できます。
• MCP サーバー（sparkforensics-mcp）は、実行の診断、要約、比較を行うツールを提供するため、LLM エージェントが実行を直接調査できます。すべてのツールはMCP ツールで確認できます。
• 手動ではなく、Spark ジョブの実行後に毎回 analyze CLI を自動実行するには、sparkforensics-operatorをご覧ください。ジョブのイベントログに対して SparkForensics を実行し、その結果に基づいて処理する Airflow オペレーターです。

クラスター側のプラグインや、LLM エージェントと実行中のサーバー（Spark History Server MCP ツール）を必要とするツールとは異なり、SparkForensics はほかの場所へのインストールが不要です。イベントログとブラウザーのタブだけで利用できます。

はじめに

ダッシュボードをローカルで実行します。

npx sparkforensics-server

はじめにでは、提供される機能、ライブデモという代替手段、実行データの読み込み方法について説明しています。SparkForensics 自体を開発する場合は、開発をご覧ください。

ブラウザーを使わず、CI パイプラインで合否判定できるような単発のチェックを行うには、次のコマンドを実行します。

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --max-runtime 3600000 --max-skew 3

このコマンドは sparkforensics-cli パッケージに含まれています。代わりに一度だけインストールするには、npm i -g sparkforensics-cli を実行し、その後 sparkforensics-analyze を直接実行してください。エイリアスパッケージの sparkforensics-analyze も使用できます。 npx sparkforensics-analyze。

これは予算のしきい値に対するヘッドレス実行です。HTML エクスポート、Spark History Server からの取得、ベースライン比較、秘匿化については、以下のコマンドラインリファレンスをご覧ください。 独自のしきい値で検出器チェックを実行するには、検出器のしきい値の調整をご覧ください。

開発

インストールと実行

チェックアウトしたディレクトリから、次のコマンドを実行します。

git clone [email protected]:shuffle-works/sparkforensics.git
cd sparkforensics
npm install
npm run dev

Vite が表示する URL を開きます。本番用バンドルを作成するには、npm run build を実行し、その後 dist/ を任意の静的ファイルサーバーで配信します。アセット URL は相対パスなので、バンドルは URL のサブパスでも動作します。

注記： アプリは HTTP 経由で配信する必要があります。file:// URL では、Chrome での Web Worker モジュールのインポートがブロックされます。

デプロイモード

このアプリは 2 つのモードで実行できます。

• 静的モード（GitHub Pages や一般的なファイルサーバーなど）：単一のイベントログには、ファイルを選択が通常のブラウザー内ローカル読み込み方法です。ローリングログフォルダーを選択は、eventlog_v2_* ディレクトリでのみ使用できます。npm run build の出力を dist/ からデプロイします。Spark History Server からの直接取得は利用できません。ブラウザーの CORS ポリシーによってブロックされ、静的ホストではリクエストをプロキシできないためです。History Server から読み込めない場合は、代わりにローカルのイベントログファイルを選択してください。
• ローカルサーバーモード：このアプリを配信し、Spark History Server からの取得も代行する、小規模な Node コンパニオンです（サーバー間通信のため、ブラウザーの CORS 制限はありません）。SHS が VPN の背後にある場合や、CORS が設定されていない場合に便利です。

ローカルサーバーモードを実行するには、次のコマンドを実行します。

npx sparkforensics-server

デフォルトでは http://127.0.0.1:4173 で待ち受けます（--port または PORT 環境変数で変更できます）。バインド先は localhost のみです。Chrome で URL を開き、読み込み画面の Spark History Server から取得の開示パネルを使用してください。同じサーバーは、同じマシン上のクライアント向けに /mcp でストリーミング可能な HTTP 経由の MCP ツールも提供します。詳しくはHTTP 経由での接続をご覧ください。

History Server からの取得には、ローカルサーバーモード、そのサーバーを実行しているマシンからアクセス可能な History Server、そしてサポート対象のベースアプリケーション ID が必要です（受け付けられる形式の一覧ははじめにをご覧ください）。省略可能な試行 ID は、ベースアプリケーション ID とは別に入力してください。ローカルサーバーは認証情報を送信せず、上流からのリダイレクトにも従いません。回復可能なエラーには、意図的に上流の応答詳細を含めていません。回復するには、フィールドを編集するか、ローカルのイベントログファイルを選択してください。

チェックアウトしたディレクトリから開発する場合は、パッケージの公開やインストールをせずに、npm run local-server で同じ機能を実行できます。

サーバー設定

すべての設定には使用可能なデフォルト値があります。ポート（PORT または --port）と SPARKFORENSICS_* 環境変数については、サーバー設定をご覧ください。

SHS プロキシのルートテスト用フィクスチャ

/shs-proxy ルート（packages/core/src/proxy.js）は、通常の npm run test:server スイートの一部である packages/server/test/shs-proxy-fixture.test.js でテストされています。このテストでは、dev/log-corpus/ の spark-event-corpus-data Git サブモジュールから実際のイベントログを読み込み、ルートが有効な ZIP としてストリーミングすることを検証します。このテストに Docker、稼働中の Spark プロセス、稼働中の History Server は必要ありません。

到達不能な上流サーバーやアプリケーションが見つからない場合の復旧状態も含め、Fetch from SHS の UI フロー全体を手動で確認するには、アクセス可能な実際の Spark History Server を npm run local-server の接続先に指定し、Fetch from Spark History Server の開閉項目を使用してください。/shs-proxy の自動テストでは spark-event-corpus-data のログを使うため、Docker イメージや稼働中の Spark プロセスは必要ありません。

テストの実行

npm test              # single run
npm run test:watch    # watch mode
npm test -- tests/finding-filter.test.js  # single file
npm run test:core     # packages/core: detectors, analyzer, parser, MCP tools
npm run test:cli      # packages/cli
npm run test:mcp      # packages/mcp
npm run test:server   # packages/server

コマンドラインリファレンス

はじめにでの基本的な予算チェックに加えて、同じ sparkforensics-analyze CLI でほかのいくつかの処理も実行できます。

JSON／Markdown レポートの代わりに、実行結果を自己完結型の HTML ダッシュボードとして出力します。サーバーなしで file:// 経由でオフライン表示できます。

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --export-html path/to/output-dir

ローカルファイルの代わりに、Spark History Server から実行結果を直接取得します（位置引数のパスとは併用できません）。

npx -p sparkforensics-cli sparkforensics-analyze --shs-base-url http://history-server:18080 --app-id application_1234_0001 --max-skew 3

候補の実行結果をベースラインと比較（A/B）し、リグレッションまたは新たに検出された重大な指摘があればビルドを失敗させます。

npx -p sparkforensics-cli sparkforensics-analyze path/to/candidate --baseline path/to/baseline --max-regression-pct 10 --fail-on-introduced critical

1 回の呼び出しで複数のリグレッション予算を適用し、複数の候補を 1 つのベースラインと比較します（NDJSON 形式で、候補ごとに 1 行出力します。ベースラインは 1 回だけ解析されます）。

npx -p sparkforensics-cli sparkforensics-analyze cand-1 cand-2 cand-3 --baseline base --regression-budget wallClock:10 --regression-budget gcTime:25

ローカルの候補、または History Server 上の候補を、Spark History Server 上にあるベースラインと比較します。--baseline-shs-base-url、--baseline-app-id、--baseline-attempt-id を指定します（ベースラインは別のサーバー上にあってもかまいません）。

npx -p sparkforensics-cli sparkforensics-analyze --shs-base-url http://history-server:18080 --app-id application_1234_0002 --baseline-shs-base-url http://history-server:18080 --baseline-app-id application_1234_0001 --max-regression-pct 10

1 つの History Server から複数の候補を指定するには、--app-id を繰り返し指定します（--app-id <id>:<attempt> で試行を指定します）。NDJSON 形式で候補ごとに 1 行出力されます。

--budgets ファイル、NDJSON の各行に含まれるフィールド、終了コードの規則については、複数の予算と複数の候補を参照してください。

出力を生成した環境の外部で共有する前に、URL とパスに含まれるアプリ ID、アプリ名、ホスト名、IP アドレス、ユーザー名を伏せてください。その他のパス、テーブル名、SQL テキストはそのまま出力されます。CI ガイドでは、--redact で伏せられる情報と伏せられない情報を説明しています。

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --redact

出力の findings 配列を、特定の影響度、種類、またはステージに絞り込みます（recommendations／cleanChecks／notRunChecks と概要の件数は、絞り込み前の全項目を対象とします）。

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --impact critical,warning --type stageSlowness --stage 12

その他の予算フラグもチェックを補完します。--max-spill <gb>、 --max-failed-task-rate <pct>、--min-efficiency <pct>（ビジーコア時間： タスクの実行に使われたエグゼキューターのコア時間の割合です。ダッシュボードの「未使用コア時間」を 100 から引いた値であり、「効率」タイルの値ではありません）。--attempt-id は、デフォルト以外の試行を指定するために --shs-base-url／--app-id と組み合わせて使用します。--regression-metric は、--max-regression-pct でチェックするメトリクスを選択します（デフォルトは wallClock）。--conf-keys と --conf-redact-regex は、JSON 出力の metrics ブロックの隣にある effectiveConf ブロックの内容を調整します（どちらのブロックもはじめにに記載されています）。--format md を指定すると、出力形式が Markdown に切り替わります（デフォルトは json）。--out <path> を指定すると、標準出力ではなくファイルに書き込みます（出力先のフォルダーが存在しない場合、コマンドは 2 で終了します）。終了コード： 0 は合格、1 は予算違反、2 は使用方法のエラー（不正なフラグ、引数、または --thresholds／--budgets ファイル）、3 は予算を判定できなかった場合（例：リグレッションチェックに必要な証拠がない場合）、4 は候補ログを読み取れない、または解析できない場合、5 はベースラインログを読み取れない、または解析できない場合、6 は内部エラーです。複数の条件に該当する場合は、6、5、4、1、3、0 の順で最も重大なものが適用されます。複数の候補がある場合は、最も重大な行が適用されます。候補を読み取れない、または解析できない場合は、その候補の行に 4 が出力されます。

Node のバージョン： 公開されている sparkforensics-cli、sparkforensics-mcp、 sparkforensics-server の各パッケージは、公開時に同梱の TypeScript をすべてプレーンな JS に変換しているため、npx でインストールして使用する場合に必要なのは Node >=18 のみです（各パッケージの engines フィールドを参照してください）。チェックアウトしたコードから packages/core/src/*.ts に対して packages/*/bin/ のいずれかを直接実行する場合 （モノレポの開発モードでのフォールバック）は、代わりにネイティブの （フラグ不要の）TypeScript 型ストリッピングに対応する Node バージョンが必要です。Node 22 LTS 系列では >=22.18.0、Node 23 以降では >=23.6.0 です。

詳細はこちら

ドキュメント全文は shuffle-works.github.io/sparkforensics/docs で公開されています。

• はじめに：ダッシュボード、実行の比較、CI、自動化の確認
• 検出結果を理解する
• MCP ツール
• 検出器の表
• ワーカープロトコル
• ストリーミング／解析の設計
• ウィジェットのレイアウト

貢献

CONTRIBUTING.md をご覧ください。

ライセンス

MIT