Ephemeral log mirror for Kubernetes load testing. Part of SpectreHub.
Annotation-based opt-in. Accepts Loki push API, writes compressed JSONL to disk, shows a minimal TUI. Capture directories are portable — share them with tar, rsync, or scp and replay on any machine.
- Receiver (
recv) — accepts Loki push API payloads, writes rotated zstd-compressed JSONL with bounded disk usage - Live TUI — real-time stats, top talkers, scrollable log pane with vim-style navigation and regex search
- Sidecar injection (
tap/untap) — injects a log-forwarding sidecar into Kubernetes workloads, no logging agent config changes - Replay (
open) — replays capture directories at original speed or fast-forward with the same TUI - Analysis (
inspect,slice,export,triage) — summarize, filter, convert to parquet/CSV, or scan for anomalies - Cluster safety (
check,status) — validates readiness, detects orphaned sidecars, shows what's tapped
- Not a permanent log storage solution — ephemeral by design
- Not a replacement for Loki/Elasticsearch — captures are load-test scoped
- Not a monitoring agent — runs for the duration of a test
- Not a log shipper — receives, does not forward
brew tap ppiankov/tap
brew install logtapgit clone https://github.com/ppiankov/logtap.git
cd logtap
make buildlogtap check # verify cluster readiness
logtap recv --in-cluster --image ghcr.io/ppiankov/logtap-forwarder:latest --redact
logtap tap --deployment api-gateway # inject sidecar
# ... watch TUI, investigate ...
logtap untap --deployment api-gateway # remove sidecar
# Ctrl+C receiver
logtap inspect ./capture # see what you got
logtap triage ./capture --out ./triage # scan for anomalies# Receiver
logtap recv --dir ./capture --max-disk 50GB --redact
logtap recv --headless # no TUI, log to stderr
logtap recv --tls-cert cert.pem --tls-key key.pem
# Sidecar injection
logtap tap --deployment api-gateway --target host:3100
logtap tap --namespace payments --allow-prod --target host:3100
logtap untap --deployment api-gateway
# Replay with filters
logtap open ./capture --speed 10x
logtap open ./capture --from 10:32 --to 10:45 --label app=gateway
logtap open ./capture --grep "error" --dump # print to stdout, no TUI
logtap open ./capture --grep "error" --dump --color=always | less -R # colored matches
logtap open ./capture --grep "error" --dump -C 5 # 5 lines context
logtap open ./capture --grep "error" --dump --head 20 # first 20 matches
logtap open ./capture --grep "error" --dump --count # match count only
logtap open ./capture --dump --fields ts,container,msg # custom columns
logtap open ./capture --grep "error" --dump --json | jq . # pipe JSONL
# Export and search
logtap export ./capture --format parquet --out capture.parquet
logtap grep "error|timeout" ./capture --format text
logtap diff ./baseline ./current --baseline --json logtap tap ──► workload + logtap-forwarder (sidecar reads pod logs)
│ Loki push API
▼
logtap recv ──► HTTP server ──► writer ──► rotator ──► capture/
│ ├── metadata.json
├── redactor (PII) ├── index.jsonl
├── audit logger ├── *.jsonl.zst
└── TUI (stats + log pane) └── audit.jsonl
| Command | Description |
|---|---|
logtap recv |
Start receiver accepting Loki push API payloads |
logtap tap |
Inject log-forwarding sidecar into a workload |
logtap untap |
Remove sidecar from a workload |
logtap open |
Replay a capture directory in the TUI |
logtap inspect |
Summarize a capture directory |
logtap slice |
Filter capture by time range or label |
logtap export |
Convert capture to parquet or CSV |
logtap triage |
Scan capture for anomalies |
logtap check |
Validate cluster readiness |
logtap status |
Show what is currently tapped |
See CLI Reference for all commands, flags, and exit codes. See TUI keybindings for keyboard shortcuts.
logtap follows the ANCC convention — single binary, deterministic output, structured JSON, bounded jobs. No plugins or SDKs required.
Agents: read docs/SKILL.md for commands, flags, JSON output schemas, exit codes, and parsing examples.
Key patterns for agents:
logtap inspect <dir> --json— capture summary (files, entries, labels, timeline)logtap triage <dir> --json— anomaly scan results with severitylogtap grep <pattern> <dir> --format text— human-readable cross-service timelinelogtap check --json— cluster readiness and orphan detectionlogtap upload <dir> --to s3://... --share --json— upload and return presigned URLs
logtap feeds load test log capture summaries into SpectreHub for unified visibility across your infrastructure.
spectrehub collect --tool logtapPrincipiis obsta — resist the beginnings.
- Bounded by default — hard disk caps, drop policies, backpressure. Never block the sender.
- Disposable — captures are ephemeral artifacts for debugging, not long-term archives.
- Mirrors, not oracles — presents evidence and lets you decide. No ML, no probabilistic magic.
- Reversible — sidecar injection is clean removal away. No shared config patching.
- Explicit consent — production namespaces require
--allow-prod. PII redaction happens before bytes hit disk.
| Document | Contents |
|---|---|
| Architecture | System design, capture format, integration modes |
| CLI Reference | All commands, flags, and exit codes |
| TUI Keybindings | Keyboard shortcuts for live and replay modes |
| Security & Safety | PII redaction, production guardrails, audit trail |
| Known Limitations | Current constraints and edge cases |
| API Stability | What is stable across versions |
| Troubleshooting | Common failure modes and solutions |
| Examples | Copy-paste workflow scripts |
MIT — see LICENSE.
Built by Obsta Labs