跟踪/日志记录

Rolldown 的代码库有很多 tracing::debug! （或 tracing::trace!）调用，它们在许多点打印出日志信息。这些功能非常有用，至少可以缩小错误位置的范围（如果不能完全找到错误的话），或者只是确定编译器执行特定操作的原因。

要查看日志，需要将 RD_LOG 环境变量设置为日志过滤器。可以在 tracing-subscriber 的 rustdoc 中找到日志过滤器的完整语法。

使用情况

RD_LOG=debug [executing rolldown]
RD_LOG=debug RD_LOG_OUTPUT=chrome-json [executing rolldown]

添加日志记录

在您的公关中添加 tracing::debug! 或 tracing::trace! 调用是可以的。但是，为了避免日志中的噪音，在选择 tracing::debug! 或 tracing::trace! 时要小心。

有一些规则可以帮助您选择正确的日志记录级别

• 如果您不知道要选择哪个级别，请使用 tracing::trace!。
• 如果日志消息只会在捆绑期间打印一次，请使用 tracing::debug!。
• 如果日志消息只会在捆绑期间打印一次，但内容的大小与捆绑期间输入的规模相关，请使用 tracing::trace!。
• 如果日志消息会在捆绑期间多次但有限地打印，请使用 tracing::debug!。
• 如果由于输入的规模，日志消息会被多次打印，请使用 tracing::trace!。

这些规则也适用于 #[tracing::instrument] 属性。

• 如果函数在捆绑期间仅调用一次，请使用 #[tracing::instrument(level = "debug", skip_all)]。
• 如果函数由于输入的规模而被多次调用，请使用 #[tracing::instrument(level = "trace", skip_all]。

信息

什么信息应该被追踪可能是有争议的，所以审查者将决定是否让你保留追踪语句，或者在合并之前要求你删除它们。

函数级别过滤器

很多 rolldown 中的函数使用进行了注释

#[instrument(level = "debug", skip(self))]
fn foo(&self, bar: Type) {}

#[instrument(level = "debug", skip_all)]
fn baz(&self, bar: Type) {}

这允许你同时使用

RUSTC_LOG=[foo]

来执行以下操作

• 记录所有对函数 foo 的调用
• 记录参数（除了 skip 列表中的参数）
• 记录在函数返回之前的一切内容（来自编译器的任何其他地方）

通知

除非有充分的理由对参数使用日志记录，否则我们通常建议使用 skip_all。

跟踪模块解析

Rolldown 使用 oxc-resolver，它公开了跟踪信息以用于调试目的。

RD_LOG='oxc_resolver' rolldown

这会为函数 oxc_resolver::resolve 发出跟踪信息，例如

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。