Connecting to NATS

Stream Trace connects to your NATS cluster using the URL in ST_NATS_URL. It uses the standard NATS client protocol and the JetStream API - it does not require the monitoring (HTTP) port.

Connection URL

ST_NATS_URL="nats://nats.internal:4222"

Authentication

Credentials are provided through the URL:

• Username / password: nats://user:password@host:4222
• Token: nats://token@host:4222

Supported boundary. Authentication and TLS are configured through one validated connection URL. URL username/password and token authentication are supported. There are no first-class settings for NATS credentials files (.creds), JWT/NKey seeds, multiple cluster seed URLs, client certificates, or a custom CA file. Select compatible beta environments; application OIDC settings do not authenticate this separate NATS connection.

TLS

Use the tls:// scheme to connect over TLS:

ST_NATS_URL="tls://nats.internal:4222"

The server’s certificate must be trusted by the container’s system certificate store. The beta image does not yet expose a supported custom-CA mount or mTLS client-certificate setting.

Reconnection

Stream Trace retries the initial connection and reconnects automatically if the connection drops:

Variable	Default	Description
ST_NATS_MAX_RECONNECTS	-1	Max reconnect attempts; -1 = unlimited.
ST_NATS_RECONNECT_WAIT_SEC	2	Seconds between attempts (1–300).

Permissions Stream Trace needs

Stream Trace reads application stream and consumer configuration, but it also manages its own JetStream resources and can publish new messages. Grant the connected NATS user only the capabilities you enable:

Capability	NATS operation	When it happens
Inventory and browsing	List stream/consumer state and retrieve messages.	Always.
Message indexer	Create or update the durable pull consumer stream_trace_message_search_index on each eligible, non-excluded stream, fetch messages, explicitly ACK them, and delete/reset that managed consumer during cleanup. WorkQueue streams are ineligible.	Default: ST_INDEXER_ENABLED=true in the indexer role.
Advisory observer	Create or update stream_trace_dlq_observations on the advisory stream, fetch events, and ACK them.	When the indexer role and advisory stream are available.
Advisory stream management	Create or update the configured advisory-capture stream.	Only with ST_DLQ_ADVISORY_STREAM_AUTO_CREATE=true.
Publish, replay, and DLQ retry	Publish new messages to application or configured replay subjects and receive publish acknowledgements.	Only when an authorized user runs the action.

In NATS permission terms, this means JetStream stream/consumer INFO and LIST requests, message GET or DIRECT GET, managed-consumer CREATE/UPDATE/DELETE and MSG.NEXT requests, publish access to ACK subjects for consumed messages, and subscription access to request/reply inboxes. Add stream CREATE/UPDATE only for advisory auto-creation. Add application-subject publish permissions only for the subjects users may target through publish, replay, or retry.

For trace and consumer observations, also grant subscribe access to the live event subjects used by the watcher:

$JS.EVENT.METRIC.CONSUMER.ACK.>
$JS.EVENT.ADVISORY.CONSUMER.MSG_NAKED.>
$JS.EVENT.ADVISORY.CONSUMER.MSG_TERMINATED.>
$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.>

Stream Trace has no application stream or consumer administration workflow, and it does not purge streams or directly delete application messages. However, reserve the managed-consumer names stream_trace_message_search_index and stream_trace_dlq_observations exclusively for Stream Trace. A pre-existing application consumer with either name can be updated or deleted by Stream Trace’s create/update and cleanup paths. Those boundaries do not make the indexer passive: its managed consumers and ACKs affect JetStream retention semantics.

Retention-policy safety

• LimitsPolicy: supported. Stream Trace’s ACKs do not delete messages; the stream’s age, count, and byte limits control retention.
• WorkQueuePolicy: message indexing and historical search are unsupported. Stream Trace detects the retention policy, skips the stream automatically, and does not create stream_trace_message_search_index. No manual exclusion is required. Stream-scoped search reports the unsupported capability instead of returning an empty result.
• InterestPolicy: exclude by default. The Stream Trace consumer becomes another interest holder, can delay deletion until it ACKs, and changes when messages are eligible for removal when that consumer is created or deleted. Index one only after accepting those retention effects explicitly.

These warnings follow the documented JetStream semantics: a WorkQueuePolicy message is removed after consumption and acknowledgement, while an InterestPolicy message is removed after all matching consumers have ACKed it. See the official NATS retention-policy reference.

ST_INDEXER_STREAM_EXCLUDE matches stream names, not subjects. See Indexing & performance and the application integration checklist before connecting Stream Trace to production streams.