User Journey: Watch the message bus

"I want to know whether the message bus is healthy." The system administrator reads one screen and gets the NATS server's vitals and one row per stream. The journey is done when the administrator can say whether messages are moving, whether any consumer is slow, and whether a stream is growing without bound.

The system administrator: an account that holds the SuperAdmin role and acts from the system tenant, in system administration mode. The shell offers this screen in the Operations area, so a tenant administrator cannot reach it, and neither can any other signed-in person.

The trigger is a symptom one level up: results are late, a service is quiet, or a stream is filling a disk. The administrator opens the bus screen and reads the vitals and the streams. The journey ends when the bus is accounted for, healthy or not.

This journey writes nothing. It reads samples that the telemetry service collects from the NATS monitoring API and stores.

1. Open the bus screen. The administrator opens the bus screen in the Operations area. The system shows one screen: a vitals panel, a stream table with one row per stream, a time range, and a chart that follows the chosen stream. The administrator expects the bus the deployment is actually running, as the telemetry service sees it.
2. Choose the range. The administrator sets the start and the end of the window. The reads answer the samples inside it — the start inclusive, the end exclusive — newest first, capped at the read's limit. Ten minutes answers a live question; a day answers an incident review.
3. Read the vitals. The system states the newest sample's current numbers — client connections and the server's memory — and the movement across the range: inbound and outbound messages and bytes. Those four counters are running totals since the NATS server started, so the screen shows the difference between the samples at the ends of the range. The slow-consumer count reads the same way: a number that grows across the range is the event the screen exists to catch.
4. Read the streams. The system gives each stream its name, the messages and bytes it currently stores, and its active consumers. A stream whose stored bytes only grow, with no consumer moving them, is the one to look at.
5. Follow one stream. The administrator opens the chart for the chosen stream: messages and bytes over the range. The legacy client charted the queue it ran itself; the installation no longer runs a queue of its own, so the chart now reads the JetStream stream samples for the same question.
6. No samples yet. The deployment is up but the range holds no sample: the telemetry service's poller has not made its first pass, the range predates it, or the poller stopped. The screen answers an empty range and says so. The poll runs on a timer, so the way to tell a stopped poller from a quiet bus is the services screen — see See the running services.
7. Leave, or go on. The administrator leaves the screen, or follows the question behind the symptom: the services that publish, the grid whose results travel this bus, or the logs the bus carried.

One screen. The vitals panel, the stream table, the range control and the stream chart are panels of that screen, because the administrator reads them as one answer. The screen is read-only: it creates nothing, changes nothing and destroys nothing.

Accepted by the user on 2026-10-04. The prototype is merged into main and kept there as the record; the accepted commit names the state.

Accepted commit

285519db99, the tip of prototype/operations-journeys, merged into main

Source

doc/prototypes/operations/message-bus/index.html

Open

/OreStudio/doc/prototypes/operations/message-bus/ once the site is built, or the file directly

Design record

Task: Prototype the operations journeys

The prototype settled the reading of a sample. The vitals keep the running totals apart from the current numbers and show the movement across the range as a difference, because a raw total says nothing without the sample it came from. The range control carries its rule in place — start inclusive, end exclusive — so adjacent ranges tile. The chart follows one chosen stream, as the legacy client's queue chart did, and reads the JetStream samples because the installation runs no queue of its own.

A sample is a point in time, not a state. The screen draws every rate from two samples, and the model states which fields are running totals since the server started and which are current at the sample time; the screen keeps the two kinds apart.

Both list subjects are served by the nats_samples model. Each request carries a query with a start, an end and a limit; the stream query adds the stream name. Each reply carries success, message and the samples the query selected, newest first. Nothing publishes these messages: the telemetry service polls the NATS HTTP monitoring API on a timer and stores what it finds. The endpoint and the interval are configuration, with http://localhost:8222 and 30 seconds as the defaults.

The browser reads them through hand-written BFF routes on the journey runtime. No route serves the operations screens yet; the prototype adds GET /api/operations/bus, which reads both lists and marks the running totals.

1. Nothing lists the streams. The stream read names one stream, and no read says which streams exist or have samples, so the table depends on names from somewhere else. The candidate is a read of the stream names present in the range, so the screen draws its own table.
2. Rates are left to the reader. Every message and byte field is a running total since the server started, so each reader subtracts two samples to get a rate, and every reader must subtract the same way. The candidate is for the read to answer deltas or rates over the range beside the totals.
3. The limit truncates in silence. The query carries a limit — 1000 by default — and no offset and no total. At the 30-second poll interval the limit covers about eight hours, so a week-long range answers the newest 1000 samples and says nothing about the rest. The candidates are paging, a total on the reply, or an explicit statement that the reply is capped.
4. A slow-consumer count cannot name the consumer. The sample keeps a running count, and the monitoring API knows which connection is slow. The screen can show that slow consumers exist, not which ones. The candidate is per-connection detail on the sample, or a current count beside the total.
5. The reads check no permission. The handlers authenticate the token and then serve any signed-in account. The candidate is a dedicated permission the model guards, as the tenant reads guard iam::tenants:read. The gap is not these reads' alone (Nothing gates a hand-written operation handler).

• See the running services — the telemetry service is the poller behind these samples; an empty range starts there
• Watch the compute grid — the work and the results this bus carries; idle nodes and a busy bus is one situation
• Read the telemetry logs — the lines behind a slow consumer or a refused publish
• Check the versions and the database — the build on both ends of a connection that misbehaves

• ores.telemetry.nats_samples
• ores.telemetry
• ores.nats
• NATS
• Message Queue
• NATS Monitor Design
• Journey execution
• Operations journeys
• How do I add a PlantUML diagram?

• User Journeys
• ores.telemetry Messaging Reference
• Protocol Reference