rspack-tracing

Rspack のトレースとパフォーマンスプロファイリング

このスキルを使用する場面

次のような場合にこのスキルを使用します。

1. Rspack のビルドが遅い原因を特定する。
2. どのプラグインやローダーに最も時間がかかっているかを把握する。
3. ユーザーから提供された Rspack のトレースファイルを分析する。
4. パフォーマンスプロファイルの取得方法をユーザーに案内する。

ワークフロー

1. トレースを取得する

まず、トレースを有効にしてビルドを実行するようユーザーに依頼します。

# Set environment variables for logging to a file
RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json pnpm build

これにより、.rspack-profile-{timestamp}-{pid}/trace.json のようなタイムスタンプ付きディレクトリにトレースファイルが生成されます。

設定の詳細については、references/tracing-guide.md を参照してください。

2. クラッシュ／エラーの簡易診断

クラッシュまたはエラーがどの段階で発生したかを特定したい場合は、全体の分析を実行せずに tail を使用して直近のイベントをすばやく確認します。

# Navigate to the generated profile directory
cd .rspack-profile-*/

# View the last 20 events to see where the build failed
tail -n 20 trace.json

直近のイベントには、ビルドが停止した箇所のスパン名と対象が表示されるため、問題のある段階、プラグイン、またはローダーをすばやく特定できます。

3. 詳細なパフォーマンス分析

クラッシュの診断だけでなく、詳細なパフォーマンスプロファイリングを行う場合は、生成されたトレースファイルに対して、同梱されている scripts/analyze_trace.mjs を実行するかどうかユーザーに確認します。同意が得られたら、作業ディレクトリはユーザーのプロジェクトのまま、Skill のルートを基準にスクリプトのパスを解決して、次を実行します。

# Navigate to the generated profile directory
cd .rspack-profile-*/

# Run the analysis script
node "<skill-root>/scripts/analyze_trace.mjs" trace.json

4. 結果を解釈する

スクリプトの出力を使用してボトルネックを特定します。 スパン名と実行可能な改善策の対応については、references/bottlenecks.md を参照してください。

5. 遅いプラグインを特定する

分析スクリプトの「Top Slowest Hooks」に基づいて、次の手順を実行します。

1. フックを特定する：フック名（例：hook:CompilationOptimizeChunks）を確認します。
2. 設定を調べる：rspack.config.js または rsbuild.config.ts を読み込みます。
3. フックとプラグインを対応付ける：その特定のフックに登録されているプラグインとそのソースを探します。
4. 出力する：疑わしいプラグインのソースコードのパス、行番号、列番号を出力します。

よくあるシナリオと簡単な修正方法

• ボトルネックのリファレンス：スパンと概念の対応付け。
• トレースガイド：RSPACK_PROFILE の詳しい使い方。