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:
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, accepting Debug, Info, Warn, and Error-level messages and denying Trace-level messages.
Add a child to the logger; send all messages to stdout.
Dispatch::chain
accepts Stdout, Stderr, Files 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.
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. |
Enums
InitError |
Convenience error which combines possible 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. |