logtap

README

logtap

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.

What logtap is

• 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

What logtap is NOT

• 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

Quick start

Homebrew

brew tap ppiankov/tap
brew install logtap

From source

git clone https://github.com/ppiankov/logtap.git
cd logtap
make build

Kubernetes workflow

logtap 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

Key flags

# 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 --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

Architecture

  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

CLI commands

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.

Agent integration

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 severity
• logtap grep <pattern> <dir> --format text — human-readable cross-service timeline
• logtap check --json — cluster readiness and orphan detection
• logtap upload <dir> --to s3://... --share --json — upload and return presigned URLs

SpectreHub integration

logtap feeds load test log capture summaries into SpectreHub for unified visibility across your infrastructure.

spectrehub collect --tool logtap

Philosophy

Principiis 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.

Documentation

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

License

MIT — see LICENSE.

---

Built by Obsta Labs