Package com.inductiveautomation.eventstream.gateway.diagnostic.tool
The tools the Event Streams diagnostic digest hands its analysis agent: on-demand, full-fidelity diagnostics for a single named event stream, and the listing that lets the agent name a stream the prompt never mentioned.
Everything in the parent diagnostic package is pre-rendered — the model reads it whether or
not it needs it, so every section there is capped, sampled, or truncated to keep prompt size
independent of how many streams a gateway hosts. This package is the inversion. The model names
one stream, pays one tool call, and gets that stream's whole picture back: every stage row and
every faulted or erroring stage's full reason, uncapped and untruncated, because the cost is
paid per investigation rather than per page load.
The one exception: stack traces
Stack traces are the only thing event_stream_diagnostics still caps. Everything else it
renders is one row per stage, and a stream has a dozen stages at the outside, so leaving those
uncapped costs nothing.
Traces are different because their size is two numbers multiplied together, and the platform
bounds only one of them:
- How many traces — bounded. Each stage keeps at most
EventStreamConstants.ERROR_COUNT_MAXerrors. - How many frames in each trace — unbounded. It is whatever the JVM happened to capture.
So EventStreamDiagnosticsRenderer caps both numbers:
- 20 frames per trace, which the
maxFramestool parameter can raise per call, up to a hard ceiling of 40. - 10 traces per response, newest first.
Every cut is marked in the rendered Markdown, so the model can tell a trimmed trace from a
complete one, and each Caused by: / Suppressed: section gets a small frame budget of its
own, so a cap can never swallow the root cause.
list_event_streams carries the one other cap in this package — 200 streams per reply, its
MAX_STREAMS_LISTED — and for a different reason: it is the only output here whose size tracks
how many streams the gateway hosts rather than how many stages one stream has. Its reply says
how many matched and how many are shown, so a truncated listing never reads as the whole
gateway.
When adding rendering here, ask the same question: does its size track stage count, or does it multiply stage count by something nothing bounds? The first can stay uncapped; the second needs a cap, and a note in the output saying the cap was hit.
Entry point
EventStreamDigestTools.bundle(EventStreamManager)
is the only public member, and the only thing the digest agent calls.
It returns a ToolBundle carrying both list_event_streams and event_stream_diagnostics, registered on the
analysis flow only. Adding a tool means adding an annotated method to that class —
Tools.fromAnnotated reflects over every @Tool method on the instance, so no wiring
changes. The renderers behind them are package-private on purpose: nothing outside this package
should render a per-stream table, because doing so from a pre-rendered section would reintroduce
exactly the unbounded prompt growth the tools exist to avoid.
How the model gets here
event_stream_diagnostics takes a project and a path, not a stream handle, so the model needs
those two strings before it can drill anything. Three places supply them: the roster lists
streams as project / path up to its cap, the scan shortlist says which of those are worth a
tool call, and list_event_streams produces the rest on demand. The roster's truncation note is
still load-bearing — it is what tells the model to go ask for the remainder rather than assuming
the roster was the whole gateway.
Freshness and failure
The tools hold the live EventStreamManager and re-read it on every call, so two calls in one conversation can
legitimately disagree — that is a real change in the gateway, not an inconsistency to smooth
over. A stream the model names may also have been deleted since the roster rendered, or its path
mistyped; that returns a plain sentence rather than throwing, because a thrown tool error reads
to the model as something to retry, whereas a sentence tells it what to do differently.
Extension guidance
New analysis-only tools belong here, bundled alongside the existing two. Three rules carry over from the parent package and are not negotiable:
- Free text reaching a prompt passes through
DigestFormat.redactfirst. - Metric rendering goes through
DigestFormatrather than being formatted inline, so one metric reads identically whether the model saw it in a pre-rendered section or fetched it here. - Anything a tool caps, it says so in the reply, with the total. Being on the on-demand side buys a larger cap, not the right to hide one: a reply that looks complete when it is not is worse than a short one, because the model will report having reviewed everything.
A tool description is the model's only instruction for that tool, so it must name every column
the tool actually returns — a column described but not rendered is a column the model will ask
about and never receive. Where two tools return overlapping subjects at different fidelities, as
list_event_streams and event_stream_diagnostics do, each description must also say what it
does not return, or the model will answer from whichever is cheaper.
-
ClassesClassDescriptionThe two tools the digest's analysis agent calls against live event-stream state:
find the streamandread that stream.