nats-trail
v0.5.0
Published
Agent-native observability for NATS and JetStream: CLI, MCP server and web UI.
Maintainers
Readme
nats-trail
Agent-native observability for NATS and JetStream. A web UI, a CLI and an MCP server over one bounded query engine, so humans and agents debug the same event bus from the same source of truth.
npx nats-trail serve # UI + API on http://127.0.0.1:4000
npx nats-trail trace --request-id req-8f21c --limit 20Why
Every NATS GUI answers "what is in this stream?". The hard question is "why did this one flow
fail?" — following a single request_id across four streams and a dead-letter subject. NATS Trail
answers that, and exposes the answer to agents as a typed, bounded, read-only tool contract.
The agent surface is read-only by construction
executeMcpTool() receives an interface that exposes only read functions. There is no disabled
publish behind a feature flag — there is no publish to call. A misconfigured environment
variable cannot purge your production stream, because the code path does not exist.
That is the only reason it is reasonable to hand an agent a prod context.
Commands
serve Start the API bridge and the web UI
contexts list List configured contexts
streams list List JetStream streams
messages search Search messages through the Query Engine
trace Trace by --request-id or --correlation-id
dlq search Search dead-letter messages
mcp run <tool> Run an MCP tool contractRun without arguments for an interactive shell, or nats-trail help for the full list.
Full documentation: https://github.com/solsolettidev/nats-trail
License
Apache-2.0
