LogWatcher

A powerful CLI tool for real-time log file monitoring with pattern highlighting and desktop notifications.

Features

• Real-time file tailing - Monitor log files as they're written
• Pattern highlighting - Color-code different log levels and patterns
• Desktop notifications - Get alerted for critical patterns even when terminal isn't visible
• Multiple file support - Monitor multiple log files simultaneously
• File rotation handling - Automatically detect and handle log rotation
• Regex support - Use regular expressions for advanced pattern matching
• Dry-run mode - Test patterns without continuous monitoring
• Throttled notifications - Prevent notification spam

Installation

From Source

git clone https://github.com/matcharr/logwatcher.git
cd logwatcher
cargo build --release
sudo cp target/release/logwatcher /usr/local/bin/

Using Cargo

cargo install log-watcher

Quick Start

Basic Usage

Monitor a single log file for ERROR and WARN patterns:

logwatcher -f /var/log/app.log

Multiple Files

Monitor multiple log files simultaneously:

logwatcher -f app.log -f error.log -f access.log

Custom Patterns

Specify custom patterns to match:

logwatcher -f app.log -p "ERROR,CRITICAL,timeout"

Regex Patterns

Use regular expressions for advanced matching:

logwatcher -f app.log -r -p "user_id=\d+|session_\w+"

Dry-Run Mode

Test patterns on existing file content:

logwatcher -f app.log --dry-run -p "ERROR,WARN"

Quiet Mode

Only show lines that match patterns:

logwatcher -f app.log -q -p "ERROR"

Command Line Options

Required Arguments

Pattern Configuration

Notification Control

Output Control

Performance Tuning

Default Color Mappings

• ERROR → Red
• WARN/WARNING → Yellow
• INFO → Green
• DEBUG → Cyan
• TRACE → Magenta
• FATAL/CRITICAL → Red + Bold

Examples

Basic Error Monitoring

# Monitor application logs for errors
logwatcher -f /var/log/app.log

# Output:
# [2025-01-07 15:00:01] Starting application server...
# [2025-01-07 15:00:02] Database connection established
# [2025-01-07 15:00:03] ERROR Failed to bind to port 8080  # (shown in red)
# [Desktop notification appears: "ERROR detected in app.log"]

Multiple Files with Custom Patterns

logwatcher -f app.log -f nginx.log -p "ERROR,404,timeout" --color-map "404:yellow,timeout:magenta"

# Output:
# [app.log] [2025-01-07 15:00:01] Request processed successfully
# [nginx.log] [2025-01-07 15:00:02] 404 Not Found: /api/users  # (shown in yellow)
# [app.log] [2025-01-07 15:00:03] ERROR Database timeout  # (shown in red, "timeout" in magenta)

Dry-Run Testing

logwatcher -f app.log --dry-run -p "ERROR,WARN"

# Output:
# Reading existing content from app.log...
# [DRY-RUN] Line 42: ERROR Connection refused  # (shown in red)
# [DRY-RUN] Line 89: WARN Memory usage at 85%  # (shown in yellow)
# Found 2 matching lines (1 ERROR, 1 WARN)
# Dry-run complete. No notifications sent.

Regex Pattern Matching

logwatcher -f app.log -q -r -p "user_id=\d+|session_\w+"

# Output:
# [2025-01-07 15:00:01] Login successful for user_id=12345
# [2025-01-07 15:00:15] Order placed by user_id=67890
# [2025-01-07 15:00:30] Session created: session_abc123

File Rotation Handling

LogWatcher automatically detects and handles log file rotation:

• Truncation detection - Detects when file size decreases
• Automatic reopening - Reopens files after rotation
• Rotation notifications - Logs when rotation is detected

# LogWatcher automatically handles rotation
logwatcher -f /var/log/app.log

# When rotation occurs:
# Warning: File rotation detected for /var/log/app.log
# Info: Reopened file: /var/log/app.log

Desktop Notifications

LogWatcher supports desktop notifications on Linux, macOS, and Windows:

• Pattern-based alerts - Notifications for specific patterns
• Throttling - Prevents notification spam
• Truncated content - Long lines are truncated in notifications
• Respects system settings - Honors Do Not Disturb settings

Notification Examples

# Enable notifications for all patterns
logwatcher -f app.log --notify

# Only notify for critical patterns
logwatcher -f app.log --notify-patterns "ERROR,FATAL,CRITICAL"

# Throttle notifications to 2 per second
logwatcher -f app.log --notify-throttle 2

Performance Considerations

• Memory efficient - Uses streaming I/O for large files
• Configurable polling - Adjust polling interval for your needs
• Buffer sizing - Tune buffer size for optimal performance
• Fast pattern matching - ~0.7-11µs per line (benchmarked)
• Small binary - Only 2.0MB in release mode
• Async I/O - Non-blocking file operations

# Optimize for high-frequency logs
logwatcher -f app.log --poll-interval 50 --buffer-size 16384

# Optimize for large files
logwatcher -f large.log --poll-interval 500 --buffer-size 32768

Troubleshooting

Common Issues

File not found:

# Check file permissions and path
ls -la /var/log/app.log
logwatcher -f /var/log/app.log

No notifications:

# Test notification system
logwatcher -f app.log --dry-run --notify -p "TEST"

High CPU usage:

# Increase polling interval
logwatcher -f app.log --poll-interval 500

Memory usage:

# Reduce buffer size
logwatcher -f app.log --buffer-size 4096

Debug Mode

Enable debug logging:

RUST_LOG=debug logwatcher -f app.log

Exit Codes

• 0 - Success
• 1 - File access error
• 2 - Invalid pattern/regex
• 3 - Notification system error
• 130 - Interrupted (Ctrl+C)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Testing & Coverage

LogWatcher has comprehensive test coverage:

• 50 Tests Total: 13 integration tests + 36 unit tests + 1 main test
• Integration Tests: End-to-end CLI functionality testing
• Unit Tests: Core component testing (matcher, highlighter, notifier, watcher, etc.)
• Performance Benchmarks: Real performance measurements
• Cross-platform Testing: Linux, macOS, Windows
• Coverage: 80.84% (above 80% professional standard)

Running Tests

# Run all tests
cargo test

# Run only integration tests
cargo test --test integration

# Run benchmarks
cargo bench

# Check test coverage (requires cargo-tarpaulin)
cargo install cargo-tarpaulin
cargo tarpaulin --out Html

Coverage reports are automatically generated and uploaded to Codecov on every commit.

Changelog

v0.1.0

• Initial release
• Real-time file tailing
• Pattern highlighting
• Desktop notifications
• File rotation handling
• Regex support
• Dry-run mode