Package com.inductiveautomation.eventstream.gateway.diagnostic
The package owns one job: turning live event-stream state into the context and tools a model needs to answer "is anything wrong with my event streams, and what". It renders text for a prompt. It does not evaluate stream health itself, does not surface anything in the UI directly, and holds no state of its own.
Entry point
EventStreamDigestAgent.build is
the only way in. It returns a DiagnosticDigestGenerator
that the module's gateway hook registers once, against the nav mount for the Event Streams
service page. Registration happens during hook startup rather than setup, because the AI
subsystem has not published the context the generator registers into until then.
Two flows, deliberately unequal
The generator drives two agents that do not see the same data, because they are paid for differently. A cheap summary renders on page load; a deeper analysis runs only when an operator asks for it.
- Shared context — headline counts and faulted-stream callouts, built from the state-only stream listing. Cheap enough for every page load.
- Analysis-only context — the stream roster (capped), a scan-produced shortlist of streams worth drilling into, and recent WARN+ log events.
- Analysis-only tools — per-stream diagnostics fetched on demand for the one stream the model asks about, at full fidelity, plus a filtered name-and-state listing that keeps every stream reachable regardless of what the roster's cap left out.
Heavy per-stream detail is reached through the tool rather than pre-rendered into the prompt. That is what keeps prompt size independent of how many streams a gateway hosts.
That tool and its renderer live in the diagnostic.tool subpackage, which is
where the split is enforced rather than merely described: everything in this package is
pre-rendered and therefore bounded, everything in that one is fetched on demand and therefore
unbounded. Only EventStreamTools.bundle crosses back.
Data flow and lifecycle
The generator is built once and lives as long as the module, capturing the live EventStreamManager. Nothing is
cached: every section is a supplier that reads event-stream state at the moment it renders, so
two digests requested a minute apart describe two different moments. Sections and tool calls run
on the requesting thread, and each returns a snapshot — no section can observe a value changing
mid-render, and none can report a trend.
Because the captured manager is live, nothing in this package may be retained beyond the gateway's lifetime.
Invariants held across the package
These are the rules that keep the rendered text honest. Every one of them exists because the consumer is a model that will otherwise fill the gap with a plausible guess.
- Absent is not zero. Metric coverage is uneven by stage type. A metric a stage does
not publish renders as a dash; only a value genuinely measured as zero renders as
0. Collapsing the two would report a busy stage as idle. - Never claim more coverage than was achieved. Any section that caps, samples, or skips says so in its own text, and says what the absence of a finding does not prove.
- Redact before rendering. Free text reaching a prompt — error messages, stack traces, log lines — passes through credential redaction first.
- A partial digest beats a failed one. Each section is registered behind a guard that logs and yields nothing on failure, so one unreadable stream cannot cost the operator the whole report.
Extension guidance
New context belongs in a section supplier registered through the same guard as the existing
ones, and on the cheap shared flow only if it is genuinely cheap. Anything whose cost scales with
stream or stage count belongs behind a tool instead. Rendering concerns — metric-to-cell
conversion, number and time formatting, redaction, truncation — belong in DigestFormat rather than
inline in a section, so that one metric reads identically wherever it appears.
Judgments about what the numbers mean belong in the framing prompt, not in code. Code here selects and renders; the model interprets.
-
ClassesClassDescriptionThe rendering vocabulary shared by every section of the Event Streams diagnostic digest: metric-to-cell conversion, number and time formatting, and the redaction and truncation applied to any text that reaches a prompt.Builds the
DiagnosticDigestGeneratorfor the gateway's Event Streams subsystem, which produces two digests: a cheap summary and a deeper analysis.