logler 1.3.2

Rust-powered log investigation for humans and AI agents

English | 日本語

Install

pip install logler

Python 3.9+. Rust backend included for investigation features.

Quick Start

Python API:

import logler.investigate as investigate

results = investigate.search(files=["app.log"], level="ERROR", limit=5)
for entry in results["results"]:
    print(f"[{entry['entry']['level']}] {entry['entry']['message']}")

CLI:

logler llm search app.log --level ERROR --tail 5

See It in Action

git clone https://github.com/gabu-quest/logler.git && cd logler
uv run python demo.py

Interactive Tours

Learn logler hands-on with marimo notebooks. Each tour is self-contained with sample data -- no external files needed.

Launch Interactive Tour (browser)

Run locally:

uv run marimo edit examples/tours/tour_01_fundamentals.py

Why Logler?

Log files are the black box of production. grep finds strings but not stories. Logler is a Rust-powered investigation engine that understands structure: threads, correlations, traces, hierarchies. Use it from Python, the CLI, or as an AI agent's investigation toolkit.

Performance

Real numbers from the benchmark suite (14 scenarios, Python 3.12, Rust backend):

Full report with 14 charts: benchmarks/results/REPORT.md

Honest limitations:

• BSD syslog without <priority> prefix has no parsed timestamps
• Time-based filtering unavailable for entries without timestamps

Features

Core

• Multi-format parser: JSON, syslog (RFC 3164/5424, BSD), logfmt, Apache CLF, plain text
• Thread tracking with correlation IDs and distributed traces
• Real-time file watching and tailing
• Rich terminal output with thread visualization

Investigation (Rust-powered)

• Hierarchy detection with tree, waterfall, flamegraph views
• Bottleneck analysis and error flow tracing
• Cross-service timeline reconstruction
• Pattern detection and smart sampling

LLM-Optimized

• 25 CLI commands with structured JSON output
• Token-efficient modes: summary, count, compact
• Investigation sessions with undo/redo and report generation
• Metrics extraction with z-score anomaly detection
• Format auto-detection with Drain template mining
• Custom formats and correlation rules via .logler.toml

When to Use Logler

Good fit:

• Debugging production incidents (threads, correlations, traces)
• AI agent log investigation (LLM-first JSON CLI)
• Cross-service distributed tracing
• Quick triage of large log files

Consider alternatives:

• Need log aggregation/storage: ELK, Loki, Datadog
• Need real-time alerting: Prometheus + Alertmanager
• Only need grep-like search: ripgrep

Showcase

Thread Hierarchy

Build a request hierarchy from span/parent_span fields, with automatic bottleneck detection:

import logler.investigate as investigate

hierarchy = investigate.follow_thread_hierarchy(
    files=["app.log"],
    root_identifier="req-123",
    min_confidence=0.8,
)
if hierarchy.get("bottleneck"):
    bn = hierarchy["bottleneck"]
    print(f"Bottleneck: {bn['node_id']} ({bn['duration_ms']}ms)")

api-gateway (req-001, 520ms)
├─ auth-service (45ms)
│  ├─ jwt-validate (5ms)
│  └─ user-lookup (25ms)
├─ product-service (450ms) SLOW
│  ├─ inventory-check (340ms)
│  │  └─ db-query (300ms)
│  └─ cache-update (45ms) ERROR
└─ response-assembly (10ms)

Full tour | API reference

Cross-Service Timeline

Reconstruct a request's journey across microservices:

timeline = investigate.cross_service_timeline(
    files={"api": ["api.log"], "db": ["db.log"], "cache": ["cache.log"]},
    correlation_id="req-12345",
)
for event in timeline["timeline"]:
    print(f"[{event['service']}] {event['entry']['message']}")

Full tour | API reference

Error Flow Analysis

Trace error propagation through the request hierarchy:

error_flow = investigate.analyze_error_flow(
    files=["app.log"],
    root_identifier="req-123",
)

Error Flow Analysis

Root Cause:
  cache-update failed at 10:00:00.450Z
  Error: Redis connection refused
  Path: api-gateway -> product-service -> cache-update

Impact: 3 nodes affected, request degraded
Recommendation: Check Redis connectivity

Full tour | API reference

Visualization Modes

Tree View -- parent-child relationships:

api-gateway (req-001, 520ms)
├─ auth-service (45ms)
│  ├─ jwt-validate (5ms)
│  └─ user-lookup (25ms)
├─ product-service (450ms) SLOW
│  ├─ inventory-check (340ms)
│  │  └─ db-query (300ms)
│  └─ cache-update (45ms) ERROR
└─ response-assembly (10ms)

Waterfall View -- temporal overlap:

Timeline: req-001 (520ms)
api-gateway          ████████████████████████████████████████  520ms
  ├─ auth-service    ████                                      45ms
  ├─ product-service      ████████████████████████████████    450ms
  │  ├─ inventory              ██████████████████████         340ms
  │  └─ cache-update                              ████ ERR     45ms
  └─ response                                          ██      10ms

Flamegraph View -- time distribution:

┌────────────────────────────────────────────────────────────────────┐
│ api-gateway (520ms)                                                │
├───────────┬────────────────────────────────────────────────────────┤
│ auth (45) │ product-service (450ms)                                │
│           ├─────────────────────────────┬──────────────────────────┤
│           │ inventory-check (340ms)     │ cache-update (45ms) ERR  │
└───────────┴─────────────────────────────┴──────────────────────────┘

Error Flow -- propagation tracing:

Root Cause:
  cache-update failed at 10:00:00.450Z
  Error: Redis connection refused
  Path: api-gateway -> product-service -> cache-update

Impact: 3 nodes affected, request degraded

Documentation

Testing

uv run pytest              # 1000+ Python tests
cargo test --workspace     # Rust tests

Contributing

uv run ruff format . && uv run ruff check .

Contributions welcome. Please submit a Pull Request.

License

MIT License -- see LICENSE for details.