Crate cli_log[][src]

Expand description

The boilerplate to have some file logging with a level given by an environment variable, and a facility to log execution durations according to the relevant log level.

It’s especially convenient for terminal applications because you don’t want to mix log with stdout or stderr.

The use of an env variable makes it possible to distribute the application and have users generate some logs without recompilation or configuration.

The names of the log file and the env variable are computed from the name of the application.

So log initialization is just

use cli_log::*; // also import logging macros
init_cli_log!();

If you prefer not having to declare cli_log import for all the log and cli-log logging macros, you may use the old #[macro_use] import in your main.rs file:

#[macro_use] extern crate cli_log;
init_cli_log!();

With the "mem" feature (enabled by default), when the OS is compatible (unix like), you may dump the current and peak memory usage with the log_mem function.

Here’s a complete application using cli-log (it can be found in examples):

use cli_log::*;

#[derive(Debug)]
struct AppData {
    count: usize,
}
impl AppData {
    fn compute(&mut self) {
        self.count += 7;
    }
}

fn main() {
    init_cli_log!();
    let mut app_data = AppData { count: 35 };
    time!(Debug, app_data.compute());
    info!("count is {}", app_data.count);
    debug!("data: {:#?}", &app_data);
    warn!("this application does nothing");
    log_mem(Level::Info);
    info!("bye");
}

If you don’t set any SMALL_APP_LOG env variable, there won’t be any log.

A convenient way to set the env variable is to launch the app as

SMALL_APP_LOG=debug small_app

or, during development,

SMALL_APP_LOG=debug cargo run

This creates a small_app.log file containing information like the level, app version, and of course the log operations you did with time precise to the ms and the logging module (target):

21:03:24.081 [INFO] cli_log::init: Starting small-app v1.0.1 with log level DEBUG
21:03:24.081 [DEBUG] small_app: app_data.compute() took 312ns
21:03:24.081 [INFO] small_app: count is 42
21:03:24.081 [DEBUG] small_app: data: AppData {
    count: 42,
}
21:03:24.081 [WARN] small_app: this application does nothing
21:03:24.081 [INFO] cli_log::mem: Physical mem usage: current=938K, peak=3.3M
21:03:24.082 [INFO] small_app: bye

Macros

debug

Logs a message at the debug level.

error

Logs a message at the error level.

info

Logs a message at the info level.

init_cli_log

configure the application log according to env variable

log

The standard logging macro.

log_enabled

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

time

print the time that executing some expression took but only when relevant according to log level.

trace

Logs a message at the trace level.

warn

Logs a message at the warn level.

Structs

Metadata

Metadata about a log message.

MetadataBuilder

Builder for Metadata.

ParseLevelError

The type returned by from_str when the string doesn’t match any of the log levels.

Record

The “payload” of a log message.

RecordBuilder

Builder for Record.

SetLoggerError

The type returned by set_logger if set_logger has already been called.

Enums

Level

An enum representing the available verbosity levels of the logger.

LevelFilter

An enum representing the available verbosity level filters of the logger.

Constants

STATIC_MAX_LEVEL

The statically resolved maximum log level.

Traits

Log

A trait encapsulating the operations required of a logger.

Functions

init

configure the application log according to env variable.

log_mem

log the current and peak physical memory used by the current process, if the given log level is reached

logger

Returns a reference to the logger.

max_level

Returns the current maximum log level.

set_boxed_logger

Sets the global logger to a Box<Log>.

set_logger

Sets the global logger to a &'static Log.

set_logger_racy

A thread-unsafe version of set_logger.

set_max_level

Sets the global maximum log level.