Rolldown 中文网

Appearance

跟踪/日志记录 ​

¥Tracing/Logging

Rolldown 的代码库中有很多 tracing::debug!（或 tracing::trace!）调用，这些调用会在很多地方打印日志信息。这些注释非常有用，即使无法完全找到错误，至少可以缩小错误的位置，或者只是帮助你了解编译器执行特定操作的原因。

¥Rolldown's codebase has a lot of tracing::debug! (or tracing::trace!) calls, which print out logging information at many points. These are very useful to at least narrow down the location of a bug if not to find it entirely, or just to orient yourself as to why the compiler is doing a particular thing.

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

¥To see the logs, you need to set the RD_LOG environment variable to your log filter. The full syntax of the log filters can be found in the rustdoc of tracing-subscriber.

用法 ​

¥Usages

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

添加日志记录 ​

¥Add logging

在你的 PR 中添加 tracing::debug! 或 tracing::trace! 调用是可以的。然而，为了避免日志中出现噪音，你应该谨慎选择 tracing::debug! 或 tracing::trace!。

¥It's fine to add tracing::debug! or tracing::trace! calls in your PRs. However, to avoid noise in the logs, you should be careful about choosing tracing::debug! or tracing::trace!.

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

¥There are some rules that help you to choose right logging level:

  • 如果你不知道选择哪个级别，请使用 tracing::trace!。

    ¥If you don't know what level to choose, use tracing::trace!.

  • 如果在打包过程中日志消息只会打印一次，请使用 tracing::debug!。

    ¥If the log message would only be printed once during the bundling, use tracing::debug!.

  • 如果在打包过程中日志消息只会打印一次，但内容的大小与输入的规模相关，请使用 tracing::trace!。

    ¥If the log message would only be printed once but the size of content is related to the scale of input during the bundling, use tracing::trace!.

  • 如果在打包过程中日志消息会被多次打印但次数有限，请使用 tracing::debug!。

    ¥If the log message would be printed multiple but limited times during the bundling, use tracing::debug!.

  • 如果由于输入的规模导致日志消息会被多次打印，请使用 tracing::trace!。

    ¥If the log message would be printed multiple times due to the scale of the input, use tracing::trace!.

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

¥These rules also apply to the #[tracing::instrument] attribute.

  • 如果在打包过程中该函数仅被调用一次，请使用 #[tracing::instrument(level = "debug", skip_all)]。

    ¥If the function is called only once during the bundling, use #[tracing::instrument(level = "debug", skip_all)].

  • 如果由于输入规模较大而多次调用该函数，请使用 #[tracing::instrument(level = "trace", skip_all]。

    ¥If the function is called multiple times due to the scale of the input, use #[tracing::instrument(level = "trace", skip_all].

信息

哪些信息应该被追踪可能存在争议，因此审核人员将决定是否允许你保留追踪语句，或者是否要求你在合并之前删除它们。

¥What information should be traced could be opinionated, so the reviewer will decide whether to let you leave tracing statements in or whether to ask you to remove them before merging.

函数级过滤器 ​

¥Function level filters

rolldown 中的许多函数都带有注解

¥Lots of functions in rolldown are annotated with

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

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

这允许你使用

¥which allows you to use

RUSTC_LOG=[foo]

为了一次性完成以下操作

¥to do the following all at once

  • 将所有函数调用记录到 foo

    ¥log all function calls to foo

  • 记录参数（skip 列表中的参数除外）

    ¥log the arguments (except for those in the skip list)

  • 记录所有内容（来自编译器中的任何其他位置），直到函数返回

    ¥log everything (from anywhere else in the compiler) until the function returns

注意事项：

¥Notices:

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

¥We generally recommend using skip_all unless you have a good reason to use logging for the arguments.

跟踪模块解析 ​

¥Trace Module Resolution

Rolldown 使用 oxc-resolver，它会公开跟踪信息以供调试。

¥Rolldown uses oxc-resolver, which exposes trace information for debugging purposes.

bash
RD_LOG='oxc_resolver' rolldown

这会触发 oxc_resolver::resolve 函数的跟踪信息，例如：

¥This emits trace information for the oxc_resolver::resolve function, e.g.

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。

¥The input values are options, path and specifier, the returned value is ret.