Crate log [−] [src]

Unstable (rustc_private)

: use the crates.io log library instead

Utilities for program-wide and customizable logging

Examples

#![feature(rustc_private)] #[macro_use] extern crate log; fn main() { debug!("this is a debug {:?}", "message"); error!("this is printed by default"); if log_enabled!(log::INFO) { let x = 3 * 4; // expensive computation info!("the answer was: {:?}", x); } } 
#[macro_use] extern crate log;

fn main() {
    debug!("this is a debug {:?}", "message");
    error!("this is printed by default");

    if log_enabled!(log::INFO) {
        let x = 3 * 4; // expensive computation
        info!("the answer was: {:?}", x);
    }
}

Assumes the binary is main:

$ RUST_LOG=error ./main
ERROR:main: this is printed by default

$ RUST_LOG=info ./main
ERROR:main: this is printed by default
INFO:main: the answer was: 12

$ RUST_LOG=debug ./main
DEBUG:main: this is a debug message
ERROR:main: this is printed by default
INFO:main: the answer was: 12

You can also set the log level on a per module basis:

$ RUST_LOG=main=info ./main
ERROR:main: this is printed by default
INFO:main: the answer was: 12

And enable all logging:

$ RUST_LOG=main ./main
DEBUG:main: this is a debug message
ERROR:main: this is printed by default
INFO:main: the answer was: 12

Logging Macros

There are five macros that the logging subsystem uses:

All of these macros use the same style of syntax as the format! syntax extension. Details about the syntax can be found in the documentation of std::fmt along with the Rust tutorial/manual.

If you want to check at runtime if a given logging level is enabled (e.g. if the information you would want to log is expensive to produce), you can use the following macro:

Enabling logging

Log levels are controlled on a per-module basis, and by default all logging is disabled except for error! (a log level of 1). Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. A logging directive is of the form:

path::to::module=log_level

The path to the module is rooted in the name of the crate it was compiled for, so if your program is contained in a file hello.rs, for example, to turn on logging for this file you would use a value of RUST_LOG=hello. Furthermore, this path is a prefix-search, so all modules nested in the specified module will also have logging enabled.

The actual log_level is optional to specify. If omitted, all logging will be enabled. If specified, the it must be either a numeric in the range of 1-255, or it must be one of the strings debug, error, info, or warn. If a numeric is specified, then all logging less than or equal to that numeral is enabled. For example, if logging level 3 is active, error, warn, and info logs will be printed, but debug will be omitted.

As the log level for a module is optional, the module to enable logging for is also optional. If only a log_level is provided, then the global log level for all modules is set to this value.

Some examples of valid values of RUST_LOG are:

Filtering results

A RUST_LOG directive may include a string filter. The syntax is to append / followed by a string. Each message is checked against the string and is only logged if it contains the string. Note that the matching is done after formatting the log string but before adding any logging meta-data. There is a single filter for all modules.

Some examples:

Performance and Side Effects

Each of these macros will expand to code similar to:

extern crate log; fn main() { if log_level <= my_module_log_level() { ::log::log(log_level, format!(...)); } }
if log_level <= my_module_log_level() {
    ::log::log(log_level, format!(...));
}

What this means is that each of these macros are very cheap at runtime if they're turned off (just a load and an integer comparison). This also means that if logging is disabled, none of the components of the log will be executed.

Modules

macros [Unstable]

Logging macros

Macros

debug! [Unstable]

A convenience macro for logging at the debug log level. This macro will be omitted at compile time in an optimized build unless -C debug-assertions is passed to the compiler.
error! [Unstable]

A convenience macro for logging at the error log level.
info! [Unstable]

A convenience macro for logging at the info log level.
log! [Unstable]

The standard logging macro
log_enabled! [Unstable]

A macro to test whether a log level is enabled for the current module.
warn! [Unstable]

A convenience macro for logging at the warning log level.

Structs

LogLevel [Unstable]

Wraps the log level with fmt implementations.
LogRecord [Unstable]

A LogRecord is created by the logging macros, and passed as the only argument to Loggers.

Constants

DEBUG [Unstable]

Debug log level
ERROR [Unstable]

Error log level
INFO [Unstable]

Info log level
MAX_LOG_LEVEL [Unstable]

Maximum logging level of a module that can be specified. Common logging levels are found in the DEBUG/INFO/WARN/ERROR constants.
WARN [Unstable]

Warn log level

Traits

Logger [Unstable]

A trait used to represent an interface to a thread-local logger. Each thread can have its own custom logger which can respond to logging messages however it likes.

Functions

set_logger [Unstable]

Replaces the thread-local logger with the specified logger, returning the old logger.