trace-test-harness

A local-only dev tool that sits next to depsera and simulates services pushing OTLP telemetry. Used to exercise depsera features end-to-end on a developer laptop.

Each simulated service is both an in-process OTLP emitter and a real HTTP listener exposing a configurable /health endpoint that depsera can poll. The harness UI (React) lets you build topologies, paste per-team dps_* API keys, toggle per-service behaviors, and run multi-service scenarios.

Stack

• Server: Node + Express + TypeScript, better-sqlite3
• Client: React 18 + Vite + TypeScript
• Single repo, npm workspaces

Run

npm install
npm run dev

• Server: http://localhost:5180
• Client: http://localhost:5181 (proxies /api to the server)

Depsera is expected on http://localhost:3001.

Test

npm test

How to use

1. Start depsera at http://localhost:3001 in a separate terminal (see the depsera repo). The harness has no auth of its own — it just needs depsera reachable.
2. Start the harness: npm install && npm run dev. Open http://localhost:5181.
3. Create a team on the Teams page and paste a depsera dps_* API key. Keys are stored locally in data/harness.sqlite and are never displayed after save (you'll only see dps_••••<last4>).
4. Build a topology on the Topology page. Either:
   • Load a canned preset (single-service, three-team-ecommerce, cross-team-fanout) from the Load Preset menu, or
   • Add services manually (assign to a team, pick a health format) and drag edges between them to declare dependencies. Cycles are rejected.
5. Tune a service on the Service Detail page (click a node in Topology, or navigate to /services/:id). Toggles are grouped per the plan:
   • Health & state (drives both /health responses and dependency.health.* metrics)
   • Latency (profile + unit + histograms)
   • Errors (rate %, 4xx/5xx mix)
   • Span shape (kind mix, attribute groups, structured attrs)
   • Discovery (unknown service names, new external deps, name-spoofing)
   • Schema / mapping (custom metric names, partial push)
   • Volume / rate (emit interval, spans per emit, force rate limit)
6. Start the service with the Start button. The emitter loop pushes OTLP traces (and metrics if configured) to depsera at the configured cadence. The mock /health listener also comes up on a port in the 4100–4199 range so depsera can poll it.
7. Fire one-off bursts from the Service Detail page (e.g. "send 50 spans now") on top of the running loop.
8. Run orchestrated scenarios on the Scenarios page (cascade-failure, auto-discover-burst, rate-limit-storm, flap-storm, cross-team-fanout, partial-push-drift, schema-mismatch). Each accepts params, polls run status, and can be aborted.
9. Watch traffic on the Activity page — tails push_log (depsera responses, status codes, span/metric counts) with filters by service, endpoint, and status family. Auto-refreshes every 2s.

Reset

Delete data/harness.sqlite to wipe topology, keys, and history. Migrations recreate the schema on next start.

Environment

• PORT — server port (default 5180).
• DEPSERA_BASE_URL — initial depsera base URL (default http://localhost:3001). Used only to seed the value on first run; after that the Settings page is authoritative and changes take effect on the next push.

Layout

See docs/PLAN.md for the full architecture and docs/DEPSERA-CONTRACT.md for the OTLP wire-format contract the harness conforms to.