Configurable cross-source log capture, search, and analysis CLI.
Paperbark captures logs from many sources (Fly.io, Cloudflare, Kubernetes, CloudWatch, plain files, stdin), runs a configurable set of probes over them, and writes a stable run-directory layout that downstream tooling can search across.
Status: latest release on PyPI. The probe, format, source (flyctl, file, stdin, wrangler), iteration, aggregate, cursor-filter, search, dispatcher, and analyse layers are all wired up;
paperbark monitorruns end to end on a configurable cadence with arich.liveticker. See docs/ROADMAP.md for current status.
# pipx (recommended for CLI use)
pipx install paperbark
# or uv
uv tool install paperbarkFor local development, see CONTRIBUTING.md.
# write a starter config in the current directory. Run inside a
# directory containing `fly.toml` or `wrangler.{toml,jsonc,json}` and
# the [[sources]] block is pre-filled with the app/worker name —
# `paperbark monitor` is then ready to go without further edits.
# Pass `--no-detect` to opt out and emit the bare template.
paperbark init
# add at least one source — uncomment the [[sources]] block in
# paperbark.toml and point `app` at your Fly app. monitor exits with
# "no sources configured" until you do. (Skip this step if `init`
# auto-detected a manifest above.)
# capture and analyse using config defaults (3s cadence, ~72 minutes)
paperbark monitor
# custom cadence, fixed run id, snapshots every 30s
paperbark monitor --interval 1s --run-id incident-pr349 --analyse-every 30s
# capture forever; press Ctrl+C to write the final report and exit
paperbark monitor --iterations 0
# search across captured runs
paperbark search --keyword "panic"
# re-run analysis over an existing run
paperbark analyse --run latestOr skip Fly entirely and pipe pre-captured logs through stdin:
# one-shot run over a piped log; same probes, same run-dir layout
printf '[[sources]]\nname = "pipe"\ntype = "stdin"\n' > paperbark.toml
cat app.log | paperbark monitor --iterations 1The file source is the on-disk equivalent — set type = "file" and
point path at the log file instead of piping.
Paperbark reads ./paperbark.toml first, then
~/.config/paperbark/config.toml. Every CLI flag is also expressible as a
TOML key; flags override TOML at runtime. See docs/CONFIG.md
for the full schema reference.
| Source | Status |
|---|---|
Fly.io (flyctl logs) |
implemented |
Cloudflare Workers (wrangler tail) |
implemented |
Kubernetes (kubectl logs) |
stub (interface only, post-v1) |
| AWS CloudWatch | stub (interface only, post-v1) |
| Plain files | implemented |
| stdin | implemented |
See docs/SOURCES.md for the Source interface and
how to add a new one.
Today: JSON-keyed payloads only. Per-source format_keys lets you
remap the canonical field names (timestamp / level / message / component)
to whatever JSON keys your app emits — see
docs/CONFIG.md.
Coming in v0.2: regex named-group formats for non-JSON shapes
(pipe-delimited, syslog, Apache combined, nginx default, or any custom
pattern). The format layer already ships three presets
(apache-combined, nginx-default, syslog-rfc5424); they're not yet
wired into iteration. Until then, non-JSON sources will trip the
format-mismatch warning and probes will produce no findings.
Severity rollup, panics and fatals, HTTP status, latency (p50/p95/p99),
heartbeat gap detection, process health, autoscaler events,
database/external errors, Sentry events, plus ad-hoc keyword and regex
matches. Each probe is config-toggleable; regex sets are
config-overridable. See docs/PROBES.md for the full
list, finding shapes, and how to add one.
MIT — see LICENSE.