[][src]Crate tao_log

Extension macros for output to the rust log crate.

“Why write an RFC, when you can just write code?” — 老子 (“Old Master”), 557 BCE

This unenlightened wanderer (游侠) wrote a log crate PR and RFC 317, before published the work as this standalone crate.

Libraries and applications can use the tao-log macros for all log output needs. This includes re-exported log crate formatted logging and associated macros, and a set of new -v suffix macros (e.g. debugv!) that provide inline expression and value logging, as a superset of std::dbg!. Both sets of macros are given a new overview below, with examples using arbitrary log levels.

If the new macros are eventually accepted to the log crate in compatible form, this crate will be re-released with those re-exports, and possibly deprecated after that.

Using the rust 2018 edition, all exported macros can be imported like a prelude:

use tao_log::*;

Or if desired, import the individual macros:

use tao_log::{debug, debugv, error, warn};

Formatted logging

The original macros for each supported level, from highest to lowest priority (or lowest to highest verbosity) include: error!, warn!, info!, debug! and trace!. These are passed a literal format string, supporting the same syntax as println!, via std::fmt:

use tao_log::*;

info!("Landing gear retracted");
let altitude = 3000;
let target = 10500;
debug!("Altitude target: {}, current: {}", target, altitude);

If for example, the configured maximum logging level is Info, then the above debug! statement does not log, and the cost of formatting the message string is avoided.

Testing for output

The log_enabled! macro may be used to explicitly test if logging is enabled, and may be useful to avoid expensive computations used only for logging.

use tao_log::*;

if log_enabled!(log::Level::Debug) {
    let e = analyze(asteroid); // expensive!
    debug!("Asteroid volume: {}, mass: {}", e.volume(), e.mass());

Inline expression and value logging

The -v macros support inline expression and value logging, as a superset of the std::dbg! macro, for use with the logging system. A single expression argument is evaluated exactly once, regardless of if the logging level is enabled, and its value is returned from the macro. Given this code as a starting point:

use std::time::{Duration, Instant};

let remaining = deadline - Instant::now();

A -v macro may be inserted inline around any expression or sub-expression:

use std::time::{Duration, Instant};
use tao_log::*;

let remaining = debugv!(deadline - Instant::now());
//               ^-- debug log: deadline - Instant::now() → 950µs
debugv!("time until deadline", remaining);
// or            ^-- debug log: time until deadline remaining → 950µs

Note that the value of the expression is moved and then returned. If the type does not implement Copy, ownership may be retained by borrowing by reference, e.g. debugv!(&expr).

The default format string for the -v macros is "{} → {:?}", where the stringify!-ed expression and resulting value are passed, in that order. If the log record is not filtered out, the Debug implementation for the type of the given expression value is used ("{:?}").

The log record can be customized via two optional parameters: a message prefix string, and a format specifier for the value. Note that the former is required, if passing the later:

use tao_log::*;

let i = 32;
infov!("", "{:?}", i);       // equivalent to above
// ^------------------------ info log: i → 32
infov!("index", i);          // prefix for additional context
infov!("index", "{}", i);    // use `Display` format for value
// ^------------------------ info log: index i → 32
infov!("index", "{:#x}", i); // hexadecimal format value
// ^------------------------ info log: index i → 0x20
infov!("index", "{:#?}", i); // pretty multi-line format (for structs)

Specifying the logging target

For all logging macros, the target defaults to the module path of the current location of use, but may be overridden with the target: marker and string literal as the first argument:

use tao_log::*;

let i = 33;
let j = debugv!(target: "maths", "halved", (i-1) / 2);

if log_enabled!(target: "special", log::Level::Info) {
    info!(target: "special", "{}", stats());


pub use log;



Logs a message at the debug level.


Log an expression at the debug level, returning its value.


Logs a message at the error level.


Log an expression at the error level, returning its value.


Logs a message at the info level.


Log an expression at the info level, returning its value.


The standard logging macro.


Determines if a message logged at the specified level in that module will be logged.


Log an expression and its value at any specified level.


Logs a message at the trace level.


Log an expression at the trace level, returning its value.


Logs a message at the warn level.


Log an expression at the warn level, returning its value.