https://rspack.rs/static/js/async/route-7a320e73f90f.c64bcb914b.js

1"use strict";(self.rspackChunkrspack_website=self.rspackChunkrspack_website||[]).push([["hy"],{Od(e,r,s){s.r(r);var n=s("i"),i=s("f");function l(e){let r={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",span:"span",ul:"ul",...(0,i.R)(),...e.components};return(0,n.jsxs)(n.Fragment,{children:[(0,n.jsxs)(r.h1,{id:"tracing",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#tracing",children:"#"}),"Tracing"]}),"\n",(0,n.jsxs)(r.p,{children:[(0,n.jsx)(r.a,{href:"https://crates.io/crates/tracing",rel:"noopener noreferrer",target:"_blank",children:(0,n.jsx)(r.code,{children:"tracing"})})," 用于记录 Rspack 内部的编译流程，既可用于性能分析，也可用于定位 Bug。"]}),"\n",(0,n.jsxs)(r.h2,{id:"开启-tracing",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#开启-tracing",children:"#"}),"开启 Tracing"]}),"\n",(0,n.jsx)(r.p,{children:"可以通过以下两种方式开启 tracing："}),"\n",(0,n.jsxs)(r.ul,{children:["\n",(0,n.jsxs)(r.li,{children:["如果使用 ",(0,n.jsx)(r.a,{href:"/zh/api/cli.html",children:"@rspack/cli"})," 或 Rsbuild：通过设置 ",(0,n.jsx)(r.code,{children:"RSPACK_PROFILE"})," 环境变量来开启："]}),"\n"]}),"\n",(0,n.jsx)(n.Fragment,{children:(0,n.jsx)(r.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"sh",children:(0,n.jsxs)(r.code,{children:[(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# Rspack CLI"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"OVERVIEW"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-function)"},children:" rspack"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:" build"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:" # 推荐"})]}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"ALL"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-function)"},children:" rspack"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:" build"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:" # 不推荐，大项目可能会生成较大的 trace 文件"})]}),"\n",(0,n.jsx)(r.span,{className:"line"}),"\n",(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# Rsbuild"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"OVERVIEW"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-function)"},children:" rsbuild"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:" build"})]}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"ALL"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-function)"},children:" rsbuild"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:" build"})]})]})})}),"\n",(0,n.jsxs)(r.ul,{children:["\n",(0,n.jsxs)(r.li,{children:["如果直接使用 ",(0,n.jsx)(r.code,{children:"@rspack/core"}),"：可通过 ",(0,n.jsx)(r.code,{children:"rspack.experiments.globalTrace.register"})," 和 ",(0,n.jsx)(r.code,{children:"rspack.experiments.globalTrace.cleanup"})," 开启。你可以查看我们如何在 ",(0,n.jsxs)(r.a,{href:"https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-cli/src/utils/profile.ts",rel:"noopener noreferrer",target:"_blank",children:[(0,n.jsx)(r.code,{children:"@rspack/cli"})," 中实现 ",(0,n.jsx)(r.code,{children:"RSPACK_PROFILE"})]})," 获取更多信息。"]}),"\n"]}),"\n",(0,n.jsxs)(r.p,{children:["启用 ",(0,n.jsx)(r.code,{children:"perfetto"})," layer 后，生成的 ",(0,n.jsx)(r.code,{children:"rspack.pftrace"})," 文件可以在 ",(0,n.jsx)(r.a,{href:"https://ui.perfetto.dev/",rel:"noopener noreferrer",target:"_blank",children:"ui.perfetto.dev"})," 中查看和分析："]}),"\n",(0,n.jsx)(r.p,{children:(0,n.jsx)(r.img,{src:"https://assets.rspack.rs/rspack/assets/rspack-v1-4-tracing.png",alt:"tracing"})}),"\n",(0,n.jsxs)(r.h2,{id:"tracing-layer",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#tracing-layer",children:"#"}),"Tracing layer"]}),"\n",(0,n.jsxs)(r.p,{children:["Rspack 支持 ",(0,n.jsx)(r.code,{children:"perfetto"})," 和 ",(0,n.jsx)(r.code,{children:"logger"})," 两种 layer："]}),"\n",(0,n.jsxs)(r.ul,{children:["\n",(0,n.jsxs)(r.li,{children:[(0,n.jsx)(r.code,{children:"logger"}),"：默认值，将 JSON Lines 格式的日志写入文件，适用于简单的日志分析。在 CI 环境中，可以上传或打印生成的 ",(0,n.jsx)(r.code,{children:"rspack.log"}),"，也可以显式设置 ",(0,n.jsx)(r.code,{children:"RSPACK_TRACE_OUTPUT=stdout"})," / ",(0,n.jsx)(r.code,{children:"stderr"})," 将 logger 输出流式写到终端。"]}),"\n",(0,n.jsxs)(r.li,{children:[(0,n.jsx)(r.code,{children:"perfetto"}),"：仅在使用 ",(0,n.jsx)(r.code,{children:"@rspack-debug/core"})," 时可用，生成符合 ",(0,n.jsx)(r.a,{href:"https://perfetto.dev/docs/reference/synthetic-track-event",rel:"noopener noreferrer",target:"_blank",children:(0,n.jsx)(r.code,{children:"perfetto proto"})})," 格式的 ",(0,n.jsx)(r.code,{children:"rspack.pftrace"})," 文件，可导入到 Perfetto 进行复杂的性能分析"]}),"\n"]}),"\n",(0,n.jsxs)(r.p,{children:[(0,n.jsx)(r.code,{children:"@rspack-debug/core"})," 是 ",(0,n.jsx)(r.code,{children:"@rspack/core"})," 的诊断版本，包含额外的调试和 tracing 能力，例如 ",(0,n.jsx)(r.code,{children:"perfetto"})," layer。当你需要为本地问题排查收集 Perfetto trace 时使用它，不建议把它作为常规构建的默认依赖。"]}),"\n",(0,n.jsxs)(r.p,{children:["可以通过 ",(0,n.jsx)(r.code,{children:"RSPACK_TRACE_LAYER"})," 环境变量指定 layer："]}),"\n",(0,n.jsx)(n.Fragment,{children:(0,n.jsx)(r.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"sh",children:(0,n.jsxs)(r.code,{children:[(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_TRACE_LAYER"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"logger"})]}),"\n",(0,n.jsx)(r.span,{className:"line"}),"\n",(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# 仅适用于 @rspack-debug/core"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_TRACE_LAYER"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"perfetto"})]})]})})}),"\n",(0,n.jsxs)(r.h2,{id:"tracing-output",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#tracing-output",children:"#"}),"Tracing output"]}),"\n",(0,n.jsx)(r.p,{children:"可以指定 trace 的输出位置："}),"\n",(0,n.jsxs)(r.ul,{children:["\n",(0,n.jsxs)(r.li,{children:[(0,n.jsx)(r.code,{children:"logger"})," layer 的默认输出为 ",(0,n.jsx)(r.code,{children:".rspack-profile-${timestamp}-${pid}/rspack.log"})]}),"\n",(0,n.jsxs)(r.li,{children:[(0,n.jsx)(r.code,{children:"perfetto"})," layer 的默认输出为 ",(0,n.jsx)(r.code,{children:".rspack-profile-${timestamp}-${pid}/rspack.pftrace"})]}),"\n"]}),"\n",(0,n.jsxs)(r.p,{children:["通过 ",(0,n.jsx)(r.code,{children:"RSPACK_TRACE_OUTPUT"})," 环境变量可以自定义输出位置："]}),"\n",(0,n.jsx)(n.Fragment,{children:(0,n.jsx)(r.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"sh",children:(0,n.jsxs)(r.code,{children:[(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_TRACE_LAYER"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"logger"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:" RSPACK_TRACE_OUTPUT"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"log.txt"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-function)"},children:" rspack"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:" dev"})]}),"\n",(0,n.jsx)(r.span,{className:"line"}),"\n",(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# 仅适用于 @rspack-debug/core"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_TRACE_LAYER"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"perfetto"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:" RSPACK_TRACE_OUTPUT"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"perfetto.pftrace"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-function)"},children:" rspack"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:" dev"})]})]})})}),"\n",(0,n.jsxs)(r.p,{children:["当 ",(0,n.jsx)(r.code,{children:"RSPACK_TRACE_OUTPUT"})," 是相对文件路径时，它会解析到生成的 ",(0,n.jsx)(r.code,{children:".rspack-profile-${timestamp}-${pid}"})," 目录下。绝对路径会按原样使用。对于 ",(0,n.jsx)(r.code,{children:"logger"})," layer，如果需要输出到终端，可以显式设置为 ",(0,n.jsx)(r.code,{children:"stdout"})," 或 ",(0,n.jsx)(r.code,{children:"stderr"}),"。",(0,n.jsx)(r.code,{children:"perfetto"})," layer 始终需要文件路径。"]}

1),"\n",(0,n.jsxs)(r.h2,{id:"tracing-filter",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#tracing-filter",children:"#"}),"Tracing filter"]}),"\n",(0,n.jsxs)(r.p,{children:["通过 ",(0,n.jsx)(r.code,{children:"RSPACK_PROFILE"})," 可以配置需要过滤的数据。Rspack 提供了两个预设的 ",(0,n.jsx)(r.code,{children:"preset"}),"："]}),"\n",(0,n.jsxs)(r.ul,{children:["\n",(0,n.jsxs)(r.li,{children:[(0,n.jsx)(r.code,{children:"RSPACK_PROFILE=OVERVIEW"}),"：默认值，只展示核心的构建流程，生成的 JSON 文件较小"]}),"\n",(0,n.jsxs)(r.li,{children:[(0,n.jsx)(r.code,{children:"RSPACK_PROFILE=ALL"}),"：包含所有的 trace event，用于较为复杂的分析，生成的 JSON 文件较大"]}),"\n"]}),"\n",(0,n.jsxs)(r.p,{children:["除了预设外，其他字符串都会透传给 ",(0,n.jsx)(r.a,{href:"https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax",rel:"noopener noreferrer",target:"_blank",children:"Env Filter"}),"，支持更复杂的过滤策略："]}),"\n",(0,n.jsxs)(r.h3,{id:"tracing-level-filter",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#tracing-level-filter",children:"#"}),"Tracing level filter"]}),"\n",(0,n.jsxs)(r.p,{children:["支持的 tracing 等级有：",(0,n.jsx)(r.code,{children:"TRACE"}),"、",(0,n.jsx)(r.code,{children:"DEBUG"}),"、",(0,n.jsx)(r.code,{children:"INFO"}),"、",(0,n.jsx)(r.code,{children:"WARN"})," 和 ",(0,n.jsx)(r.code,{children:"ERROR"}),"。可以通过等级进行过滤："]}),"\n",(0,n.jsx)(n.Fragment,{children:(0,n.jsx)(r.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"sh",children:(0,n.jsxs)(r.code,{children:[(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# trace level 是最高级别，输出所有日志"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"trace"})]}),"\n",(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# 只输出小于等于 INFO level 的日志"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"info"})]})]})})}),"\n",(0,n.jsxs)(r.h3,{id:"模块级别过滤",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#模块级别过滤",children:"#"}),"模块级别过滤"]}),"\n",(0,n.jsx)(n.Fragment,{children:(0,n.jsx)(r.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"sh",children:(0,n.jsxs)(r.code,{children:[(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# 查看 rspack_resolver 的日志"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_TRACE_LAYER"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"logger"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:" RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"rspack_resolver"})]})]})})}),"\n",(0,n.jsxs)(r.h3,{id:"混合过滤",children:[(0,n.jsx)(r.a,{className:"rp-header-anchor","aria-hidden":"true",href:"#混合过滤",children:"#"}),"混合过滤"]}),"\n",(0,n.jsx)(r.p,{children:"EnvFilter 支持混合使用多种过滤条件，实现更复杂的过滤策略："}),"\n",(0,n.jsx)(n.Fragment,{children:(0,n.jsx)(r.pre,{className:"shiki css-variables",style:{backgroundColor:"var(--shiki-background)",color:"var(--shiki-foreground)"},tabIndex:"0",lang:"sh",children:(0,n.jsxs)(r.code,{children:[(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# 查看 rspack_core crate 里的 WARN level 的日志"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"rspack_core"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"warn"})]}),"\n",(0,n.jsx)(r.span,{className:"line",children:(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-comment)"},children:"# 保留其他 crate 的 INFO level 日志但关闭 rspack_resolver 的日志"})}),"\n",(0,n.jsxs)(r.span,{className:"line",children:[(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"RSPACK_PROFILE"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"info,"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-foreground)"},children:"rspack_core"}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,n.jsx)(r.span,{style:{color:"var(--shiki-token-string)"},children:"off"})]})]})})})]})}function c(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},{wrapper:r}={...(0,i.R)(),...e.components};return r?(0,n.jsx)(r,{...e,children:(0,n.jsx)(l,{...e})}):l(e)}c.__RSPRESS_PAGE_META={},c.__RSPRESS_PAGE_META["zh%2Fcontribute%2Fdevelopment%2Ftracing.md"]={toc:[{id:"开启-tracing",text:"开启 Tracing",depth:2},{id:"tracing-layer",text:"Tracing layer",depth:2},{id:"tracing-output",text:"Tracing output",depth:2},{id:"tracing-filter",text:"Tracing filter",depth:2},{id:"tracing-level-filter",text:"Tracing level filter",depth:3},{id:"模块级别过滤",text:"模块级别过滤",depth:3},{id:"混合过滤",text:"混合过滤",depth:3}],title:"Tracing",headingTitle:"Tracing",frontmatter:{description:"介绍 Rspack 中 Tracing 的使用方式"}},s.d(r,{default:()=>c})}}]);