#Tracing

tracing is used to record the internal processes of Rspack compilation, which can be used for performance analysis as well as narrow down the location of a bug.

#Enabling tracing

Tracing can be enabled in two ways:

• If using @rspack/cli or Rsbuild: Enable it by setting the RSPACK_PROFILE environment variable:

# Rspack CLI
RSPACK_PROFILE=OVERVIEW rspack build # recommend
RSPACK_PROFILE=ALL rspack build # not recommend, may generate too large rspack.pftrace for large projects

# Rsbuild
RSPACK_PROFILE=OVERVIEW rsbuild build
RSPACK_PROFILE=ALL rsbuild build

• If directly using @rspack/core: Enable it through rspack.experiments.globalTrace.register and rspack.experiments.globalTrace.cleanup. You can check how we implement RSPACK_PROFILE in @rspack/cli for more information.

The generated rspack.pftrace file can be viewed and analyzed in ui.perfetto.dev:

#Tracing layer

Rspack supports two types of layers: perfetto and logger:

• perfetto: The default value, generates a rspack.pftrace file conforming to the perfetto proto format, which can be exported to perfetto for complex performance analysis
• logger: Outputs logs directly to the terminal, suitable for simple log analysis or viewing compilation processes in CI environments

You can specify the layer through the RSPACK_TRACE_LAYER environment variable:

RSPACK_TRACE_LAYER=logger
# or
RSPACK_TRACE_LAYER=perfetto

#Tracing output

You can specify the output location for traces:

• The default output for the logger layer is stdout
• The default output for the perfetto layer is rspack.pftrace

You can customize the output location through the RSPACK_TRACE_OUTPUT environment variable:

RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./log.txt rspack dev
RSPACK_TRACE_LAYER=perfetto RSPACK_TRACE_OUTPUT=./perfetto.pftrace rspack dev

#Tracing filter

You can configure the data to be filtered through RSPACK_PROFILE. Rspack provides two preset options:

• RSPACK_PROFILE=OVERVIEW: The default value, only shows the core build process, generating a smaller JSON file
• RSPACK_PROFILE=ALL: Includes all trace events, used for more complex analysis, generating a larger JSON file

Apart from the presets, other strings will be passed directly to Env Filter, supporting more complex filtering strategies:

#Tracing level filter

The supported tracing levels are: TRACE, DEBUG, INFO, WARN, and ERROR. You can filter by level:

# trace level is the highest level, outputting all logs
RSPACK_PROFILE=trace
# only output logs less than or equal to INFO level
RSPACK_PROFILE=info

#Module level filtering

# View rspack_resolver logs and output to terminal
RSPACK_TRACE_LAYER=logger RSPACK_PROFILE=rspack_resolver

#Mixed filtering

EnvFilter supports mixed use of multiple filtering conditions to implement more complex filtering strategies:

# View WARN level logs in the rspack_core crate
RSPACK_PROFILE=rspack_core=warn
# Keep INFO level logs for other crates but turn off logs for rspack_resolver
RSPACK_PROFILE=info,rspack_core=off