StreamTrace BETA
Documentation menu

Using Stream Trace

Searching messages

Filter by subject, sequence, and time, and search payloads with full-text and JSON path queries.

The Messages tab is a fast, virtualized table over a stream’s messages. Select any message to open the inspector, which shows the payload with JSON syntax highlighting and collapsing, the headers, and metadata. You can copy or download a message as JSON.

Filters available everywhere

  • Subject - match a subject or wildcard (e.g. orders.*).
  • Sequence range - from / to sequence numbers.
  • Time range - rolling presets (15m, 1h, 4h, 24h, 2d, 7d, 14d, 30d) or a custom range.

Message source

A source toggle lets you read directly from NATS (always live) or from Stream Trace’s index (fast for large streams). Stream Trace picks a sensible default based on stream size and index readiness, and you can override it.

WorkQueue streams

Message history isn’t available for WorkQueue streams. Messages are removed when workers acknowledge them, so Stream Trace cannot capture them reliably.

Historical message search, payload search, and trace-header search are unsupported for WorkQueuePolicy. Stream configuration, consumers, pending/redelivery metrics, and advisories remain available. A direct view may show currently retained messages, but that is a point-in-time snapshot rather than complete history.

Stream Trace detects the retention policy and skips indexing automatically. A stream-scoped search returns a structured 422 with the work_queue_retention reason, while global search identifies every excluded WorkQueue stream. See the WorkQueuePolicy support boundary for the complete capability contract.

Beyond metadata filters, you can search message contents:

  • Full-text search across the payload body.
  • JSON path queries that target a scalar field, with operators: exists, equals, not equals, gt, gte, lt, and lte.

Payload search requires the payload index. It is off by default. Enable it with ST_PAYLOAD_INDEXING_ENABLED=true and let the indexer catch up. Indexing limits (payload size, JSON depth, scalar count) are tunable - see Indexing & performance. Until a stream’s payload index is ready, payload filters are disabled for that stream.

Export

Export the current selection-or everything matching your filters-to a JSON file. The UI requires confirmation before truncating results above 50,000 messages. Ordinary reads and exports are not recorded in the audit log.