# FStdout Logger
A simple and flexible dual-destination logger for Rust applications that implements the `log` crate's API.
[](https://crates.io/crates/fstdout-logger)
[](https://docs.rs/fstdout-logger)
## Features
- Log messages to both stdout and a file simultaneously
- Configurable log levels (Trace, Debug, Info, Warn, Error)
- **Module-level log filtering with RUST_LOG support**
- Colored output for stdout (with different colors for each log level)
- Plain text output for log files (no color codes)
- Compact timestamps in stdout (only time, HH:MM:SS)
- Complete timestamps in log files (includes date)
- Optional file and line number information
- Highly configurable via simple builder API
- Compatible with the standard `log` crate macros
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
fstdout-logger = "0.1.0"
log = "0.4"
```
The crate uses the following dependencies internally:
- `colored` for terminal coloring
- `chrono` for timestamp formatting
- `thiserror` for error handling
## Usage
### Simple Usage
```rust
use fstdout_logger::init_logger;
use log::{debug, error, info, warn};
fn main() {
// Initialize logger with defaults (colored output, Info level)
if let Err(e) = init_logger(Some("application.log")) {
eprintln!("Failed to initialize logger: {}", e);
return;
}
// Now use the standard log macros
info!("Application started"); // Blue
debug!("This won't show by default"); // Suppressed (below Info level)
warn!("Warning: resource usage high"); // Yellow
error!("Failed to process item: {}", "invalid format"); // Red
}
```
### Using Presets
For common use cases, presets are available:
```rust
use fstdout_logger::{init_development_logger, init_production_logger};
use log::{debug, error, info};
fn main() {
// For development: Debug level with file info and colors
init_development_logger(Some("dev.log")).expect("Failed to initialize logger");
// Or for production: Info level without file info, concise timestamps
// init_production_logger(Some("app.log")).expect("Failed to initialize logger");
debug!("Debug info shows in development mode"); // Shows in development, hidden in production
info!("Application running");
error!("Something went wrong!");
}
```
### Custom Configuration
For full control, use the configuration builder:
```rust
use fstdout_logger::{init_logger_with_config, LoggerConfig, LoggerConfigBuilder};
use log::{info, LevelFilter};
fn main() {
// Create a custom configuration
let config = LoggerConfig::builder()
.level(LevelFilter::Info)
.show_file_info(false) // Hide file and line info for cleaner output
.show_date_in_stdout(false) // Show only time in stdout (HH:MM:SS)
.use_colors(true) // Enable colored output
.build();
// Initialize with the custom config
init_logger_with_config(Some("application.log"), config)
.expect("Failed to initialize logger");
info!("Customized logging experience!");
}
```
### Using RUST_LOG Environment Variable
The logger supports the standard `RUST_LOG` environment variable for fine-grained control over log levels per module:
```rust
use fstdout_logger::init_logger_from_env;
use log::{debug, info, trace};
fn main() {
// Initialize logger from RUST_LOG environment variable
init_logger_from_env(Some("app.log"))
.expect("Failed to initialize logger");
// Logs will be filtered according to RUST_LOG
trace!("This is a trace message");
debug!("This is a debug message");
info!("This is an info message");
}
```
Set `RUST_LOG` when running your application:
```bash
# Set global log level to debug
RUST_LOG=debug cargo run
# Set specific module to trace, others to warn
RUST_LOG=my_crate::network=trace,warn cargo run
# Multiple module filters
RUST_LOG=my_crate::module_a=debug,my_crate::module_b=trace,info cargo run
# On Windows (PowerShell)
$env:RUST_LOG="debug" ; cargo run
$env:RUST_LOG="my_crate::network=trace,warn" ; cargo run
```
Supported `RUST_LOG` formats:
- `debug` - Set default level to debug
- `my_crate=debug` - Set specific crate to debug
- `my_crate::module=trace` - Set specific module to trace
- `my_crate=debug,other_crate::module=trace` - Multiple module filters
- `my_crate::module=trace,warn` - Module-specific level with global default
**Note:** `init_logger()` automatically reads `RUST_LOG` and `LOG_LEVEL` if they are set!
### Using LOG_LEVEL Numeric Format
For simpler configuration, you can use `LOG_LEVEL` with numeric values:
```rust
use fstdout_logger::{init_logger_with_config, LoggerConfig};
use log::LevelFilter;
use std::env;
fn main() {
// Parse LOG_LEVEL environment variable
let log_level = match env::var("LOG_LEVEL") {
Ok(level) => match level.parse::<u8>() {
Ok(level) => match level {
0 => LevelFilter::Off,
1 => LevelFilter::Error,
2 => LevelFilter::Warn,
3 => LevelFilter::Info,
4 => LevelFilter::Debug,
_ => LevelFilter::Trace,
},
Err(_) => LevelFilter::Warn,
},
Err(_) => LevelFilter::Warn,
};
// Configure logger with module filters
if let Err(e) = init_logger_with_config(
Some("app.log"),
LoggerConfig::builder()
.show_file_info(cfg!(debug_assertions))
.level(log_level)
.filter_module("rustls", LevelFilter::Error)
.filter_module("tokio_rustls", LevelFilter::Error)
.build(),
) {
eprintln!("Failed to initialize logger: {}", e);
std::process::exit(1);
}
}
```
`LOG_LEVEL` values:
- `0` = Off
- `1` = Error
- `2` = Warn
- `3` = Info (default)
- `4` = Debug
- `5+` = Trace
Set `LOG_LEVEL` when running:
```bash
LOG_LEVEL=4 cargo run # Debug level
# On Windows (PowerShell)
$env:LOG_LEVEL="4" ; cargo run
```
## Output Format
### Terminal Output (Default)
By default, terminal output shows a concise format with colors:
```
[HH:MM:SS LEVEL file:line] Message
```
For example:
```
[14:23:45 INFO main.rs:25] Application started
```
Log messages are colored according to log level:
- `ERROR`: Bold Red
- `WARN`: Bold Yellow
- `INFO`: Bold Blue
- `DEBUG`: Green
- `TRACE`: Default terminal color
The timestamp and file information are displayed in a dimmed color to make the log level and message stand out.
### File Output (Always Plain Text)
Log messages in files always include the date and file information:
```
[YYYY-MM-DD HH:MM:SS LEVEL file:line] Message
```
For example:
```
[2023-05-15 14:23:45 INFO main.rs:25] Application started
```
### Configuration Options
You can configure the output format through the `LoggerConfig`:
- `show_file_info` - Toggle display of file and line information
- `show_date_in_stdout` - Toggle inclusion of date in terminal output
- `use_colors` - Enable or disable colored output in terminal
- `level` - Set the minimum log level to display
## Run Examples
The crate includes examples that demonstrate its usage:
```bash
# Simple logging with custom configuration
cargo run --example basic_usage
# Stdout-only logging with minimal format
cargo run --example stdout_only
# Comparing different color and format options
cargo run --example color_options
# Demonstrating production vs development presets
cargo run --example production
# Module-level filtering with RUST_LOG
RUST_LOG=debug cargo run --example module_filters
RUST_LOG=module_filters::network=trace,warn cargo run --example module_filters
# Numeric log levels with LOG_LEVEL
LOG_LEVEL=4 cargo run --example log_level_numeric
```
## Full API
The logger provides several initialization functions for different use cases:
- `init_logger(path)` - Simple initialization with defaults
- `init_logger_with_level(path, level)` - Set a specific log level
- `init_logger_with_config(path, config)` - Use a custom configuration
- `init_logger_from_env(path)` - Initialize from RUST_LOG environment variable
- `init_production_logger(path)` - Use production-optimized settings
- `init_development_logger(path)` - Use development-optimized settings
- `init_stdout_logger(config)` - Initialize a stdout-only logger
- `init_simple_stdout_logger(level)` - Initialize a minimal stdout-only logger
## License
This project is licensed under the MIT License - see the LICENSE file for details.