🌿 logscan v1.2.0 · MIT

The problem

Log files grow quietly and nobody reads them until something is already on fire. grep finds strings but gives no triage, no grouping, no exit codes. This tool watches any text log against a rule set, groups matches by rule with severity (CRIT / WARN / INFO), and turns the result into 0 / 1 / 2 exit codes a cron or CI job can react to.

What it does

• Built-in generic rules — segfaults, fatal errors, OOM, disk full, auth failures, connection refused/reset, timeouts, panics.
• Custom rules via a JSON file: --rules rules.json (id, severity, regex, description).
• Time window — --since-hours 24 keeps only fresh timestamped lines; unparseable lines fail open (never silently skipped).
• JSON-lines aware — recognises JSON-lines entries (extracts the timestamp + message), so rules match the message field and the time window works on structured logs (app logs, OpenClaw daily logs) that a plain timestamp regex would miss.
• Output — plain text, --json, or --md for daily reports; sample lines included.
• Zero dependencies, Python ≥ 3.9, single module.

Install (pip)

pip install logscan @ git+https://mandrilly.com/git/logscan.git

Usage

logscan /var/log/app.log                     # text report
logscan --since-hours 24 --md app.log        # markdown report, 24h window
logscan --rules myrules.json --json a.log b.log
logscan --tail 500 /var/log/app.log          # only last 500 lines per file
logscan --list-rules                         # show the active rule set

Sample output:

== logscan report ==
files: /tmp/demo.log
total matches: 2 (CRIT=1, WARN=1, INFO=0)
[WARN] conn-refused: 1 match(es)
    | 2026-09-18 11:00:00 connection refused to api
[CRIT] fatal: 1 match(es)
    | 2026-09-18 11:05:00 fatal: disk corrupt

Exit codes

Cron pattern

logscan --quiet --since-hours 24 /var/log/app.log \
  || echo "logscan exit $?" | mail -s "logscan anomalies" ops@example.com

Tests

python -m unittest test_logscan -v   # 16 tests → OK

Source

git clone https://mandrilly.com/git/logscan.git