Crate holochain_logging

Holochain's log implementation.

This logger implementation is designed to be fast and to provide useful filtering combination capabilities.

Use

The basic use of the log crate is through the five logging macros: error!, warn!, info!, debug! and trace! where error! represents the highest-priority log messages and trace! the lowest. The log messages are filtered by configuring the log level to exclude messages with a lower priority. Each of these macros accept format strings similarly to println!.

Quick Start

To get you started quickly, the easiest and highest-level way to get a working logger (with the Info log verbosity level) is to use init_simple.

use holochain_logging::prelude::*;

// We need a guard here in order to gracefully shutdown
// the logging thread
let mut guard = holochain_logging::init_simple().unwrap();
info!("Here you go champ!");

// Warning and Error log message have their own color
warn!("You've been warned Sir!");
error!("Oh... something wrong pal.");

// Flushes any buffered records
guard.flush();
// Flush and shutdown gracefully the logging thread
guard.shutdown();

Examples

Simple log with Trace verbosity level.

In order to log everything with at least the Debug verbosity level:

use holochain_logging::prelude::*;

// We need a guard here in order to gracefully shutdown
// the logging thread
let mut guard = FastLoggerBuilder::new()
    // The timestamp format is customizable as well
    .timestamp_format("%Y-%m-%d %H:%M:%S%.6f")
    .set_level_from_str("Debug")
    .build()
    .expect("Fail to init the logging factory.");

debug!("Let's trace what that program is doing.");

// Flushes any buffered records
guard.flush();
// Flush and shutdown gracefully the logging thread
guard.shutdown();

Building the logging factory from TOML configuration.

The logger can be built from a TOML configuration file:

use holochain_logging::prelude::*;
let toml = r#"
   [logger]
   level = "debug"

        [[logger.rules]]
        pattern = "info"
        exclude = false
        color = "Blue"
    "#;
// We need a guard here in order to gracefully shutdown
// the logging thread
let mut guard = FastLoggerBuilder::from_toml(toml)
    .expect("Fail to instantiate the logger from toml.")
     .build()
     .expect("Fail to build logger from toml.");

// Should NOT be logged because of the verbosity level set to Debug
trace!("Track me if you can.");
debug!("What's bugging you today?");

// This one is colored in blue because of our rule on 'info' pattern
info!("Some interesting info here");

// Flushes any buffered records
guard.flush();
// Flush and shutdown gracefully the logging thread
guard.shutdown();

Dependency filtering

Filtering out every log from dependencies and putting back in everything related to a particular target

use holochain_logging::prelude::*;

let toml = r#"
    [logger]
    level = "debug"

        [[logger.rules]]
        pattern = ".*"
        exclude = true

        [[logger.rules]]
        pattern = "^holochain"
        exclude = false
    "#;
// We need a guard here in order to gracefully shutdown
// the logging thread
let mut guard = FastLoggerBuilder::from_toml(toml)
    .expect("Fail to instantiate the logger from toml.")
    .build()
    .expect("Fail to build logger from toml.");

// Should NOT be logged
debug!(target: "rpc", "This is our dependency log filtering.");

// Should be logged each in different color. We avoid filtering by prefixing using the 'target'
// argument.
info!(target: "holochain", "Log message from Holochain Core.");
info!(target: "holochain-app-2", "Log message from Holochain Core with instance ID 2");

// Flushes any buffered records
guard.flush();
// Flush and shutdown gracefully the logging thread
guard.shutdown();

Modules

color	This is where we handle the color of the logging messages. Greatly inspired by the fern crate.
prelude	Convenience re-export of common members
rule	Log filtering facility: add the capability to filter out by regex log messages and/or colorize them.

Structs

FastLogger	The logging struct where we store everything we need in order to correctly log stuff.
FastLoggerBuilder	Logger Builder used to correctly set up our logging capability.

Functions

init_simple

Initialize a simple logging instance with Info log level verbosity or retrieve the level from the RUST_LOG environment variable and no rule filtering.