Crate fern [−] [src]

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

Fern, while feature-complete, does not have a mature API. The library may be changed in backwards incompatible ways to make it more ergonomic in the future.

Depending on Fern

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

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

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

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

Example usage:

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::LogLevelFilter::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::LogLevelFilter::Debug)

Set the minimum level needed to output to Debug, accepting Debug, Info, Warn, and Error-level messages and denying Trace-level messages.

.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.

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 examples!

Structs

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

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.

Crate fern [−] [src]

Depending on Fern

Example usage:

Logging

More configuration

Structs

Enums

Traits

Functions

Type Definitions