StreamTrace BETA
Documentation menu

Getting Started

Quickstart

Run Stream Trace locally against a NATS cluster in a couple of minutes.

This quickstart gets Stream Trace running locally so you can click around against a real JetStream-enabled NATS server.

Private beta. Stream Trace is currently in private beta. The examples below use git.prod.antomic.net/antomic/stream-trace:BETA_TAG. Beta participants receive registry access and an immutable tag - request access if you haven’t yet. Do not substitute latest.

Prerequisites

  • NATS 2.x+ with JetStream enabled (the example below starts one for you).
  • Docker and Docker Compose.

1. Create a docker-compose.yaml

name: stream-trace-quickstart

services:
  nats:
    image: nats:2.12.1
    command: ["-js", "-m", "8222"]
    ports:
      - "4222:4222"

  stream-trace:
    image: git.prod.antomic.net/antomic/stream-trace:BETA_TAG
    depends_on:
      - nats
    ports:
      - "4000:4000"
    environment:
      ST_NATS_URL: "nats://nats:4222"
      # Local evaluation only - see the note below.
      ST_AUTH_ENABLED: "false"
      # Review retention policies before historical indexing.
      ST_INDEXER_ENABLED: "false"

2. Start it

docker compose up

Then open http://localhost:4000.

Stream Trace will discover your streams without creating an indexing consumer. If you don’t have any streams yet, create one with the nats CLI or your application and refresh.

About ST_AUTH_ENABLED: "false". Disabling auth attaches a synthetic local development admin and shows a warning banner in the UI. It’s perfect for a quick local look, but do not use disabled auth in a shared or production environment. See Authentication to turn on login, SSO, and access control.

3. Persisting data (optional)

By default Stream Trace stores its state in an embedded SQLite file inside the container, which is lost when the container is removed. To keep it between runs, mount a volume and point the database at it:

    environment:
      ST_NATS_URL: "nats://nats:4222"
      ST_AUTH_ENABLED: "false"
      ST_DB_URL: "file:/data/stream-trace.db?_foreign_keys=on&_journal_mode=WAL&_busy_timeout=5000"
    volumes:
      - stream-trace-data:/data

For multi-instance or production deployments, use PostgreSQL - see Databases.

Next steps

Use one real stream to complete a first investigation: confirm the stream appears, open its consumer state, inspect pending or redelivered messages, and follow one signal to the relevant message, DLQ case, or trace. Then review every accessible stream’s retention policy before enabling the historical indexer.