Scaling & high availability · Docs

Stream Trace is stateless apart from its database, so you can scale it horizontally by running multiple instances against a shared PostgreSQL database.

Runtime modes

ST_RUNTIME_MODE selects which roles a process runs:

Mode	Runs
`api`	The HTTP API and web UI only.
`indexer`	The background message indexer only.
`api,indexer` (default)	Both in one process.

SQLite must run the combined api,indexer mode in a single process.
PostgreSQL lets you split the roles: run several api replicas behind a load balancer for the UI, and one or more indexer deployments to keep up with high-volume streams.

Background workers (indexer, throughput sampler, DLQ capture) coordinate through short database leases, so running more than one is safe - they share the work rather than duplicating it.

A scaled-out topology

            ┌──────────────┐
  users ──► │  api (×N)    │ ──► PostgreSQL ◄── indexer (×M) ──► NATS
            └──────────────┘          ▲                            │
                   │                  └────────────────────────────┘
                   └──────────────► NATS (read, publish, replay)

Health checks

Two endpoints support orchestration probes:

Endpoint	Use
`GET /api/health/live`	Liveness - the process is up.
`GET /api/health/ready`	Readiness - registered database, NATS, and DLQ readiness checks pass.

Point your Kubernetes livenessProbe at /api/health/live and readinessProbe at /api/health/ready. Readiness does not currently prove that the message indexer, throughput sampler, or trace observer has completed useful work; confirm those from their UI state and logs.

Graceful shutdown

On SIGTERM, Stream Trace stops accepting new requests, drains in-flight work, and closes its NATS and database connections. ST_SHUTDOWN_TIMEOUT_SEC (default 20) bounds how long it waits before forcing exit.