Utilities for program-wide and customizable logging

Example

#[feature(phase)];
#[phase(syntax, link)] 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);
    }
}

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 std::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 std::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 std::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

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.