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.