StreamTrace BETA
Documentation menu

Installation & Deployment

Scaling & high availability

Runtime modes, horizontal scaling, health checks, and graceful shutdown.

For the limited beta, use one combined api,indexer instance with SQLite or PostgreSQL. The architecture below supports separate roles, but a multi-instance deployment has not been qualified for this beta. Authorization checks use the current state in the application database. Use one authoritative database; asynchronous read replicas are not qualified.

Runtime modes

ST_RUNTIME_MODE selects which roles a process runs:

ModeRuns
apiThe HTTP API and web UI only.
indexerThe 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:

EndpointUse
GET /api/health/liveLiveness - the process is up.
GET /api/health/readyReadiness - 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.