尧图网页设计 
Rolldown 调试利器基于 tracing 与 RD_LOG 的源码级日志系统实战指南【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldownRolldown 是一款以 Rust 实现的 JavaScript/TypeScript 打包器其代码库在打包链路的各个阶段埋设了大量tracing::debug!/tracing::trace!日志调用。本文围绕 Rolldown 的 Tracing/Logging 机制讲解如何通过RD_LOG环境变量按需开启日志、如何理解与配置多种输出格式并给出在源码中新增日志与使用函数级过滤器的最佳实践帮助你快速定位 bug、理解打包器每一步的行为。为什么需要一套日志系统Rolldown 的打包流程横跨模块解析、链接link、tree-shaking、代码生成等多个阶段逻辑复杂且高度并发。直接打断点或在代码中临时插入打印语句往往效率低下。为此代码库在大量关键路径上埋设了tracing::debug!或tracing::trace!调用正如关联文档 docs/development-guide/tracing-logging.md 所述这些日志即使在无法直接定位 bug 时也能帮你大幅缩小问题范围或者帮助你理解编译器打包器为什么要做某件事。由于 tracing 的引入会拖慢打包速度Rolldown 默认不开启任何日志。只有当你显式设置环境变量RD_LOG时日志基础设施才会被初始化。这一设计在 crates/rolldown_tracing/src/lib.rs 中有直接体现pub fn try_init_tracing() - OptionBoxdyn Any Send { let Ok(env_var) std::env::var(LOG_ENV_NAME) else { // tracing will slow down the bundling process, so we only enable it when LOG is set. return None; }; ... }未设置RD_LOG时直接返回None整套订阅器不会被注册因此正常运行不受任何性能影响。快速上手用 RD_LOG 开启日志开启日志只需为你的打包命令设置RD_LOG环境变量值为一个日志过滤器log filter。RD_LOG的取值遵循tracing-subscriber中EnvFilter/Targets的指令语法例如# 输出所有 debug 级别及以上的日志 RD_LOGdebug rolldown -i ./input.js # 只关注某个目标target的日志例如模块解析 RD_LOGoxc_resolver rolldown -i ./input.js # 按模块路径过滤 RD_LOGrolldowndebug,oxc_resolverinfo rolldown -i ./input.js过滤器的完整语法如crate_namelevel、多指令用逗号分隔等可以参考tracing-subscriber的EnvFilter文档中关于 directives 的说明。在 Rolldown 的实现中RD_LOG的值被解析为Targets见 crates/rolldown_tracing/src/lib.rslet targets match Targets::from_str(env_var) { Ok(targets) targets, Err(error) { report_tracing_init_failure(format!(invalid {LOG_ENV_NAME} filter: {error})); return None; } };值得注意的一个实现细节如果过滤器格式非法Rolldown 不会 panic而是打印一条告警并静默禁用 tracing。集成测试 crates/rolldown_tracing/tests/invalid_filter_fallback.rs 专门验证了这一行为#[test] fn invalid_rd_log_filter_disables_tracing_instead_of_panicking() { unsafe { std::env::set_var(RD_LOG, rolldownnot_a_level); std::env::remove_var(RD_LOG_OUTPUT); } let guard rolldown_tracing::try_init_tracing(); assert!(guard.is_none(), invalid filter should disable tracing, not panic); }这个测试之所以独立成二进制运行是因为try_init_tracing内部通过IS_INITIALIZED全局原子标志保证只初始化一次见 crates/rolldown_tracing/src/lib.rs同一进程内无法重复初始化。控制输出格式RD_LOG_OUTPUT默认情况下日志以可读文本形式输出到 stdout。除此之外Rolldown 还支持将 tracing 事件导出为 Chrome 性能分析工具chrome://tracing / Perfetto可加载的 JSON 文件用于可视化打包各阶段的耗时与调用关系# 普通文本日志 RD_LOGdebug rolldown -i ./input.js # 导出 chrome-json 格式的追踪文件 RD_LOGdebug RD_LOG_OUTPUTchrome-json rolldown -i ./input.js关联文档 docs/development-guide/tracing-logging.md 明确指出RD_LOG_OUTPUTchrome-json需要以chrome-tracingcargo feature 构建该 feature 在 profile 构建pnpm build-binding:profile中启用但在 release 构建中禁用以保持产物更小。未启用时rolldown 会回退到可读的 stdout 输出并打印一条警告。从源码看RD_LOG_OUTPUT支持多种取值见 crates/rolldown_tracing/src/lib.rsRD_LOG_OUTPUT 取值行为chrome-json使用ChromeLayerBuilder以TraceStyle::Async风格导出异步追踪chrome-json-threaded以TraceStyle::Threaded风格导出按线程组织事件json当前未实现打印告警并回退到可读输出readable强制可读的 pretty 文本输出默认行为其他 / 未设置默认可读输出并开启 span 的ENTER/CLOSE事件其中chrome-json分支在没有启用chrome-tracingfeature 时会编译进一段回退逻辑#[cfg(not(feature chrome-tracing))] { eprintln!( RD_LOG_OUTPUT{output_mode} requires building with the chrome-tracing feature, \ which is disabled in release builds. Falling back to readable stdout output. \ Build a profile binary (pnpm build-binding:profile) to enable chrome tracing. ); ... }因此如果你需要可视化分析请确保使用 profile 构建即pnpm build-binding:profile来运行具体构建步骤可参考 docs/development-guide/building-and-running.md。另外crates/rolldown_tracing/src/lib.rs 的注释中还提到一种组合用法RD_LOGtrace RD_LOG_OUTPUTchrome-json rolldown ... RD_LOG_OUTPUT_STYLEasync其中RD_LOG_OUTPUT_STYLEasync用于将 trace 记录为一组异步操作适合分析并发打包过程中的跨任务依赖关系。统一的初始化入口与过滤规则无论选择哪种输出模式初始化都会经过统一的过滤管线crates/rolldown_tracing/src/lib.rslet filter_for_removing_devtools_event filter_fn(|metadata| { const ALLOW: bool true; const REJECT: bool false; if metadata.is_event() metadata.fields().field(devtoolsAction).is_some() { return REJECT; } ALLOW });凡是带有devtoolsAction字段的事件仅供开发调试工具 devtools 使用都会被剔除不会污染普通日志输出。同时tracing 基础设施的初始化入口try_init_tracing是在打包器工厂中触发的见 crates/rolldown/src/bundle/bundle_factory.rsif opts.disable_tracing_setup { None } else { rolldown_tracing::try_init_tracing() };这也说明通过 bundler 选项disable_tracing_setup可以显式关闭 tracing 的初始化方便某些宿主环境如已自行接入 tracing 的调用方自行管理订阅器。在源码中新增日志选择正确的级别Rolldown 欢迎贡献者在 PR 中加入tracing::debug!或tracing::trace!调用但为了避免日志噪音需要谨慎选择日志级别。关联文档给出了清晰的决策规则场景推荐级别不确定选哪个级别tracing::trace!打包过程中只会打印一次tracing::debug!只会打印一次、但内容大小与输入规模相关tracing::trace!会打印多次、但次数有限tracing::debug!因输入规模而打印多次tracing::trace!核心原则一句话概括与输入规模模块数量、依赖数量成正比增长的日志应该用trace级别只有固定次数、内容量可控的日志才适合debug级别。在真实代码库中这些调用遍布各个阶段。例如 crates/rolldown/src/stages/link_stage/tree_shaking/include_statements.rs、crates/rolldown/src/stages/link_stage/bind_imports_and_exports.rs、crates/rolldown/src/stages/generate_stage/order_analysis.rs 等文件中均有tracing::debug!/tracing::trace!调用你可以直接阅读这些示例来感受级别的选取粒度。一个容易踩的坑#[tracing::instrument]的级别上述规则同样适用于#[tracing::instrument]属性函数在打包过程中只调用一次使用#[tracing::instrument(level debug, skip_all)]函数因输入规模被多次调用使用#[tracing::instrument(level trace, skip_all)]注意文档原文第 33 行给出的示例写作#[tracing::instrument(level trace, skip_all]实际正确的属性语法是skip_all)使用时应留意。需要说明的是哪些信息值得被追踪带有较强的主观性opinionated因此 reviewer 会在合并前决定保留还是要求移除这些 tracing 语句。函数级过滤器用 #[instrument] 缩小排查范围Rolldown 中大量函数使用#[instrument]属性标注例如#[instrument(level debug, skip(self))] fn foo(self, bar: Type) {} #[instrument(level debug, skip_all)] fn baz(self, bar: Type) {}一旦函数被#[instrument]包裹你可以通过如下形式的过滤器一次性完成三件事RUSTC_LOG[foo]注意这里演示的键名是文档中的通用写法在 Rolldown 中实际使用的环境变量是RD_LOG例如RD_LOG[foo]。开启后可以记录对foo的所有函数调用打印 span 进入/退出记录函数的入参skip列表中排除的参数除外在函数返回之前记录该函数执行期间来自其他任何位置的日志事件——相当于把整个调用子树纳入了可见范围。配套两个注意点默认推荐使用skip_all除非你有充分的理由需要记录参数值参数打印可能产生大量噪音也可能涉及大对象序列化成本需要打印特定参数时用skip(self)这类白名单外的形式保留个别参数其余全部跳过。这种按函数名开日志的方式比全局开启RD_LOGdebug噪音小得多适合针对某个可疑阶段做定点观测。追踪模块解析oxc_resolver 的调试输出模块解析是打包器最容易出问题、也最值得调试的环节之一。Rolldown 使用 oxc-resolver文档中指向的第三方解析库进行模块解析它对外暴露了调试用的 trace 信息。开启方式RD_LOGoxc_resolver rolldown这会输出oxc_resolver::resolve函数的 trace 信息例如2024-06-11T07:12:20.003537Z DEBUG oxc_resolver: options: ResolveOptions { ... }, path: ..., specifier: ..., ret: ... at /path/to/oxc_resolver-1.8.1/src/lib.rs:212 in oxc_resolver::resolve with path: ..., specifier: ...解读这条日志输入值options解析选项、path当前模块路径、specifier被解析的导入说明符返回值ret解析结果。通过观察specifier与ret的对应关系你可以迅速判断某个导入为什么被解析到某个路径、为什么走了node_modules中的某个版本、为什么解析失败等。结合函数级过滤器还可以进一步跟踪resolve内部更细粒度的调用栈。排查工作流建议综合上述机制推荐如下调试工作流粗定位先RD_LOGdebug全局开启观察打包过程在哪一阶段出现异常行为或报错细定位根据日志中的 target/span 名称改用RD_LOG[可疑函数名]或RD_LOG模块名debug聚焦某个模块解析问题怀疑模块解析问题时直接RD_LOGoxc_resolver跟踪 specifier 与 ret性能分析需要分析各阶段耗时与调用关系时用 profile 构建pnpm build-binding:profile配合RD_LOGdebug RD_LOG_OUTPUTchrome-json导出可视化 trace确认修复修复后重新对比日志输出验证行为符合预期若日志噪音过大检查是否有与输入规模成正比的日志被错误地放在了debug级别。这套日志系统的所有核心逻辑都集中在 crates/rolldown_tracing/src/lib.rs它是理解整个 tracing 行为的首选入口而 crates/rolldown_tracing/tests 下的集成测试则固化了非法过滤器不 panic等关键行为契约。掌握 RD_LOG 的用法你就能像外科手术一样精准地看到 Rolldown 内部每一次决策无论是排查 bug、理解 tree-shaking 行为还是调研代码生成细节都会事半功倍。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rolldown 调试利器：基于 tracing 与 RD_LOG 的源码级日志系统实战指南
Rolldown 调试利器基于 tracing 与 RD_LOG 的源码级日志系统实战指南【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldownRolldown 是一款以 Rust 实现的 JavaScript/TypeScript 打包器其代码库在打包链路的各个阶段埋设了大量tracing::debug!/tracing::trace!日志调用。本文围绕 Rolldown 的 Tracing/Logging 机制讲解如何通过RD_LOG环境变量按需开启日志、如何理解与配置多种输出格式并给出在源码中新增日志与使用函数级过滤器的最佳实践帮助你快速定位 bug、理解打包器每一步的行为。为什么需要一套日志系统Rolldown 的打包流程横跨模块解析、链接link、tree-shaking、代码生成等多个阶段逻辑复杂且高度并发。直接打断点或在代码中临时插入打印语句往往效率低下。为此代码库在大量关键路径上埋设了tracing::debug!或tracing::trace!调用正如关联文档 docs/development-guide/tracing-logging.md 所述这些日志即使在无法直接定位 bug 时也能帮你大幅缩小问题范围或者帮助你理解编译器打包器为什么要做某件事。由于 tracing 的引入会拖慢打包速度Rolldown 默认不开启任何日志。只有当你显式设置环境变量RD_LOG时日志基础设施才会被初始化。这一设计在 crates/rolldown_tracing/src/lib.rs 中有直接体现pub fn try_init_tracing() - OptionBoxdyn Any Send { let Ok(env_var) std::env::var(LOG_ENV_NAME) else { // tracing will slow down the bundling process, so we only enable it when LOG is set. return None; }; ... }未设置RD_LOG时直接返回None整套订阅器不会被注册因此正常运行不受任何性能影响。快速上手用 RD_LOG 开启日志开启日志只需为你的打包命令设置RD_LOG环境变量值为一个日志过滤器log filter。RD_LOG的取值遵循tracing-subscriber中EnvFilter/Targets的指令语法例如# 输出所有 debug 级别及以上的日志 RD_LOGdebug rolldown -i ./input.js # 只关注某个目标target的日志例如模块解析 RD_LOGoxc_resolver rolldown -i ./input.js # 按模块路径过滤 RD_LOGrolldowndebug,oxc_resolverinfo rolldown -i ./input.js过滤器的完整语法如crate_namelevel、多指令用逗号分隔等可以参考tracing-subscriber的EnvFilter文档中关于 directives 的说明。在 Rolldown 的实现中RD_LOG的值被解析为Targets见 crates/rolldown_tracing/src/lib.rslet targets match Targets::from_str(env_var) { Ok(targets) targets, Err(error) { report_tracing_init_failure(format!(invalid {LOG_ENV_NAME} filter: {error})); return None; } };值得注意的一个实现细节如果过滤器格式非法Rolldown 不会 panic而是打印一条告警并静默禁用 tracing。集成测试 crates/rolldown_tracing/tests/invalid_filter_fallback.rs 专门验证了这一行为#[test] fn invalid_rd_log_filter_disables_tracing_instead_of_panicking() { unsafe { std::env::set_var(RD_LOG, rolldownnot_a_level); std::env::remove_var(RD_LOG_OUTPUT); } let guard rolldown_tracing::try_init_tracing(); assert!(guard.is_none(), invalid filter should disable tracing, not panic); }这个测试之所以独立成二进制运行是因为try_init_tracing内部通过IS_INITIALIZED全局原子标志保证只初始化一次见 crates/rolldown_tracing/src/lib.rs同一进程内无法重复初始化。控制输出格式RD_LOG_OUTPUT默认情况下日志以可读文本形式输出到 stdout。除此之外Rolldown 还支持将 tracing 事件导出为 Chrome 性能分析工具chrome://tracing / Perfetto可加载的 JSON 文件用于可视化打包各阶段的耗时与调用关系# 普通文本日志 RD_LOGdebug rolldown -i ./input.js # 导出 chrome-json 格式的追踪文件 RD_LOGdebug RD_LOG_OUTPUTchrome-json rolldown -i ./input.js关联文档 docs/development-guide/tracing-logging.md 明确指出RD_LOG_OUTPUTchrome-json需要以chrome-tracingcargo feature 构建该 feature 在 profile 构建pnpm build-binding:profile中启用但在 release 构建中禁用以保持产物更小。未启用时rolldown 会回退到可读的 stdout 输出并打印一条警告。从源码看RD_LOG_OUTPUT支持多种取值见 crates/rolldown_tracing/src/lib.rsRD_LOG_OUTPUT 取值行为chrome-json使用ChromeLayerBuilder以TraceStyle::Async风格导出异步追踪chrome-json-threaded以TraceStyle::Threaded风格导出按线程组织事件json当前未实现打印告警并回退到可读输出readable强制可读的 pretty 文本输出默认行为其他 / 未设置默认可读输出并开启 span 的ENTER/CLOSE事件其中chrome-json分支在没有启用chrome-tracingfeature 时会编译进一段回退逻辑#[cfg(not(feature chrome-tracing))] { eprintln!( RD_LOG_OUTPUT{output_mode} requires building with the chrome-tracing feature, \ which is disabled in release builds. Falling back to readable stdout output. \ Build a profile binary (pnpm build-binding:profile) to enable chrome tracing. ); ... }因此如果你需要可视化分析请确保使用 profile 构建即pnpm build-binding:profile来运行具体构建步骤可参考 docs/development-guide/building-and-running.md。另外crates/rolldown_tracing/src/lib.rs 的注释中还提到一种组合用法RD_LOGtrace RD_LOG_OUTPUTchrome-json rolldown ... RD_LOG_OUTPUT_STYLEasync其中RD_LOG_OUTPUT_STYLEasync用于将 trace 记录为一组异步操作适合分析并发打包过程中的跨任务依赖关系。统一的初始化入口与过滤规则无论选择哪种输出模式初始化都会经过统一的过滤管线crates/rolldown_tracing/src/lib.rslet filter_for_removing_devtools_event filter_fn(|metadata| { const ALLOW: bool true; const REJECT: bool false; if metadata.is_event() metadata.fields().field(devtoolsAction).is_some() { return REJECT; } ALLOW });凡是带有devtoolsAction字段的事件仅供开发调试工具 devtools 使用都会被剔除不会污染普通日志输出。同时tracing 基础设施的初始化入口try_init_tracing是在打包器工厂中触发的见 crates/rolldown/src/bundle/bundle_factory.rsif opts.disable_tracing_setup { None } else { rolldown_tracing::try_init_tracing() };这也说明通过 bundler 选项disable_tracing_setup可以显式关闭 tracing 的初始化方便某些宿主环境如已自行接入 tracing 的调用方自行管理订阅器。在源码中新增日志选择正确的级别Rolldown 欢迎贡献者在 PR 中加入tracing::debug!或tracing::trace!调用但为了避免日志噪音需要谨慎选择日志级别。关联文档给出了清晰的决策规则场景推荐级别不确定选哪个级别tracing::trace!打包过程中只会打印一次tracing::debug!只会打印一次、但内容大小与输入规模相关tracing::trace!会打印多次、但次数有限tracing::debug!因输入规模而打印多次tracing::trace!核心原则一句话概括与输入规模模块数量、依赖数量成正比增长的日志应该用trace级别只有固定次数、内容量可控的日志才适合debug级别。在真实代码库中这些调用遍布各个阶段。例如 crates/rolldown/src/stages/link_stage/tree_shaking/include_statements.rs、crates/rolldown/src/stages/link_stage/bind_imports_and_exports.rs、crates/rolldown/src/stages/generate_stage/order_analysis.rs 等文件中均有tracing::debug!/tracing::trace!调用你可以直接阅读这些示例来感受级别的选取粒度。一个容易踩的坑#[tracing::instrument]的级别上述规则同样适用于#[tracing::instrument]属性函数在打包过程中只调用一次使用#[tracing::instrument(level debug, skip_all)]函数因输入规模被多次调用使用#[tracing::instrument(level trace, skip_all)]注意文档原文第 33 行给出的示例写作#[tracing::instrument(level trace, skip_all]实际正确的属性语法是skip_all)使用时应留意。需要说明的是哪些信息值得被追踪带有较强的主观性opinionated因此 reviewer 会在合并前决定保留还是要求移除这些 tracing 语句。函数级过滤器用 #[instrument] 缩小排查范围Rolldown 中大量函数使用#[instrument]属性标注例如#[instrument(level debug, skip(self))] fn foo(self, bar: Type) {} #[instrument(level debug, skip_all)] fn baz(self, bar: Type) {}一旦函数被#[instrument]包裹你可以通过如下形式的过滤器一次性完成三件事RUSTC_LOG[foo]注意这里演示的键名是文档中的通用写法在 Rolldown 中实际使用的环境变量是RD_LOG例如RD_LOG[foo]。开启后可以记录对foo的所有函数调用打印 span 进入/退出记录函数的入参skip列表中排除的参数除外在函数返回之前记录该函数执行期间来自其他任何位置的日志事件——相当于把整个调用子树纳入了可见范围。配套两个注意点默认推荐使用skip_all除非你有充分的理由需要记录参数值参数打印可能产生大量噪音也可能涉及大对象序列化成本需要打印特定参数时用skip(self)这类白名单外的形式保留个别参数其余全部跳过。这种按函数名开日志的方式比全局开启RD_LOGdebug噪音小得多适合针对某个可疑阶段做定点观测。追踪模块解析oxc_resolver 的调试输出模块解析是打包器最容易出问题、也最值得调试的环节之一。Rolldown 使用 oxc-resolver文档中指向的第三方解析库进行模块解析它对外暴露了调试用的 trace 信息。开启方式RD_LOGoxc_resolver rolldown这会输出oxc_resolver::resolve函数的 trace 信息例如2024-06-11T07:12:20.003537Z DEBUG oxc_resolver: options: ResolveOptions { ... }, path: ..., specifier: ..., ret: ... at /path/to/oxc_resolver-1.8.1/src/lib.rs:212 in oxc_resolver::resolve with path: ..., specifier: ...解读这条日志输入值options解析选项、path当前模块路径、specifier被解析的导入说明符返回值ret解析结果。通过观察specifier与ret的对应关系你可以迅速判断某个导入为什么被解析到某个路径、为什么走了node_modules中的某个版本、为什么解析失败等。结合函数级过滤器还可以进一步跟踪resolve内部更细粒度的调用栈。排查工作流建议综合上述机制推荐如下调试工作流粗定位先RD_LOGdebug全局开启观察打包过程在哪一阶段出现异常行为或报错细定位根据日志中的 target/span 名称改用RD_LOG[可疑函数名]或RD_LOG模块名debug聚焦某个模块解析问题怀疑模块解析问题时直接RD_LOGoxc_resolver跟踪 specifier 与 ret性能分析需要分析各阶段耗时与调用关系时用 profile 构建pnpm build-binding:profile配合RD_LOGdebug RD_LOG_OUTPUTchrome-json导出可视化 trace确认修复修复后重新对比日志输出验证行为符合预期若日志噪音过大检查是否有与输入规模成正比的日志被错误地放在了debug级别。这套日志系统的所有核心逻辑都集中在 crates/rolldown_tracing/src/lib.rs它是理解整个 tracing 行为的首选入口而 crates/rolldown_tracing/tests 下的集成测试则固化了非法过滤器不 panic等关键行为契约。掌握 RD_LOG 的用法你就能像外科手术一样精准地看到 Rolldown 内部每一次决策无论是排查 bug、理解 tree-shaking 行为还是调研代码生成细节都会事半功倍。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考