LogGraph

LogGraph is a local, DuckDB-first log analysis tool for humans and coding agents. It ingests raw logs into .log-index/, then exposes compact, cited evidence through the lograg CLI so Claude, Codex, Cline, and humans do not need to paste large raw logs into chat.

raw logs -> DuckDB evidence index -> compact lograg output -> focused analysis

What It Is For

• Token-efficient triage of large or noisy logs.
• Safe agent workflows that avoid direct raw-log and DuckDB reads.
• Grouping repeated failures by templates and fingerprints.
• Drilling into exact events, windows, traces, sources, tags, and timelines.
• Default-on redaction for secrets and personal data.
• Reuse-aware ingestion for repeated analysis of the same inputs.

Install

python3 -m venv .venv
.venv/bin/pip install -e .

For development:

.venv/bin/pip install -e ".[dev]"

Quick Start

lograg ingest logs/raw/app.log --out .log-index/app-local
lograg manifest --index .log-index/app-local
lograg errors --index .log-index/app-local
lograg search --query "token refresh failed" --index .log-index/app-local
lograg show --event @e52 --index .log-index/app-local
lograg window --event @e52 --index .log-index/app-local

When --out is omitted, ingestion checks .log-index/registry.json and reuses a compatible existing index for identical discovered inputs, file hashes, config digest, and index format. Use --force only for intentional rebuilds.

Common Commands

lograg sources
lograg tags
lograg templates
lograg find --level ERROR --tag auth
lograg group-errors
lograg trace --request-id req-123
lograg timeline --bucket 1m --level ERROR
lograg benchmark --all --scale smoke
lograg eval-create incident.log --issue "Requests fail after refresh" \
  --suspect-class AuthService --repo . --out /tmp/loggraph-evals/auth-refresh

Useful aliases include f for find, w for window, sh for show, se for search, tr for trace, ge for group-errors, tl for timeline, and tpl for templates.

Configuration

Configuration is optional. If lograg.config.json exists, LogGraph merges it with validated defaults. Copy lograg.config.example.json (which mirrors the defaults) to lograg.config.json and edit it for parser profiles, redaction patterns, ranking caps, output compression, and FTS settings.

Agent Use

Agents should use lograg commands instead of reading raw .log files or .duckdb databases directly. The skill resources under .agents/skills/loggraph-log-analysis/ provide progressive context for Claude and Codex, while .cline/skills/loggraph-log-analysis/SKILL.md supports Cline.

Recommended flow:

manifest -> stats/sources/tags/templates -> errors/find/search -> show/window/trace -> cited answer

Project Layout

• loggraph/ingest: source discovery, parsing, redaction, templates, fingerprints.
• loggraph/storage: DuckDB schema, FTS, manifests, index paths, reuse registry.
• loggraph/query: SQL filters, handle resolution, ranking, diversity selection.
• loggraph/output: compact text, JSON output, token budgets.
• loggraph/benchmark: fixtures, benchmark runner, recall/token metrics.
• loggraph/evaluation: generated debugging cases, agent execution, audit, and scoring.
• tests: CLI, ingestion, query, storage, benchmark, and agent integration tests.

More Detail

Read docs/GUIDE.md for the expanded guide and docs/ARCHITECTURE.md for architecture, flow, and sequence diagrams.

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, tests, and the project guardrails.

License

MIT