log-triage

Turn raw logs into a root-cause report. The agent never just greps — it parses, correlates, and ranks.

Workflow

1. Collect — identify the log source: a file, directory, command output (kubectl logs, docker logs, journalctl), or pasted text. If the user gives a directory, scan for *.log, *.jsonl, and files without extension modified recently.
2. Parse — run scripts/parse_logs.py <path> to auto-detect the format and emit structured events. Supports JSON lines, LEVEL timestamp message plain logs, syslog, nginx access/error, Python tracebacks, and Java stacktraces. Unknown lines are kept as raw events, never dropped.
3. Triage — run scripts/triage.py <parsed-json> to classify errors, rebuild the timeline, correlate error chains (same request-id / thread / 5-second window), detect repeating patterns, and rank root-cause hypotheses by confidence.
4. Report — present: most-likely root cause, impact (how many events / users / requests affected), a compact timeline of key events, and concrete next steps (fix, add monitoring, roll back).

Quick commands

# Parse a log file or directory (auto-detects format)
python scripts/parse_logs.py /var/log/app > events.json

# Triage parsed events and print a root-cause report
python scripts/triage.py events.json

# One-liner: parse and triage in one shot
python scripts/parse_logs.py app.log | python scripts/triage.py -

What the report contains

• Root cause hypothesis — ranked by confidence (high/medium/low), with the evidence lines
• Severity — critical / error / warning / info, derived from event levels and impact
• Timeline — the 5–15 most significant events in chronological order
• Error chains — correlated events sharing a request-id, thread, or close timestamps
• Repeat offenders — errors that recur across the log window
• Next steps — concrete actions: fix the bug, roll back, scale up, add a circuit breaker, etc.

Parsing rules

• JSON lines: each line is one event; map level/severity, timestamp/time, msg/message, and any request_id/trace_id/thread fields.
• Plain text: detect LEVEL (DEBUG/INFO/WARN/ERROR/FATAL/CRITICAL) at line start; extract ISO-8601 or common timestamps; multi-line stacktraces are attached to the preceding event.
• Nginx: parse $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent; status ≥500 = error, 4xx = warning.
• Syslog: parse <priority>timestamp host process[pid]: message.
• Unknown: keep as raw with level=info; the triage step still catches anomalies via pattern matching.

When to read references

• Multi-line stacktraces or custom log formats: read references/parsing-recipes.md for regex patterns and format-specific guidance.
• Correlating across services (distributed tracing): read references/correlation-patterns.md for request-id propagation, trace-id stitching, and cross-service timeline merge.
• Writing the final report for different audiences: read references/report-templates.md for incident-postmortem vs. developer-debug vs. executive-summary formats.

Exit codes

• parse_logs.py: 0 = parsed at least one event, 1 = no events found, 2 = file not found
• triage.py: 0 = report generated, 1 = no errors found (clean run), 2 = input invalid