brk_logger

Colored console logging with optional file output for Bitcoin Research Kit applications.

Overview

This crate provides a thin wrapper around env_logger with enhanced formatting, colored output, and optional file logging. Designed specifically for BRK applications, it offers structured logging with timestamps, level-based coloring, and automatic filtering of noisy dependencies.

Key Features:

• Level-based color coding for console output (error=red, warn=yellow, info=green, etc.)
• Dual output: colored console logs and optional plain-text file logging
• System timezone-aware timestamps with customizable formatting
• Automatic filtering of verbose dependencies (bitcoin, fjall, tracing, etc.)
• Environment variable configuration support via RUST_LOG

Target Use Cases:

• Bitcoin blockchain analysis applications requiring structured logging
• Development and debugging of BRK components
• Production deployments with file-based log archival
• Applications needing both human-readable and machine-parseable logs

Installation

cargo add brk_logger

Quick Start

use brk_logger;

// Initialize with console output only
brk_logger::init(None)?;

// Initialize with file logging
let log_path = std::path::Path::new("application.log");
brk_logger::init(Some(log_path))?;

// Use standard log macros
log::info!("Application started");
log::warn!("Configuration issue detected");
log::error!("Failed to process block");

API Overview

Core Functions

init(path: Option<&Path>) -> io::Result<()> Initializes the logging system with optional file output. Console logging is always enabled with color formatting.

Re-exported Types:

• OwoColorize: Color formatting trait for custom colored output

Log Formatting

Console Output Format:

2024-09-16 14:23:45 - INFO  Application started successfully
2024-09-16 14:23:46 - WARN  Bitcoin RPC connection slow
2024-09-16 14:23:47 - ERROR Failed to parse block data

File Output Format (Plain Text):

2024-09-16 14:23:45 - info  Application started successfully
2024-09-16 14:23:46 - warn  Bitcoin RPC connection slow
2024-09-16 14:23:47 - error Failed to parse block data

Default Filtering

The logger automatically filters out verbose logs from common dependencies:

• bitcoin=off - Bitcoin library internals
• bitcoincore-rpc=off - RPC client details
• fjall=off - Database engine logs
• lsm_tree=off - LSM tree operations
• tracing=off - Tracing framework internals

Examples

Basic Logging Setup

use brk_logger;
use log::{info, warn, error};

fn main() -> std::io::Result<()> {
    // Initialize logging to console only
    brk_logger::init(None)?;

    info!("Starting Bitcoin analysis");
    warn!("Price feed temporarily unavailable");
    error!("Block parsing failed at height 750000");

    Ok(())
}

File Logging with Custom Path

use brk_logger;
use std::path::Path;

fn main() -> std::io::Result<()> {
    let log_file = Path::new("/var/log/brk/application.log");

    // Initialize with dual output: console + file
    brk_logger::init(Some(log_file))?;

    log::info!("Application configured with file logging");

    // Both console (colored) and file (plain) will receive this log
    log::error!("Critical system error occurred");

    Ok(())
}

Environment Variable Configuration

# Set custom log level and targets
export RUST_LOG="debug,brk_indexer=trace,bitcoin=warn"

# Run application - logger respects RUST_LOG
./my_brk_app

use brk_logger;

fn main() -> std::io::Result<()> {
    // Respects RUST_LOG environment variable
    brk_logger::init(None)?;

    log::debug!("Debug information (only shown if RUST_LOG=debug)");
    log::trace!("Trace information (only for specific modules)");

    Ok(())
}

Colored Output Usage

use brk_logger::OwoColorize;

fn print_status() {
    println!("Status: {}", "Connected".green());
    println!("Height: {}", "800000".bright_blue());
    println!("Error:  {}", "Connection failed".red());
}

Architecture

Logging Pipeline

1. Initialization: init() configures env_logger with custom formatter
2. Environment: Reads RUST_LOG or uses default filter configuration
3. Formatting: Applies timestamp, level formatting, and color coding
4. Dual Output: Writes colored logs to console, plain logs to file (if configured)

Color Scheme

• ERROR: Red text for critical failures
• WARN: Yellow text for warnings and issues
• INFO: Green text for normal operations
• DEBUG: Blue text for debugging information
• TRACE: Cyan text for detailed tracing
• Timestamps: Bright black (gray) for visual hierarchy

File Handling

• File Creation: Creates log file if it doesn't exist
• Append Mode: Appends to existing files without truncation
• Error Resilience: Console logging continues even if file write fails
• File Rotation: Manual - application responsible for log rotation

Filtering Strategy

Default filter prioritizes BRK application logs while suppressing:

• Verbose dependency logging that clutters output
• Internal library debug information not relevant to users
• Framework-level tracing that doesn't aid in debugging BRK logic

Code Analysis Summary

Main Function: init() function that configures env_logger with custom formatting and dual output
Dependencies: Built on env_logger for filtering, jiff for timestamps, owo-colors for terminal colors
Output Streams: Simultaneous console (colored) and file (plain text) logging with different formatting
Timestamp Format: System timezone-aware formatting using %Y-%m-%d %H:%M:%S pattern
Color Implementation: Level-based color mapping with owo-colors for terminal output
Filter Configuration: Predefined filter string that suppresses verbose dependencies while enabling BRK logs
Architecture: Thin wrapper pattern that enhances env_logger with BRK-specific formatting and behavior

This README was generated by Claude Code