rustc_log/
lib.rs

1//! This crate allows tools to enable rust logging without having to magically
2//! match rustc's tracing crate version.
3//!
4//! For example if someone is working on rustc_ast and wants to write some
5//! minimal code against it to run in a debugger, with access to the `debug!`
6//! logs emitted by rustc_ast, that can be done by writing:
7//!
8//! ```toml
9//! [dependencies]
10//! rustc_ast = { path = "../rust/compiler/rustc_ast" }
11//! rustc_log = { path = "../rust/compiler/rustc_log" }
12//! ```
13//!
14//! ```
15//! fn main() {
16//!     rustc_log::init_logger(rustc_log::LoggerConfig::from_env("LOG")).unwrap();
17//!     /* ... */
18//! }
19//! ```
20//!
21//! Now `LOG=debug cargo +nightly run` will run your minimal main.rs and show
22//! rustc's debug logging. In a workflow like this, one might also add
23//! `std::env::set_var("LOG", "debug")` to the top of main so that `cargo
24//! +nightly run` by itself is sufficient to get logs.
25//!
26//! The reason rustc_log is a tiny separate crate, as opposed to exposing the
27//! same things in rustc_driver only, is to enable the above workflow. If you
28//! had to depend on rustc_driver in order to turn on rustc's debug logs, that's
29//! an enormously bigger dependency tree; every change you make to rustc_ast (or
30//! whichever piece of the compiler you are interested in) would involve
31//! rebuilding all the rest of rustc up to rustc_driver in order to run your
32//! main.rs. Whereas by depending only on rustc_log and the few crates you are
33//! debugging, you can make changes inside those crates and quickly run main.rs
34//! to read the debug logs.
35
36use std::env::{self, VarError};
37use std::fmt::{self, Display};
38use std::io::{self, IsTerminal};
39
40use tracing::dispatcher::SetGlobalDefaultError;
41use tracing::{Event, Subscriber};
42use tracing_subscriber::Registry;
43use tracing_subscriber::filter::{Directive, EnvFilter, LevelFilter};
44use tracing_subscriber::fmt::FmtContext;
45use tracing_subscriber::fmt::format::{self, FormatEvent, FormatFields};
46use tracing_subscriber::layer::SubscriberExt;
47// Re-export tracing
48pub use {tracing, tracing_core, tracing_subscriber};
49
50/// The values of all the environment variables that matter for configuring a logger.
51/// Errors are explicitly preserved so that we can share error handling.
52pub struct LoggerConfig {
53    pub filter: Result<String, VarError>,
54    pub color_logs: Result<String, VarError>,
55    pub verbose_entry_exit: Result<String, VarError>,
56    pub verbose_thread_ids: Result<String, VarError>,
57    pub backtrace: Result<String, VarError>,
58    pub wraptree: Result<String, VarError>,
59    pub lines: Result<String, VarError>,
60}
61
62impl LoggerConfig {
63    pub fn from_env(env: &str) -> Self {
64        LoggerConfig {
65            filter: env::var(env),
66            color_logs: env::var(format!("{env}_COLOR")),
67            verbose_entry_exit: env::var(format!("{env}_ENTRY_EXIT")),
68            verbose_thread_ids: env::var(format!("{env}_THREAD_IDS")),
69            backtrace: env::var(format!("{env}_BACKTRACE")),
70            wraptree: env::var(format!("{env}_WRAPTREE")),
71            lines: env::var(format!("{env}_LINES")),
72        }
73    }
74}
75
76/// Initialize the logger with the given values for the filter, coloring, and other options env variables.
77pub fn init_logger(cfg: LoggerConfig) -> Result<(), Error> {
78    init_logger_with_additional_layer(cfg, Registry::default)
79}
80
81/// Trait alias for the complex return type of `build_subscriber` in
82/// [init_logger_with_additional_layer]. A [Registry] with any composition of [tracing::Subscriber]s
83/// (e.g. `Registry::default().with(custom_layer)`) should be compatible with this type.
84/// Having an alias is also useful so rustc_driver_impl does not need to explicitly depend on
85/// `tracing_subscriber`.
86pub trait BuildSubscriberRet:
87    tracing::Subscriber + for<'span> tracing_subscriber::registry::LookupSpan<'span> + Send + Sync
88{
89}
90
91impl<
92    T: tracing::Subscriber + for<'span> tracing_subscriber::registry::LookupSpan<'span> + Send + Sync,
93> BuildSubscriberRet for T
94{
95}
96
97/// Initialize the logger with the given values for the filter, coloring, and other options env variables.
98/// Additionally add a custom layer to collect logging and tracing events via `build_subscriber`,
99/// for example: `|| Registry::default().with(custom_layer)`.
100pub fn init_logger_with_additional_layer<F, T>(
101    cfg: LoggerConfig,
102    build_subscriber: F,
103) -> Result<(), Error>
104where
105    F: FnOnce() -> T,
106    T: BuildSubscriberRet,
107{
108    let filter = match cfg.filter {
109        Ok(env) => EnvFilter::new(env),
110        _ => EnvFilter::default().add_directive(Directive::from(LevelFilter::WARN)),
111    };
112
113    let color_logs = match cfg.color_logs {
114        Ok(value) => match value.as_ref() {
115            "always" => true,
116            "never" => false,
117            "auto" => stderr_isatty(),
118            _ => return Err(Error::InvalidColorValue(value)),
119        },
120        Err(VarError::NotPresent) => stderr_isatty(),
121        Err(VarError::NotUnicode(_value)) => return Err(Error::NonUnicodeColorValue),
122    };
123
124    let verbose_entry_exit = match cfg.verbose_entry_exit {
125        Ok(v) => &v != "0",
126        Err(_) => false,
127    };
128
129    let verbose_thread_ids = match cfg.verbose_thread_ids {
130        Ok(v) => &v == "1",
131        Err(_) => false,
132    };
133
134    let lines = match cfg.lines {
135        Ok(v) => &v == "1",
136        Err(_) => false,
137    };
138
139    let mut layer = tracing_tree::HierarchicalLayer::default()
140        .with_writer(io::stderr)
141        .with_ansi(color_logs)
142        .with_targets(true)
143        .with_verbose_exit(verbose_entry_exit)
144        .with_verbose_entry(verbose_entry_exit)
145        .with_indent_amount(2)
146        .with_indent_lines(lines)
147        .with_thread_ids(verbose_thread_ids)
148        .with_thread_names(verbose_thread_ids);
149
150    if let Ok(v) = cfg.wraptree {
151        match v.parse::<usize>() {
152            Ok(v) => layer = layer.with_wraparound(v),
153            Err(_) => return Err(Error::InvalidWraptree(v)),
154        }
155    }
156
157    let subscriber = build_subscriber();
158    // NOTE: It is important to make sure that the filter is applied on the last layer
159    match cfg.backtrace {
160        Ok(backtrace_target) => {
161            let fmt_layer = tracing_subscriber::fmt::layer()
162                .with_writer(io::stderr)
163                .without_time()
164                .event_format(BacktraceFormatter { backtrace_target });
165            let subscriber = subscriber.with(layer).with(fmt_layer).with(filter);
166            tracing::subscriber::set_global_default(subscriber)?;
167        }
168        Err(_) => {
169            tracing::subscriber::set_global_default(subscriber.with(layer).with(filter))?;
170        }
171    };
172
173    Ok(())
174}
175
176struct BacktraceFormatter {
177    backtrace_target: String,
178}
179
180impl<S, N> FormatEvent<S, N> for BacktraceFormatter
181where
182    S: Subscriber + for<'a> tracing_subscriber::registry::LookupSpan<'a>,
183    N: for<'a> FormatFields<'a> + 'static,
184{
185    fn format_event(
186        &self,
187        _ctx: &FmtContext<'_, S, N>,
188        mut writer: format::Writer<'_>,
189        event: &Event<'_>,
190    ) -> fmt::Result {
191        let target = event.metadata().target();
192        if !target.contains(&self.backtrace_target) {
193            return Ok(());
194        }
195        // Use Backtrace::force_capture because we don't want to depend on the
196        // RUST_BACKTRACE environment variable being set.
197        let backtrace = std::backtrace::Backtrace::force_capture();
198        writeln!(writer, "stack backtrace: \n{backtrace:?}")
199    }
200}
201
202pub fn stdout_isatty() -> bool {
203    io::stdout().is_terminal()
204}
205
206pub fn stderr_isatty() -> bool {
207    io::stderr().is_terminal()
208}
209
210#[derive(Debug)]
211pub enum Error {
212    InvalidColorValue(String),
213    NonUnicodeColorValue,
214    InvalidWraptree(String),
215    AlreadyInit(SetGlobalDefaultError),
216}
217
218impl std::error::Error for Error {}
219
220impl Display for Error {
221    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
222        match self {
223            Error::InvalidColorValue(value) => write!(
224                formatter,
225                "invalid log color value '{value}': expected one of always, never, or auto",
226            ),
227            Error::NonUnicodeColorValue => write!(
228                formatter,
229                "non-Unicode log color value: expected one of always, never, or auto",
230            ),
231            Error::InvalidWraptree(value) => write!(
232                formatter,
233                "invalid log WRAPTREE value '{value}': expected a non-negative integer",
234            ),
235            Error::AlreadyInit(tracing_error) => Display::fmt(tracing_error, formatter),
236        }
237    }
238}
239
240impl From<SetGlobalDefaultError> for Error {
241    fn from(tracing_error: SetGlobalDefaultError) -> Self {
242        Error::AlreadyInit(tracing_error)
243    }
244}
rustc_log/lib.rs

rustc_log/
lib.rs
