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_core::{Event, Subscriber};
41use tracing_subscriber::filter::{Directive, EnvFilter, LevelFilter};
42use tracing_subscriber::fmt::FmtContext;
43use tracing_subscriber::fmt::format::{self, FormatEvent, FormatFields};
44use tracing_subscriber::layer::SubscriberExt;
45
46/// The values of all the environment variables that matter for configuring a logger.
47/// Errors are explicitly preserved so that we can share error handling.
48pub struct LoggerConfig {
49    pub filter: Result<String, VarError>,
50    pub color_logs: Result<String, VarError>,
51    pub verbose_entry_exit: Result<String, VarError>,
52    pub verbose_thread_ids: Result<String, VarError>,
53    pub backtrace: Result<String, VarError>,
54    pub wraptree: Result<String, VarError>,
55    pub lines: Result<String, VarError>,
56}
57
58impl LoggerConfig {
59    pub fn from_env(env: &str) -> Self {
60        LoggerConfig {
61            filter: env::var(env),
62            color_logs: env::var(format!("{env}_COLOR")),
63            verbose_entry_exit: env::var(format!("{env}_ENTRY_EXIT")),
64            verbose_thread_ids: env::var(format!("{env}_THREAD_IDS")),
65            backtrace: env::var(format!("{env}_BACKTRACE")),
66            wraptree: env::var(format!("{env}_WRAPTREE")),
67            lines: env::var(format!("{env}_LINES")),
68        }
69    }
70}
71
72/// Initialize the logger with the given values for the filter, coloring, and other options env variables.
73pub fn init_logger(cfg: LoggerConfig) -> Result<(), Error> {
74    let filter = match cfg.filter {
75        Ok(env) => EnvFilter::new(env),
76        _ => EnvFilter::default().add_directive(Directive::from(LevelFilter::WARN)),
77    };
78
79    let color_logs = match cfg.color_logs {
80        Ok(value) => match value.as_ref() {
81            "always" => true,
82            "never" => false,
83            "auto" => stderr_isatty(),
84            _ => return Err(Error::InvalidColorValue(value)),
85        },
86        Err(VarError::NotPresent) => stderr_isatty(),
87        Err(VarError::NotUnicode(_value)) => return Err(Error::NonUnicodeColorValue),
88    };
89
90    let verbose_entry_exit = match cfg.verbose_entry_exit {
91        Ok(v) => &v != "0",
92        Err(_) => false,
93    };
94
95    let verbose_thread_ids = match cfg.verbose_thread_ids {
96        Ok(v) => &v == "1",
97        Err(_) => false,
98    };
99
100    let lines = match cfg.lines {
101        Ok(v) => &v == "1",
102        Err(_) => false,
103    };
104
105    let mut layer = tracing_tree::HierarchicalLayer::default()
106        .with_writer(io::stderr)
107        .with_ansi(color_logs)
108        .with_targets(true)
109        .with_verbose_exit(verbose_entry_exit)
110        .with_verbose_entry(verbose_entry_exit)
111        .with_indent_amount(2)
112        .with_indent_lines(lines)
113        .with_thread_ids(verbose_thread_ids)
114        .with_thread_names(verbose_thread_ids);
115
116    match cfg.wraptree {
117        Ok(v) => match v.parse::<usize>() {
118            Ok(v) => {
119                layer = layer.with_wraparound(v);
120            }
121            Err(_) => return Err(Error::InvalidWraptree(v)),
122        },
123        Err(_) => {} // no wraptree
124    }
125
126    let subscriber = tracing_subscriber::Registry::default().with(filter).with(layer);
127    match cfg.backtrace {
128        Ok(backtrace_target) => {
129            let fmt_layer = tracing_subscriber::fmt::layer()
130                .with_writer(io::stderr)
131                .without_time()
132                .event_format(BacktraceFormatter { backtrace_target });
133            let subscriber = subscriber.with(fmt_layer);
134            tracing::subscriber::set_global_default(subscriber).unwrap();
135        }
136        Err(_) => {
137            tracing::subscriber::set_global_default(subscriber).unwrap();
138        }
139    };
140
141    Ok(())
142}
143
144struct BacktraceFormatter {
145    backtrace_target: String,
146}
147
148impl<S, N> FormatEvent<S, N> for BacktraceFormatter
149where
150    S: Subscriber + for<'a> tracing_subscriber::registry::LookupSpan<'a>,
151    N: for<'a> FormatFields<'a> + 'static,
152{
153    fn format_event(
154        &self,
155        _ctx: &FmtContext<'_, S, N>,
156        mut writer: format::Writer<'_>,
157        event: &Event<'_>,
158    ) -> fmt::Result {
159        let target = event.metadata().target();
160        if !target.contains(&self.backtrace_target) {
161            return Ok(());
162        }
163        // Use Backtrace::force_capture because we don't want to depend on the
164        // RUST_BACKTRACE environment variable being set.
165        let backtrace = std::backtrace::Backtrace::force_capture();
166        writeln!(writer, "stack backtrace: \n{backtrace:?}")
167    }
168}
169
170pub fn stdout_isatty() -> bool {
171    io::stdout().is_terminal()
172}
173
174pub fn stderr_isatty() -> bool {
175    io::stderr().is_terminal()
176}
177
178#[derive(Debug)]
179pub enum Error {
180    InvalidColorValue(String),
181    NonUnicodeColorValue,
182    InvalidWraptree(String),
183}
184
185impl std::error::Error for Error {}
186
187impl Display for Error {
188    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
189        match self {
190            Error::InvalidColorValue(value) => write!(
191                formatter,
192                "invalid log color value '{value}': expected one of always, never, or auto",
193            ),
194            Error::NonUnicodeColorValue => write!(
195                formatter,
196                "non-Unicode log color value: expected one of always, never, or auto",
197            ),
198            Error::InvalidWraptree(value) => write!(
199                formatter,
200                "invalid log WRAPTREE value '{value}': expected a non-negative integer",
201            ),
202        }
203    }
204}