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
Depending on fern
First, 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 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::LogLevelFilter::Debug) .chain(std::io::stdout()) .chain(fern::log_file("output.log")?) .apply()?;
Let's unwrap the above example:
Create an empty logger config.
Add a formatter to the logger, modifying all messages sent through.
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.
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
.
This accepts Debug
, Info
, Warn
and Error
level messages, and denies the lowest level, Trace
.
Add a child to the logger; send all messages to stdout.
Dispatch::chain
accepts Stdout
, Stderr
, File
s and other Dispatch
instances.
Add a second child; send all messages to the file "output.log".
See fern::log_file()
for more info on file output.
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.
Modules
colors |
Module containing color-related functions using the |
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. |
Traits
FernLog |
Fern logging trait. This is necessary in order to allow for custom loggers taking in arguments that have already had a custom format applied to them. |
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. |