clearvoiance

Documentation

Record real production traffic and replay it safely at N× speed.

Catch breaking points before they hit production — without triggering real APIs, payments, or side effects.

Why?

Staging environments lie.

Mocks drift. Synthetic tests miss real edge cases.

clearvoiance records actual traffic and replays it in a hermetic environment so you can test against reality — not guesses.

Start here

  • Quickstart — install the SDK, point it at a local engine, capture an HTTP session, replay it in 60 seconds.
  • Core concepts — capture vs. replay vs. hermetic vs. observer, and how the four fit together.
  • Monitors — start / stop captures on running services remotely from the dashboard, the way you'd actually use this in production.
  • Database correlation — how slow queries get pinned back to the exact request that caused them, across Postgres, Knex, Prisma, and Mongoose.

What's in the box

clearvoiance has four components, all in one repo:

  1. The SDK (@clearvoiance/node) runs inside your app. It captures HTTP, WebSockets, cron, queues, outbound HTTP/fetch, and DB queries, streaming events to the engine over gRPC. Framework adapters are peer-dep-free — install only what you use. Two modes: auto-session (start on boot, good for dev) and remote-controlled "monitors" (idle until the dashboard clicks Start, the production default).
  2. The engine is a Go binary that persists events to ClickHouse + MinIO, schedules replays at configurable speedup, runs the control plane that pushes Start / Stop commands to SDKs, and exposes a REST/WebSocket API. Self-host via docker-compose.
  3. The DB observer is a sidecar (or embedded) binary that polls pg_stat_activity, parses the SDK's application_name = 'clv:<event_id>', and correlates every slow query back to the replay event that caused it. For MongoDB (no equivalent introspection view), the SDK emits observations directly from the Mongoose adapter — see Database correlation.
  4. The dashboard is a Next.js UI that drives the engine — monitors, sessions, replays with live 250ms progress + per-endpoint slow- route analysis + capture-vs-replay regression diffs, DB observations, API key + user management.

How it's different

Every tool in the space makes you pick one of:

  • Synthetic load (k6, Artillery, Locust, Gatling) — you hand-write traffic. Real production is always weirder than your scripts.
  • Wall-clock replay (GoReplay, mirrord) — replays at 1×. Useful for smoke tests, useless for finding scale ceilings.
  • Chaos injection (Toxiproxy, Chaos Mesh) — injects failures, doesn't model realistic traffic shapes.

clearvoiance does all three in one flow: capture a real traffic window, replay at 12–100×, watch the DB side of the replay in the same UI. Output looks like: "Under 12× prod load, POST /api/leads triggers lock contention on leads_email_key after ~400ms. Here's the query plan. Here's the captured event. Here's the reproducer."

Install

npm install @clearvoiance/node

Node 18+ required. Then head to the quickstart.