rspack-tracing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rspack Tracing & Performance Profiling

Rspack 追踪与性能分析

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Diagnose why an Rspack build is slow.
Understand which plugins or loaders are taking the most time.
Analyze a user-provided Rspack trace file.
Guide a user to capture a performance profile.

在以下场景中使用该技能：

诊断Rspack构建缓慢的原因。
了解哪些插件或加载器耗时最长。
分析用户提供的Rspack追踪文件。
指导用户捕获性能分析数据。

Workflow

工作流程

1. Capture a Trace

1. 捕获追踪数据

First, ask the user to run their build with tracing enabled.

bash

undefined

首先，要求用户在启用追踪的情况下运行构建。

bash

undefined

Set environment variables for logging to a file

RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json pnpm build


This will generate a trace file in a timestamped directory like `.rspack-profile-{timestamp}-{pid}/trace.json`.

See [references/tracing-guide.md](references/tracing-guide.md) for more details on configuration.

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. Quick Diagnosis for Crashes/Errors

2. 崩溃/错误快速诊断

If the user wants to identify which stage a crash or error occurred in, use

tail

to quickly view the last events without running the full analysis:

bash

undefined

如果用户想要确定崩溃或错误发生在哪个阶段，可以使用

tail

命令快速查看最后几个事件，而无需运行完整分析：

bash

undefined

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


The last events will show the span names and targets where the build stopped, helping to quickly pinpoint the problematic stage, plugin, or loader.

tail -n 20 trace.json


最后的事件将显示构建停止时的跨度名称和目标，帮助快速定位有问题的阶段、插件或加载器。

3. Full Performance Analysis

3. 完整性能分析

For detailed performance profiling (not just crash diagnosis), ask the user to run the bundled analysis script on the generated trace file.

bash

undefined

对于详细的性能分析（不仅仅是崩溃诊断），请用户在生成的追踪文件上运行捆绑的分析脚本。

bash

undefined

Navigate to the generated profile directory

cd .rspack-profile-*/

Run the analysis script

node ${CLAUDE_PLUGIN_ROOT}/skills/tracing/scripts/analyze_trace.js trace.json

undefined

node ${CLAUDE_PLUGIN_ROOT}/skills/tracing/scripts/analyze_trace.js trace.json

undefined

4. Interpret Results

4. 解读结果

Use the output from the script to identify bottlenecks. Consult references/bottlenecks.md to map span names to actionable fixes.

使用脚本的输出来识别瓶颈。请查阅 [references/bottlenecks.md] 将跨度名称映射为可操作的修复方案。

5. Locate Slow Plugins

5. 定位缓慢的插件

Based on the "Top Slowest Hooks" from the analysis script:

Identify the Hook: Note the hook name (e.g.,
```
hook:CompilationOptimizeChunks
```
).
Inspect Configuration: Read
```
rspack.config.js
```
or
```
rsbuild.config.ts
```
.
Map Hook to Plugin: Look for plugins and their sources that tap into that specific hook.
Output: Output the paths, lines and columns of the suspected plugin source code.

根据分析脚本输出的“Top Slowest Hooks”：

识别钩子：记录钩子名称（如
```
hook:CompilationOptimizeChunks
```
）。
检查配置：读取
```
rspack.config.js
```
或
```
rsbuild.config.ts
```
。
将钩子映射到插件：查找接入该特定钩子的插件及其来源。
输出：输出可疑插件源代码的路径、行号和列号。

Common Scenarios & Quick Fixes

常见场景与快速修复

Bottleneck Reference: Mapping spans to concepts.
Tracing Guide: Detailed usage of
```
RSPACK_PROFILE
```
.

瓶颈参考：将跨度映射到相关概念。
追踪指南：
```
RSPACK_PROFILE
```
的详细用法。