Skip to content

logging.md

Latest commit

 

History

History
304 lines (222 loc) · 7.59 KB

logging.md

File metadata and controls

304 lines (222 loc) · 7.59 KB

FloatWM Structured Logging System

Overview

FloatWM includes a comprehensive structured logging system built on top of the log and fern crates. The system provides flexible configuration options, multiple output formats, and environment variable-based configuration.

Features

  • Multiple Log Levels: trace, debug, info, warn, error, off
  • Multiple Output Formats: Terminal (colored), JSON (structured), Compact
  • Flexible Output Targets: stdout, stderr, file, or both
  • Environment Variable Configuration: Easy configuration without code changes
  • Module-Level Filtering: Control logging verbosity per module
  • Timestamps and Metadata: Optional timestamps, module paths, and file/line information

Configuration

Environment Variables

The logging system can be configured using the following environment variables:

Variable Description Values Default
FLOATWM_LOG_LEVEL Minimum log level to display trace, debug, info, warn, error, off info
FLOATWM_LOG_FORMAT Output format for logs terminal, json, compact terminal
FLOATWM_LOG_TARGET Where to send log output stdout, stderr, file, both stderr
FLOATWM_LOG_FILE Path to log file (required for file and both targets) Any valid file path None
FLOATWM_LOG_TIMESTAMP Include timestamps in logs true, false, 1, 0 true
FLOATWM_LOG_MODULE Include module paths in logs true, false, 1, 0 true
RUST_LOG Alternative log level setting (also supports module-specific levels) See RUST_LOG documentation info

Examples

Basic Usage (Default Configuration)

# Uses all defaults: info level, terminal format, stderr output
floatwm

Debug Mode

# Enable debug level logging
FLOATWM_LOG_LEVEL=debug floatwm

JSON Logging to File

# Output JSON logs to a file
FLOATWM_LOG_FORMAT=json \
FLOATWM_LOG_TARGET=file \
FLOATWM_LOG_FILE=/var/log/floatwm.log \
floatwm

Dual Output (Console + File)

# Output to both console and file
FLOATWM_LOG_TARGET=both \
FLOATWM_LOG_FILE=/var/log/floatwm.log \
floatwm

Module-Specific Logging

# Enable debug for specific modules only
RUST_LOG=floatwm::x11=debug,floatwm::sensor=trace,floatwm=info floatwm

Trace Mode for Development

# Enable all trace logs
FLOATWM_LOG_LEVEL=trace floatwm

Output Formats

Terminal Format (Default)

Colored, human-readable output suitable for console viewing:

2024-01-13 10:30:45.123 [INFO ] floatwm::main FloatWM starting with sensor support enabled
2024-01-13 10:30:45.124 [DEBUG] floatwm::main Logging system initialized successfully
2024-01-13 10:30:45.125 [INFO ] floatwm::lib Connected to X11 display: :0

JSON Format

Structured JSON output for machine parsing and log aggregation:

{"timestamp":"2024-01-13T10:30:45.123+00:00","level":"INFO","message":"FloatWM starting","module":"floatwm::main"}
{"timestamp":"2024-01-13T10:30:45.124+00:00","level":"DEBUG","message":"Logging initialized","module":"floatwm::main"}

Compact Format

Simplified format with minimal metadata:

2024-01-13 10:30:45.123 [INFO] FloatWM starting
2024-01-13 10:30:45.124 [DEBUG] Logging initialized

Programmatic Usage

Basic Initialization

use floatwm::logging;

fn main() {
    // Initialize with environment variables
    logging::init_logging().expect("Failed to initialize logging");

    log::info!("Application started");
}

Custom Configuration

use floatwm::logging::{LoggingConfig, LogFormat, LogTarget};
use log::LevelFilter;

fn main() {
    let config = LoggingConfig::new()
        .with_level(LevelFilter::Debug)
        .with_format(LogFormat::Json)
        .with_target(LogTarget::Both)
        .with_log_file("/var/log/floatwm.log")
        .with_timestamps(true)
        .with_module_path(true);

    logging::init_logging_with_config(config)
        .expect("Failed to initialize logging");

    log::info!("Application started");
}

Using the Log Macros

use log::{trace, debug, info, warn, error};

fn example_function() {
    trace!("Detailed trace information");
    debug!("Debugging information");
    info!("General information");
    warn!("Warning condition");
    error!("Error occurred");
}

Log Levels

Level Description Use Case
trace Extremely detailed debugging Tracing function execution, variable states
debug Detailed information for debugging Development and troubleshooting
info General informational messages Normal operation, significant events
warn Warning conditions Unexpected but recoverable situations
error Error conditions Failures that don't stop execution
off Disable logging Performance-critical sections

Best Practices

For Development

# Enable detailed logging
FLOATWM_LOG_LEVEL=debug floatwm

For Production

# Log warnings and errors to file
FLOATWM_LOG_LEVEL=warn \
FLOATWM_LOG_TARGET=file \
FLOATWM_LOG_FILE=/var/log/floatwm.log \
floatwm

For Debugging Issues

# Enable trace logging for specific module
RUST_LOG=floatwm::x11=trace,floatwm=info floatwm

For Monitoring/Log Aggregation

# JSON format for easy parsing
FLOATWM_LOG_FORMAT=json \
FLOATWM_LOG_TARGET=file \
FLOATWM_LOG_FILE=/var/log/floatwm.log \
floatwm

File Rotation

The logging system writes to files in append mode but does not implement automatic log rotation. For production use, consider using external tools like logrotate:

Example logrotate configuration

/var/log/floatwm.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 floatwm adm
}

Performance Considerations

  • Logging at trace and debug levels has minimal overhead when disabled
  • File I/O is buffered for better performance
  • JSON formatting has slightly more overhead than terminal format
  • For high-frequency logging, consider using warn or higher levels in production

Troubleshooting

Logs Not Appearing

Check that the log level is set appropriately:

# Check current RUST_LOG setting
echo $RUST_LOG

# Try explicitly setting the level
RUST_LOG=debug floatwm

File Permission Errors

Ensure FloatWM has write permissions for the log file location:

# Create log directory with proper permissions
sudo mkdir -p /var/log/floatwm
sudo chown $USER:$USER /var/log/floatwm
chmod 755 /var/log/floatwm

Module-Specific Logs Not Working

Verify the module path matches the actual Rust module structure:

// In floatwm/src/x11.rs
log::debug!("This message is from module: floatwm::x11");

Then use:

RUST_LOG=floatwm::x11=debug floatwm

Integration with External Tools

Systemd Integration

[Service]
ExecStart=/usr/bin/floatwm
Environment="FLOATWM_LOG_LEVEL=info"
Environment="FLOATWM_LOG_TARGET=file"
Environment="FLOATWM_LOG_FILE=/var/log/floatwm.log"
StandardOutput=null
StandardError=journal

Docker Integration

ENV FLOATWM_LOG_LEVEL=info
ENV FLOATWM_LOG_FORMAT=json
ENV FLOATWM_LOG_TARGET=stdout

API Reference

See the floatwm::logging module documentation for complete API details:

  • LoggingConfig: Main configuration struct
  • LogFormat: Output format enum
  • LogTarget: Output target enum
  • init_logging(): Initialize with environment variables
  • init_logging_with_config(): Initialize with custom config