env_logger

In an executable, env_logger should be initialized as early as possible in the main function. Once initialized, you can use macros from the log crate (like info!, warn!, error!, etc.) to emit log messages.

Control the visibility of these messages at runtime using the RUST_LOG environment variable.

use log::info;

fn main() {
    env_logger::init();

    info!("starting up");

    // ...
}

To use env_logger in a binary project, you must add both log and env_logger to your project dependencies.

Use the following command to add them via cargo:

$ cargo add log env_logger

The env_filter crate parses logging specification strings to determine which modules should log at which levels and applies optional regex filters.

Syntax Structure

A specification string follows this pattern: [directives]/[filter]

1. Directives: A comma-separated list of module/crate specifications. Each directive can be:
   • name=level: e.g., crate1::mod3=error
   • name: e.g., crate1::mod3 (defaults to LevelFilter::max())
   • level: e.g., warn (applies the level globally, with no specific name)
2. Filter: An optional regex filter following a single / character.

Examples

• crate1,crate2::mod3,crate3::x=error/foo
• crate1::mod1=error,crate1::mod2,crate2=debug
• warn,crate2=debug (sets global level to warn and crate2 to debug)
• crate1/abc (sets crate1 to max level and applies regex filter abc)

When using the default format, you can control the precision of the included timestamps using the TimestampPrecision enum via the timestamp method on ConfigurableFormat.

Available precisions:

• Seconds: Full second precision (0 decimal digits).
• Millis: Millisecond precision (3 decimal digits).
• Micros: Microsecond precision (6 decimal digits).
• Nanos: Nanosecond precision (9 decimal digits).

Note: Timestamp functionality requires the humantime feature.

// Example of setting millisecond precision
// (Assuming access to ConfigurableFormat via Builder)
config.timestamp(Some(TimestampPrecision::Millis));

The RUST_LOG environment variable determines which log messages are displayed. The level names are case-insensitive (e.g., info, INFO, and iNfO are all valid).

Supported log levels from the log crate:

• error
• warn
• info
• debug
• trace
• off (a pseudo-level used to disable all logging for a module or the application)

Example usage:

$ RUST_LOG=info ./main

$ RUST_LOG=INFO ./main

By default, cargo test captures and hides logs. To ensure logs are captured and visible in the test output, use the Builder::is_test(true) method in your test initialization code.

#[cfg(test)]
mod tests {
    use log::info;

    fn init() {
        // is_test(true) ensures logs are captured by the test harness
        let _ = env_logger::builder().is_test(true).try_init();
    }

    #[test]
    fn it_works() {
        init();
        info!("This record will be captured by `cargo test`");
        assert_eq!(2, 1 + 1);
    }
}

The Builder struct is used to configure and construct a Filter. You can define logging rules programmatically by specifying modules and levels, or by parsing a directive string (e.g., from an environment variable).

To use the builder:

1. Initialize it with Builder::new().
2. Add rules using .filter(), .filter_module(), or .filter_level().
3. Alternatively, parse a string using .parse() (which ignores errors and prints warnings to stderr) or .try_parse() (which returns a Result).
4. Finalize the configuration by calling .build().

# use log::LevelFilter;
# use env_filter::Builder;

let mut builder = Builder::new();

// Parse a logging filter from an environment variable.
if let Ok(rust_log) = std::env::var("RUST_LOG") {
    builder.parse(&rust_log);
}

let filter = builder.build();