mig

README

mig — message inspector general

A live TUI for inspecting NATS message flow. Point it at a subject (Core or JetStream), see rates, volumes, last-message timing, top subjects, JSON health, and an inferred schema sketch with numeric histograms. The layout adapts: paginated in small terminals, a tiled grid in large ones.

   ╭─ Total ─╮ ╭─ Rate ──────────╮ ╭─ Last seen ─────────────╮
   │  1,234  │ │ ↑ 12.5 msg/s    │ │ 0.3s ago  evt.foo  18B  │
   │ 56.7KB  │ │ 60s avg 8.4     │ │ {"id":1,"v":42}         │
   ╰─────────╯ ╰─────────────────╯ ╰─────────────────────────╯
   ╭─ Msgs/s ─────────────────────────────────────────────────╮
   │ ▁▂▂▃▄▄▆▇█▇▇▇▆▅▅▆▇▇█▇▆▆▅▄▄▃▃▂▁▁▁▁▁▂▃▄▄▅▆▆▇█▇▆▅            │
   │ peak 47/s · window 120s                                  │
   ╰──────────────────────────────────────────────────────────╯

Install

Pre-built, signed binaries (Linux/macOS/Windows × x86_64/arm64) are on the releases page. Each release ships SBOMs and a cosign-signed checksums.txt.bundle; verification recipe is in CONTRIBUTING.md.

If you have module access (this repository is private), go install also works:

GOPRIVATE=github.com/panevain/* go install github.com/panevain/mig/cmd/mig@latest

Or build from source:

git clone https://github.com/panevain/mig
cd mig
make build
./mig --help

Usage

Point at a subject; mig auto-detects whether the server has JetStream and which stream covers your filter:

# Local NATS, all subjects
mig

# Specific subject filter
mig -S 'evt.>'

# Multiple filters, explicit server
mig -s nats://nats.example:4222 -S 'orders.*' -S 'payments.*'

# Force Core NATS (no JetStream)
mig --core -S '>'

# Pin to a specific stream and replay everything
mig --stream EVENTS -S 'evt.>' --all

# Replay last 5 minutes
mig --stream EVENTS --since 5m

# Pipe-friendly mode: no TUI, one JSON message per line on stdout
mig --no-tui -S 'evt.>' | jq .

Benching locally

End-to-end bench against real NATS in two commands:

docker compose --profile bench up -d --build   # NATS + BENCH stream + publisher
./mig                                          # consume, watch the tiles light up

The bench profile starts three services: nats (JetStream-enabled server), nats-init (one-shot stream creator), and nats-pub (the cmd/migbench publisher, built in-tree via cmd/migbench/Dockerfile). It emits realistic JSON with rotating event types, randomized user/region/currency/tags, and incrementing ids — so JSON Health tile shows ~100% parseable, the schema sketch fills out, and Top subjects spreads across bench.x.0..bench.x.9. Tune with env vars before bringing the stack up:

BENCH_RATE=10000 BENCH_SUBJECTS=50 docker compose --profile bench up -d --build

For a faster dev loop without rebuilding the container on every code change, run the publisher natively against a NATS-only stack:

docker compose up -d                  # NATS only (no init, no pub)
make bench-pub                        # ./cmd/migbench against localhost:4222

Tear down with docker compose --profile bench down -v (the -v wipes JS state). Monitoring is on localhost:8222 (e.g., curl localhost:8222/varz).

On Linux hosts where Docker's bridge networking is flaky (Fedora / nftables / firewalld in particular), copy compose.override.yaml.example to compose.override.yaml to switch every bench service to host networking. Linux-only — leave it as .example on macOS/Windows.

Auth

# JWT + nkey
mig --creds ~/.nats/user.creds

# nkey only
mig --nkey ~/.nats/user.nk

# Username + password (also picks up NATS_PASSWORD env)
mig --user observer --password $TOKEN

# TLS
mig --tlscert client.crt --tlskey client.key --tlsca ca.crt

# Existing nats CLI context (opt-in)
mig --context production

Tiles

Tile	What you see
Header	Connection status dot, server URL, source kind (core/jetstream + stream), uptime, drop count, recent error count
Total	Lifetime message count + total bytes
Rate	Current msg/s (5s EMA) + 60s EMA + jitter stddev. Up/down/flat trend arrow
Msgs/s sparkline	120-second history of msg/s with peak marker
Bytes	Bytes/s (5s EMA) + 60s avg + small inline byte sparkline
Last seen	Age of last message (red when older than --stale), subject, JSON-pretty preview
Top subjects	Up to 10 busiest subjects with counts and last-seen ages
JSON health	% parseable, ok/bad counts, count of valid-but-non-object payloads
Schema sketch	Inferred JSON paths with types, numeric range/μ/p50 + histogram, string distinct count + example
Drops	Red banner only visible when slow-consumer drops have occurred

Layout

mig adapts to terminal size automatically:

Width × Height	Layout
< 40 × 10	"resize me" message
< 60 wide or < 16 tall	One tile per page; tab / arrows cycle
60–119 × 16–29	2-column grid, 2 pages
120–179 × ≥ 30	3-column grid, all tiles visible
≥ 180	4-column grid, big sparkline, expanded subjects/schema

Keys

Key	Action
q, Ctrl-C	Quit
tab, →, l	Next page (paginated layouts)
shift-tab, ←, h	Previous page
r	Reset all stats and schema (uptime preserved)
p	Pause UI rendering (data still recorded)

Reliability

• Cold-start with NATS down: mig exits immediately with cannot reach NATS at <url> instead of hanging or surfacing an opaque buffer error. Mid-session drops reconnect forever; header turns red until the connection is back.
• JetStream auto-detect: if the stream is missing, mig surfaces the available stream list and suggests --core or an explicit --stream. JS-disabled servers fall back to Core silently.
• Slow-consumer drops increment a counter and pop the Drops tile/banner.
• Malformed JSON is counted (bad=N) but never crashes anything; the LastSeen tile still renders the raw bytes.
• Subject and schema-path tracking are bounded (--max-subjects, --max-paths) with eviction so high-cardinality streams don't OOM mig.

Flag reference

mig --help

All flags: see mig --help. Highlights:

• --refresh DURATION (default 200ms, min 50ms) — UI tick interval
• --stale DURATION (default 5s) — red threshold on last-seen
• --max-subjects N (default 256) — bounded top-N subject map
• --max-paths N (default 512) — bounded schema path tracker
• --schema-sample F (default 1.0) — fraction of valid JSON fed into the schema engine
• --no-tui — flat one-line-per-message stdout for piping/grepping
• --json-pretty — pretty-print JSON in --no-tui mode

Contributing

Contributions welcome — see CONTRIBUTING.md. For security issues, please use private reporting per SECURITY.md.

License

MIT