When println! isn't enough
You built a CLI tool. It works perfectly on your machine. You send the binary to a friend, and it crashes with no output. Or worse, it prints a wall of text that buries the actual error under fifty lines of routine status messages. You need logs. But println! is blunt. It doesn't filter by severity. It doesn't route to files. It doesn't color-code errors so they pop out of the noise.
You need a logging system that routes messages based on rules. You want the terminal to show colored errors and warnings, while a file captures every debug detail with timestamps. You want to toggle verbosity without changing code. That is what fern does. It builds a flexible pipeline that takes log messages and dispatches them to the right destination with the right format.
The mailroom analogy
Think of fern as a smart mailroom. Your code generates messages using the log crate. Those messages are like envelopes. The mailroom has a rulebook. "If the envelope is marked ERROR, print it in red on the manager's desk. If it's marked DEBUG, file it in the archive. If it's marked TRACE, shred it."
fern builds that rulebook. It does not generate the envelopes. Your code does that via macros like log::info!. fern sits behind the scenes and decides where each envelope goes and how it looks. This separation is key. The log crate defines the interface; fern implements the backend. You can swap fern for another logger later without touching your logging calls.
Minimal setup
Start with the simplest configuration. You want logs to go to the terminal, but only at the Info level and above. Debug and Trace messages should be ignored.
use fern::Dispatch;
use log::{info, LevelFilter};
/// Configures a basic logger that outputs Info and above to stdout.
fn setup_logger() -> Result<(), fern::InitError> {
// Dispatch::new() starts the builder.
// level() sets the global maximum level.
// chain() adds a destination.
// apply() installs the logger globally.
Dispatch::new()
.level(LevelFilter::Info)
.chain(std::io::stdout())
.apply()
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Install the logger before logging anything.
setup_logger()?;
info!("Application started");
log::debug!("This will not appear");
Ok(())
}
Call setup_logger() before you call any logging macros. If you log before applying the dispatch, the message vanishes. The log crate buffers nothing; if no backend is registered, the message is dropped immediately.
How the Dispatch tree works
fern uses a builder pattern. Dispatch::new() creates an empty configuration. You chain methods to add rules. Each method returns a new Dispatch object, allowing you to build the configuration step by step.
The level() method sets a global filter. LevelFilter::Info means Info, Warn, and Error pass through. Debug and Trace are blocked. You can override this per-destination. A file might need Debug details while the console only shows Info.
The chain() method adds an output. You can chain stdout, stderr, files, or custom writers. You can also chain another Dispatch. This creates a tree structure. A nested dispatch can have its own level, format, and targets. This is how you split logs: one branch for the console, one branch for a file.
The apply() method registers the dispatch with the log crate. It returns a Result because it can fail. If you call apply() twice, it panics. The log crate only supports one backend at a time.
Ah-ha moment: the log crate does nothing on its own. If you add log to your Cargo.toml and call info!, you get no output. You must add a backend like fern, env_logger, or tracing. The log crate is a facade. It provides the macros; the backend does the work.
Realistic configuration
Real applications need more than a single output. You want colors in the terminal to make errors stand out. You want a file with timestamps for post-mortem analysis. You want different verbosity levels for each destination.
use fern::{colors::{Color, ColoredLevelConfig}, Dispatch};
use log::{debug, info, LevelFilter};
use std::fs::File;
/// Configures a logger with colored console output and detailed file logging.
fn setup_logger() -> Result<(), fern::InitError> {
// Define colors for log levels.
// This config is shared across branches that use it.
let colors = ColoredLevelConfig::new()
.error(Color::Red)
.warn(Color::Yellow)
.info(Color::Green)
.debug(Color::White);
// Build the dispatch tree.
let dispatch = Dispatch::new()
.level(LevelFilter::Debug) // Global max: allow Debug through.
// Console branch: colored, Info only.
.chain(
Dispatch::new()
.level(LevelFilter::Info) // Override: console gets Info+.
.level_map(colors) // Apply color mapping.
.format(|out, message, record| {
// Custom format for console.
// out.finish() writes the formatted string.
out.finish(format_args!(
"[{}] {}",
record.level(),
message
))
})
.chain(std::io::stdout())
)
// File branch: plain text, Debug level, with timestamps.
.chain(
Dispatch::new()
.level(LevelFilter::Debug) // File gets everything.
.format(|out, message, record| {
// Plain text format for files.
// Colors don't work in files; use timestamps instead.
out.finish(format_args!(
"{} [{}] {}",
chrono::Local::now().format("%Y-%m-%d %H:%M:%S"),
record.level(),
message
))
})
.chain(File::create("app.log").expect("Failed to create log file"))
);
dispatch.apply()
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
setup_logger()?;
info!("Server starting on port 8080");
debug!("Loading configuration from disk");
log::error!("Connection refused");
Ok(())
}
The console shows colored levels but no timestamps. The file shows timestamps but no colors. The console filters out Debug. The file captures everything. The format closure lets you customize the output string. It receives the message, the record (which contains level, target, module, etc.), and an output writer.
Convention aside: if you just need a file and don't care about custom formatting, use fern::log_file(). It creates a file dispatch with a standard format in one call. It saves boilerplate for simple cases.
// Shortcut for a basic file logger.
fern::log_file("app.log")?;
Filtering by module
Sometimes you want verbose logs for your code but quiet logs for dependencies. fern lets you filter by target. The target is usually the crate name or module path.
Dispatch::new()
.level(LevelFilter::Warn) // Default: only Warn and Error.
.target("my_app", LevelFilter::Debug) // My code: Debug allowed.
.target("hyper", LevelFilter::Error) // Hyper: only Errors.
.chain(std::io::stdout())
.apply()?;
This is useful when a dependency is too chatty. You can silence it without losing your own debug output. The target matching is prefix-based. "my_app" matches "my_app", "my_app::utils", and "my_app::core".
Pitfalls and compiler traps
Logging setup has a few gotchas. The compiler will catch some; others cause silent failures.
If you capture a local variable in your format closure, the compiler rejects it with E0597 (does not live long enough). The logger is global and lives for the entire program. The closure must be 'static, meaning it cannot hold references to local data. Use move to take ownership, or pass static values.
// BAD: captures a local reference.
let prefix = "LOG: ";
Dispatch::new()
.format(|out, message, record| {
out.finish(format_args!("{} {}", prefix, message)) // E0597
})
.apply()?;
// GOOD: moves the string into the closure.
let prefix = String::from("LOG: ");
Dispatch::new()
.format(move |out, message, record| {
out.finish(format_args!("{} {}", prefix, message))
})
.apply()?;
If you call apply() twice, the program panics. The log crate does not support multiple backends. Initialize the logger once, early in main. If you are writing a library, do not call apply(). Libraries should emit logs via log macros and let the binary set up the backend.
If you log before apply(), the message is lost. There is no buffer. The log crate checks for a backend; if none exists, it drops the message. Always set up the logger before the first log call.
Don't fight the compiler on lifetimes. Keep format closures simple and static. If you need dynamic data, pass it via move or use thread-local storage.
Choosing your logger
Rust has several logging crates. Pick the one that matches your needs.
Use fern when you need a simple, configuration-driven logger with multiple outputs and custom formatting. It works well for CLI tools, servers, and applications where you want to split logs to files and terminals with different rules.
Use env_logger when you want zero-configuration logging controlled by environment variables. It is perfect for scripts and tools where users set RUST_LOG=debug to enable verbose output. It requires minimal code.
Use tracing when you are building async applications, need structured data like JSON, or require advanced filtering and subscriber patterns. It integrates with async runtimes and provides richer context.
Use log alone when you are writing a library. Emit logs via log macros and let your users choose the backend. Never force a specific logger on library consumers.
Pick the tool that matches your complexity. Over-engineering logging is a classic trap. Start simple. Add features only when you need them.