holochain_logging 0.0.6

A logger for Holochain
Documentation

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();