grep is too slow. Elasticsearch is too heavy. qlog is just right.

# Index your logs once
qlog index './logs/**/*.log'

# Search millions of lines in milliseconds
qlog search "status=500" --context 3

# Find errors across all services
qlog search "exception" -n 50

# Get stats
qlog stats

✅ Use qlog when:

• Developing locally and need to search app logs quickly
• Debugging CI/CD pipelines with large log artifacts
• Running small projects/side projects where Elasticsearch is overkill
• You want grep-speed search but for repeated queries
• Monitoring local log files with live filtering

❌ Don't use qlog for:

• Production observability at scale (use Datadog, Splunk, ELK, etc.)
• Team collaboration on live production logs (use centralized logging)
• Real-time alerting across distributed systems (use an observability platform)

Think of qlog like ripgrep for logs - it complements (not replaces) your production logging stack.

• ⚡ Blazingly Fast - Inverted index searches millions of lines/second
• 🎯 Smart Indexing - Only re-indexes changed files
• 👁️ Watch Mode - Monitor files and auto-reindex with live filtering
• 🎨 Beautiful Output - Color-coded, context-aware results
• 📊 Format Detection - Auto-detects JSON, syslog, nginx, apache, and more
• 🔍 Context Aware - See lines before/after matches
• 💾 Efficient - Index stored locally, works offline
• 🐍 Pure Python - Easy to install, extend, and understand

pip install qlog-cli

Or install from source:

git clone https://github.com/Cosm00/qlog
cd qlog
pip install -e .

# Index all logs in current directory
qlog index './**/*.log'

# Index specific patterns
qlog index './app.log' './errors.log' '/var/log/nginx/*.log'

# Force re-indexing
qlog index './**/*.log' --force

Indexing is fast: 1M+ lines/second on modern hardware.

# Simple search
qlog search "error"

# Search with context (3 lines before/after)
qlog search "connection refused" --context 3

# Limit results
qlog search "timeout" -n 50

# JSON output (for piping)
qlog search "critical" --json | jq '.[] | .file'

# Monitor logs with auto-reindexing
qlog watch './logs/**/*.log' --filter "error"

Perfect for monitoring local services during development.

qlog stats

Shows indexed files, unique terms, index size, and performance metrics.

# Index all service logs
qlog index './logs/**/*.log'

# Find all 500 errors with context
qlog search "500" --context 5

# Search for specific request ID
qlog search "request-id-12345" -c 10

# Find all exceptions
qlog search "exception" -n 100

# Index nginx logs
qlog index '/var/log/nginx/*.log'

# Find slow requests
qlog search "upstream_response_time" --context 2

# Watch logs and auto-reindex on changes
qlog watch './logs/**/*.log'

# Watch with live filtering (only show errors)
qlog watch './logs/**/*.log' --filter "error"

# Watch with custom interval (default: 5s)
qlog watch './app.log' --filter "exception" --interval 2

Tested on a MacBook Pro (M1) with 10GB of mixed log files:

qlog is ~3750x faster than grep for indexed searches.

qlog uses an inverted index (like search engines):

1. Indexing Phase:

   • Scans log files using memory-mapped I/O (fast!)
   • Tokenizes each line (words, IPs, UUIDs, status codes)
   • Builds an inverted index: term → [(file, line, offset), ...]
   • Stores index locally in .qlog/ (efficient, fast to load)

2. Search Phase:

   • Looks up terms in the index (O(1) hash lookup)
   • Finds intersection of matching lines (set operations)
   • Retrieves actual lines from files
   • Formats and displays with context

qlog automatically detects and parses common log formats:

• JSON - Structured JSON logs
• Syslog - Traditional Unix syslog
• Apache/Nginx - Combined web server logs
• ISO Timestamps - Generic YYYY-MM-DD HH:MM:SS logs
• Plain Text - Falls back to full-text indexing

from qlog import LogIndexer, LogSearcher

# Create indexer
indexer = LogIndexer(index_dir=".qlog")

# Index files
stats = indexer.index_files(["./logs/**/*.log"])
print(f"Indexed {stats['lines']:,} lines in {stats['elapsed']:.2f}s")

# Search
searcher = LogSearcher(indexer)
results = searcher.search("error", context=3, max_results=100)

for result in results:
    print(f"{result['file']}:{result['line_num']}")
    print(f"  {result['line']}")

Extend the indexer to recognize domain-specific patterns:

from qlog import LogIndexer

class CustomIndexer(LogIndexer):
    def _tokenize(self, line):
        tokens = super()._tokenize(line)
        # Add custom patterns
        # e.g., extract trace IDs, custom codes, etc.
        return tokens

• Pros: qlog is 10-100x faster on repeated searches
• Cons: Requires one-time indexing step

• Pros: Much simpler, no server, works offline, lower resource usage
• Cons: Single-machine only, no clustering

• Pros: Free, open-source, no licensing, simpler
• Cons: Fewer features, no distributed search

• Faster result retrieval (mmap offset reads; no full-file readlines per match)
• Index hygiene: stable file IDs + purge old postings on reindex
• New command: qlog watch <patterns> [--filter QUERY]
• GitHub issue templates

• Time-based queries (qlog search "error" --since "1h ago")
• Cross-service correlation (trace IDs)
• Export to CSV/JSON with aggregations
• TUI (interactive terminal UI)
• Regular expression queries
• Fuzzy search
• Web UI for non-CLI users

Contributions welcome! This is a community project.

# Clone repo
git clone https://github.com/Cosm00/qlog
cd qlog

# Install dev dependencies
pip install -e '.[dev]'

# Run tests
pytest

# Run benchmarks
python benchmarks/bench.py

If qlog saves you time, consider supporting development:

• Ko-fi: https://ko-fi.com/cosm00

(Once GitHub Sponsors is approved, I’ll add it here too.)

MIT License - see LICENSE for details.

Built with:

• rich - Beautiful terminal output
• click - CLI framework

Inspired by:

• grep, ag, ripgrep - Fast text search
• Elasticsearch - Inverted index architecture
• lnav - Log file navigation

Made with ❤️ for developers who hate waiting for grep

⭐ Star this repo if qlog saved you time!