Crate log

Utilities for program-wide and customizable logging

Example

#[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 = 3i * 4i; // 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:

• log!(level, ...) - the generic logging macro, takes a level as a u32 and any related format! arguments
• debug!(...) - a macro hard-wired to the log level of DEBUG
• info!(...) - a macro hard-wired to the log level of INFO
• warn!(...) - a macro hard-wired to the log level of WARN
• error!(...) - a macro hard-wired to the log level of ERROR

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:

• log_enabled!(level) - returns true if logging of the given level is enabled

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:

• hello turns on all logging for the 'hello' module
• info turns on all info logging
• hello=debug turns on debug logging for 'hello'
• hello=3 turns on info logging for 'hello'
• hello,std::option turns on hello, and std's option logging
• error,hello=warn turn on global error logging and also warn for hello

Filtering results

A RUST_LOG directive may include a regex filter. The syntax is to append / followed by a regex. Each message is checked against the regex, and is only logged if it matches. 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:

• hello/foo turns on all logging for the 'hello' module where the log message includes 'foo'.
• info/f.o turns on all info logging where the log message includes 'foo', 'f1o', 'fao', etc.
• hello=debug/foo*foo turns on debug logging for 'hello' where the log message includes 'foofoo' or 'fofoo' or 'fooooooofoo', etc.
• error,hello=warn/[0-9] scopes turn on global error logging and also warn for hello. In both cases the log message must include a single digit number followed by 'scopes'

Performance and Side Effects

Each of these macros will expand to code similar to:

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

Logging macros

Macros

debug!	A convenience macro for logging at the debug log level. This macro can also be omitted at compile time by passing --cfg ndebug to the compiler. If this option is not passed, then debug statements will be compiled.
error!	A convenience macro for logging at the error log level.
info!	A convenience macro for logging at the info log level.
log!	The standard logging macro
log_enabled!	A macro to test whether a log level is enabled for the current module.
warn!	A convenience macro for logging at the warning log level.

Structs

LogLevel	Wraps the log level with fmt implementations.
LogRecord	A LogRecord is created by the logging macros, and passed as the only argument to Loggers.

Constants

DEBUG	Debug log level
ERROR	Error log level
INFO	Info log level
MAX_LOG_LEVEL	Maximum logging level of a module that can be specified. Common logging levels are found in the DEBUG/INFO/WARN/ERROR constants.
WARN	Warn log level

Traits

Logger

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

Functions

set_logger

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