how it works

  log file / stdin
        |
        v
  [ clean up ]     strip colour codes, syslog <PRI>, docker/kubectl prefixes
        |
        v
  [ parse ]        auto-detect format (or several, for mixed streams),
        |          or --format to force it
        v
  [ analyze ]      bursts and spikes, plus single-line failures:
        |          crashes, failed jobs, denials, limits, certificates
        v
  [ classify ]     names the incident category, groups related events
        |
        v
  [ summarize ]    one incident: a title, findings with what they
        |          are about and the lines that prove them, remediation
        v
  terminal output / --json

parse

Format is auto-detected from the path and samples taken across the whole file, not just its first lines. A stream that interleaves formats, like docker logs of a web server mixing access and error lines, is parsed line by line by the parsers that recognize each part. Lines no parser understands are still analyzed as generic text, never dropped. See formats.

analyze

Two kinds of detectors run. Statistical ones look for concentrated anomalies, not noisy volume: a burst of benign INFO lines isn't an incident, a dense cluster of warnings-or-worse is, and in a long log a burst has to stand out from that log's own normal error rate. They cover error-rate spikes against a historical baseline, event bursts, auth-failure clusters, mail-reject bursts and proxy/firewall anomalies.

The others catch failures that are one line, because many real ones are: a backup job that did not complete, a backend killed by a signal, an app that died on an unhandled exception or panic, an OOM kill, a full disk, a degraded RAID array or a filesystem gone read-only, an SELinux or AppArmor denial, a config file a service refused, a proxy with no live backend, a process out of file descriptors or processes, a rejected TLS certificate, a clock that jumped, a failing Kubernetes health probe. Overlapping signals for the same incident are folded into one finding.

classify

Deterministic, high-precision signals (a literal OOM kill, a disk-full message, an auth-failure cluster) are trusted directly as the root cause. For more generic signals, a small local classification model names the likely incident category and groups related events together so you see one incident instead of a hundred near-duplicate lines. This step runs entirely on-device (no network call, no external API) and is optional: if it's unavailable for any reason, logcrux still reports everything the statistical analysis found and says so plainly, rather than pretending nothing happened.

summarize

Signals and classification are combined into one incident: a title, and findings that say what they are about (the source addresses and users of an attack, the process the OOM killer chose, the unit or pod that crashed, the HTTP status and path of a 5xx flood), when it started and ended, and the log lines, by number, that prove it. Then a confidence score and a remediation suggestion. A clean result says what was checked. Output is either a terminal report or --json for scripts, CI gates and agents.

state (optional)

A local SQLite database tracks historical event rates so later runs can compare against a baseline instead of guessing at "normal." It's purely local, gracefully skipped if unavailable, and disabled per-run with --no-baseline. See config for the path and tuning knobs.