Timberjack 🪓

Timberjack: Fell Your Logs Fast - A lightning-fast CLI log analysis tool built in Rust.

📋 Overview

Timberjack is a log-agnostic CLI tool that chops through noise to deliver patterns, trends, and stats from your logs. It's designed to be portable, requiring no servers or complex setup, and works with logs from any source—Java, Rust, Python, or any text-based logs.

✨ Key Features

• Fast JSON Processing: 70-90x faster than jq for large JSON logs
• Pattern Matching: On par with grep for small files, with richer analysis capabilities
• Parallel Processing: Up to 57% faster analysis of large files with automatic multi-threading
• Statistical Analysis: Get insights on log levels, error types, and message uniqueness
• Memory Efficiency: Low memory footprint even with large log files
• Automatic Format Detection: Intelligently handles both plaintext and JSON logs
• Stdin Support: Seamless piping and streaming log analysis

🚀 Installation

cargo install timberjack

🌐 Stdin and Piping Superpowers

Timberjack now supports stdin input, making log analysis incredibly flexible:

# Pipe logs from any source
cat system.log | timber --level ERROR
docker logs mycontainer | timber --chop "connection"
journalctl | timber --stats

# Quick counting
cat large_log.log | timber --count
cat access.log | grep "404" | timber --count

# Advanced analysis
kubectl logs pod/web-server | timber --json --trend

Pro Tips:

• Automatically detects log formats from stdin
• Supports compressed logs via zcat/gunzip
• Memory-mapped processing for large input streams
• Works with JSON, plaintext, and mixed log formats

🔨 Quick Examples

# Basic log analysis with automatic format detection
timber path/to/logfile.log

# Find errors and show statistics
timber --level ERROR --stats app.log

# Analyze JSON logs and filter by specific fields
timber --format json -f service=api -f status=500 logs.json

# Get just the count of errors (fastest mode)
timber --count --level ERROR app.log

# Use parallel processing for large files
timber --parallel large_logfile.log

📊 Benchmark Results

Our latest benchmarks show impressive performance across various operations:

JSON Processing (vs jq)

Pattern Matching

Parallel Processing (10M lines)

📚 Detailed Usage

Pattern Searching

# Find logs containing "Exception"
timber --chop "Exception" app.log

# Count occurrences (fastest)
timber --count --chop "Exception" app.log

# Combine with level filtering
timber --chop "timeout" --level ERROR app.log

JSON Log Analysis

# Process JSON logs (auto-detected)
timber app.json

# Filter by JSON fields
timber --format json -f service=api app.json

# Complex field filtering
timber --format json -f service=api -f level=ERROR -f "response_time>1000" app.json

Statistical Analysis

# Get comprehensive statistics
timber --stats app.log

# Show time-based trends
timber --trend app.log

# Show unique messages in stats
timber --stats --show-unique app.log

# Output top 10 error types
timber --stats --top-errors 10 app.log

Performance Options

# Force parallel processing for large files
timber --parallel large.log

# Memory-efficient mode
timber --count large.log

# Output JSON for programmatic use
timber --stats --json app.log > analysis.json

🔍 When to Use Timberjack

• Complex JSON Logs: Timberjack outperforms specialized tools like jq by 46-72x on large files
• All-in-One Analysis: Replaces grep, jq, and custom scripts with one unified tool
• Large Log Files: Automatic parallelization for multi-gigabyte logs
• Statistical Insights: When you need more than just matching lines
• CI/CD Pipelines: Fast and reliable log analysis in automated environments

🛠️ Command-Line Options

📝 Roadmap

• VS Code extension (coming May 2025)
• Multi-file analysis
• Interactive TUI mode
• Advanced pattern correlation

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

Timberjack is licensed under the MIT License - see the LICENSE file for details.