Crate fern

Efficient, configurable logging in Rust.

With Fern, you can:

• Configure logging at runtime; make changes based off of user arguments or configuration
• Format log records without allocating intermediate results
• Output to stdout, stderr, log files and custom destinations
• Apply a blanket level filter and per-crate/per-module overrides
• Intuitively apply filters and formats to groups of loggers via builder chaining
• Log using the standard log crate macros

Depending on fern

First, depend on the fern and log crates in your project's Cargo.toml:

[dependencies]
log = "0.4"
fern = "0.5"

Then declare both in your program's main.rs or lib.rs:

#[macro_use]
extern crate log;
extern crate fern;

Example setup:

In fern 0.4+, creating, configuring, and establishing a logger as the global logger are all merged into builder methods on the Dispatch struct.

Here's an example logger which formats messages, limits to Debug level, and puts everything into both stdout and an output.log file.

extern crate chrono;

fern::Dispatch::new()
    .format(|out, message, record| {
        out.finish(format_args!(
            "{}[{}][{}] {}",
            chrono::Local::now().format("[%Y-%m-%d][%H:%M:%S]"),
            record.target(),
            record.level(),
            message
        ))
    })
    .level(log::LevelFilter::Debug)
    .chain(std::io::stdout())
    .chain(fern::log_file("output.log")?)
    .apply()?;

Let's unwrap the above example:

---

fern::Dispatch::new()

Create an empty logger config.

---

.format(|...| ...)

Add a formatter to the logger, modifying all messages sent through.

---

chrono::Local::now()

Get the current time in the local timezone using the chrono library. See the time-and-date docs.

---

.format("[%Y-%m-%d][%H:%M:%S]")

Use chrono's lazy format specifier to turn the time into a readable string.

---

out.finish(format_args!(...))

Call the fern::FormattingCallback to submit the formatted message.

Fern uses this callback style to allow usage of std::fmt formatting without the allocation that would be needed to return the formatted result.

format_args!() has the same arguments as println!() or any other std::fmt-based macro.

The final output of this formatter will be:

[2017-01-20][12:55:04][crate-name][INFO] Something happened.

---

.level(log::LevelFilter::Debug)

Set the minimum level needed to output to Debug.

This accepts Debug, Info, Warn and Error level messages, and denies the lowest level, Trace.

---

.chain(std::io::stdout())

Add a child to the logger; send all messages to stdout.

Dispatch::chain accepts Stdout, Stderr, Files and other Dispatch instances.

---

.chain(fern::log_file(...)?)

Add a second child; send all messages to the file "output.log".

See fern::log_file() for more info on file output.

---

.apply()

Consume the configuration and instantiate it as the current runtime global logger.

This will fail if and only if another fern or log logger has already been set as the global logger.

Since it's really up to the binary-producing crate to set up logging, the apply result can be reasonably unwrapped or ignored.

Logging

Once the logger has been set using apply it will pick up all log macro calls from your crate and all your libraries.

#[macro_use]
extern crate log;
extern crate fern;

fern::Dispatch::new()
    // ...
    .apply()?;

trace!("Trace message");
debug!("Debug message");
info!("Info message");
warn!("Warning message");
error!("Error message");

More configuration

Check out the Dispatch documentation and the full example program for more usages.

Structs

Dispatch	The base dispatch logger.
FormatCallback	Callback struct for use within a formatter closure
Output	Configuration for a logger output.

Enums

InitError

Convenience error combining possible errors which could occur while initializing logging.

Functions

log_file

Convenience method for opening a log file with common options.

Type Definitions

Filter	A type alias for a log filter. Returning true means the record should succeed - false means it should fail.
Formatter	A type alias for a log formatter.