Using Tracing to Debug the Rust Compiler

# Using tracing to debug the compiler  The compiler has a lot of [`debug!`] (or `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. To see the logs, you need to set the `RUSTC_LOG` environment variable to your log filter. The full syntax of the log filters can be found in the [rustdoc of `tracing-subscriber`](https://docs.rs/tracing-subscriber/0.2.24/tracing_subscriber/filter/struct.EnvFilter.html#directives). ## Function level filters Lots of functions in rustc are annotated with ``` #[instrument(level = "debug", skip(self))] fn foo(&self, bar: Type) {} ``` which allows you to use ``` RUSTC_LOG=[foo] ``` to do the following all at once * log all function calls to `foo` * log the arguments (except for those in the `skip` list) * log everything (from anywhere else in the compiler) until the function returns ### I don't want everything Depending on the scope of the function, you may not want to log everything in its body. As an example: the `do_mir_borrowck` function will dump hundreds of lines even for trivial code being borrowchecked. Since you can combine all filters, you can add a crate/module path, e.g. ``` RUSTC_LOG=rustc_borrowck[do_mir_borrowck] ``` ### I don't want all calls If you are compiling libcore, you likely don't want *all* borrowck dumps, but only one for a specific function. You can filter function calls by their arguments by regexing them. ``` RUSTC_LOG=[do_mir_borrowck{id=\.\*from_utf8_unchecked\.\*}] ``` will only give you the logs of borrowchecking `from_utf8_unchecked`. Note that you will still get a short message per ignored `do_mir_borrowck`, but none of the things inside those calls. This helps you in looking through the calls that are happening and helps you adjust your regex if you mistyped it. ## Query level filters Every [query](query.md) is automatically tagged with a logging span so that you can display all log messages during the execution of the query. For example, if you want to log everything during type checking: ``` RUSTC_LOG=[typeck] ``` The query arguments are included as a tracing field which means that you can filter on the debug display of the arguments. For example, the `typeck` query has an argument `key: LocalDefId` of what is being checked. You can use a regex to match on that `LocalDefId` to log type checking for a specific function: ``` RUSTC_LOG=[typeck{key=.*name_of_item.*}] ``` Different queries have different arguments. You can find a list of queries and their arguments in [`rustc_middle/src/query/mod.rs`](https://github.com/rust-lang/rust/blob/master/compiler/rustc_middle/src/query/mod.rs#L18). ## Broad module level filters You can also use filters similar to the `log` crate's filters, which will enable everything within a specific module. This is often too verbose and too unstructured, so it is recommended to use function level filters. Your log filter can be just `debug` to get all `debug!` output and higher (e.g., it will also include `info!`), or `path::to::module` to get *all* output (which will include `trace!`) from a particular module, or `path::to::module=debug` to get `debug!` output and higher from a particular module. For example, to get the `debug!` output and higher for a specific module, you can run the compiler with `RUSTC_LOG=path::to::module=debug rustc my-file.rs`. All `debug!` output will then appear in standard error. Note that you can use a partial path and the filter will still work. For example, if you want to see `info!` output from only `rustdoc::passes::collect_intra_doc_links`, you could use `RUSTDOC_LOG=rustdoc::passes::collect_intra_doc_links=info` *or* you could use `RUSTDOC_LOG=rustdoc::passes::collect_intra=info`. If you are developing rustdoc, use `RUSTDOC_LOG` instead. If you are developing Miri, use `MIRI_LOG` instead. You get the idea :)

The Rust compiler has extensive logging via `debug!` and `trace!` calls. To view these logs, the `RUSTC_LOG` environment variable is used to set log filters. Filters can be applied at the function level (logging function calls, arguments, and everything within the function), query level (logging everything during a specific query execution, filtering by query arguments), or module level (logging everything within a module). More specific filters can be created by applying regexes to the arguments. Rustdoc and Miri have equivalent logging via `RUSTDOC_LOG` and `MIRI_LOG`.