StreamTrace BETA
Documentation menu

Getting Started

Introduction

What Stream Trace is, how it connects to NATS JetStream, and what you can do with it.

What is Stream Trace?

Stream Trace is a self-hosted web UI for NATS JetStream. Point it at your existing NATS cluster and it gives you a fast, visual way to understand and debug your streams - no nats CLI and no log grepping required.

With Stream Trace you can:

  • Browse streams and consumers with live metrics, configuration, and health signals.
  • Search messages by subject, sequence, and time-plus optional full-text and JSON path scalar filtering with exists, equality, and comparison operators.
  • Inspect, replay, publish, and export messages, one at a time or in bulk.
  • Manage dead-letter cases built from terminal JetStream advisory events, with retry, resolution, and audited remediation outcomes.
  • Analyze throughput with per-consumer rates, p50–p99 message-size percentiles, and trend detection.
  • Trace messages across streams and consumers using correlation IDs.
  • Secure access with OIDC single sign-on, fine-grained RBAC, team-scoped stream ownership, and audit logging.

How it works

Stream Trace runs as a single container alongside your infrastructure:

  • It connects to your NATS cluster over the standard client protocol (ST_NATS_URL) and reads JetStream state through the JetStream API.
  • It keeps its own state - indexes, throughput samples, DLQ cases, users, and the audit log - in an embedded SQLite database or an external PostgreSQL database. NATS message data stays within the infrastructure and integrations you configure.
  • A background indexer continuously indexes new messages so search and filtering stay fast on large streams. The indexer can run in the same process as the API, or as a separate deployment for scale.

Self-hosted and air-gap capable. Stream Trace can run without public Internet access when you use local authentication or internally hosted identity and email services. Optional OIDC and SMTP integrations connect only to endpoints you configure.

NATS changes are explicit

The default indexer creates and manages its own durable consumer on every eligible, non-excluded stream and ACKs messages after indexing. Stream Trace also manages an advisory-observation consumer and can optionally create or update its dedicated advisory-capture stream. Authorized publish, replay, and retry actions create new messages. Stream Trace does not administer application-owned stream or consumer configuration through the product, purge streams, or directly delete messages. Reserve its two managed-consumer names; a name collision can cause Stream Trace’s create/update or cleanup path to modify that consumer.

Those managed consumers matter for retention. LimitsPolicy streams are the supported default. Historical message and trace search are unsupported for WorkQueuePolicy, which Stream Trace detects and excludes automatically. Review InterestPolicy streams before enabling indexing. Read the exact NATS permissions and retention effects.

Where to go next