Class DigestFormat
The 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.
This exists as its own type because the digest is assembled by several unrelated
renderers — the summary, the roster, the drill shortlist, the on-demand per-stream table and
the log section — and every one of them has to render a metric the same way. A stage's
errors column must read identically whether it came from the tool's table or from a
shortlist reason, or the analysis agent is being shown two different pictures of one number.
One invariant runs through the whole class and is the reason most of these methods exist at
all: absent and zero are different findings and must never render alike. Metric coverage in
StageDiagnostics.metrics() is uneven by design — only the source stage reports
recv 1m, only filter reports forwarded, OnErrorStage reports nothing at all — so folding a
missing key to 0 would tell the model that a healthy, busy stage is idle. Every *Cell method
below therefore renders — for a key the stage does not publish and a numeric 0 only for a
value genuinely measured as zero. msCell(StageDiagnostics, String) carries that one step further and dashes on a
zero too, because an unwritten timer publishes its keys with a 0 in them — see that method for
why zero and absent are the same finding for a timing and only for a timing.
metricLong(StageDiagnostics, String) and metricDouble(StageDiagnostics, String) are the deliberate exception: they do fold a
missing key to zero, because their callers are threshold tests where "not reported" and "zero"
lead to the same decision (no signal). A caller that needs to tell the two apart must read
StageDiagnostics.metrics() directly — see EventStreamDigestAgent.stalledSourceSignal,
which does exactly that.
Stateless: every method is a pure function of its arguments, so the digest's section suppliers
can call these from any thread at render time. Public only so the on-demand tool's renderer in
diagnostic.tool shares this one vocabulary; nothing outside the digest should call it.
-
Method Summary
Modifier and TypeMethodDescriptionstatic StringRenders a free-text value into a Markdown table cell:—when blank, otherwise flattened to one line and escaped, so neither an embedded newline nor an embedded pipe can break the column layout.static StringcountCell(StageDiagnostics stage, String key) Renders one count column:—when the stage reports no such metric, otherwise the value as a whole number.static StringformatMs(double millis) Formats a duration in milliseconds, widening the unit at one second and the precision below ten milliseconds.static StringformatRate(double rate) Formats a received-throughput rate — events per second, not a time in nanoseconds — so unlikeformatMs(double)it must never be scaled.static doublemetricDouble(StageDiagnostics stage, String key) Reads one metric as adouble, folding a key the stage does not publish to0.0.static longmetricLong(StageDiagnostics stage, String key) Reads one metric as along, folding a key the stage does not publish to0.static StringmsCell(StageDiagnostics stage, String key) Renders one timing column:—when the stage has no timing to report, otherwise the value converted from nanoseconds and formatted as milliseconds.static StringPicks the singular or plural wording for a count.static StringqualifiedName(String project, String path) Theproject / pathform used to name a stream everywhere in the digest.static StringqueueCell(StageDiagnostics stage) Renders the queue column for one stage: the depth as reported, uninterpreted, left for the reader to judge.static StringrateCell(StageDiagnostics stage, String key) Renders one received-rate column:—when the stage reports no such metric, otherwise the formatted rate.static StringBlanks the credentials carried by any URL embedded in freeform text:user:pass@userinfo is dropped, and the value of a credential-shaped query or parameter key —?api_key=,;password=,&token=— is replaced withREDACTED.static StringsafeMessage(@Nullable String message) Collapses a log message's internal whitespace onto one line so it cannot break the bullet it is rendered into.static StringstageStateLabel(StageState state) Renders a stage's state for a table cell, inlining a truncated fault reason so the row carries why it faulted without the trace.static StringtimeOfDay(long epochMillis) Formats an epoch-millisecond instant as a bareHH:mm:ssin the gateway's zone.static StringTruncates to at mostmaxcharacters, marking the cut with an ellipsis.
-
Method Details
-
timeOfDay
Formats an epoch-millisecond instant as a bare
HH:mm:ssin the gateway's zone.Time of day only, with no date: everything the digest timestamps — a stage error, a log event — is drawn from a window measured in minutes, so the date would be the same on every line. The framing prompt warns the model that these are the only clock it gets, so the omission is deliberate rather than an oversight.
-
countCell
Renders one count column:
—when the stage reports no such metric, otherwise the value as a whole number.Counts are cumulative and published as integral values, so the
Numberis read as along. -
rateCell
Renders one received-rate column:
—when the stage reports no such metric, otherwise the formatted rate.Absent and zero are different findings and must not render alike. Rate coverage is uneven across stage types — the source publishes a 1-minute and a 15-minute rate, the encoders publish a 15-minute and an all-time mean, and every other stage publishes none — so folding a missing metric to
0would tell the analysis agent that a healthy, busy stage is receiving nothing. A rate genuinely measured as zero still renders0, and that distinction is the whole point.Note that the diagnostics table calls this for the source row only. Every other stage's received meter is drain-gated and its rates are unusable — see
EventStreamDiagnosticsRenderer.render— so the encoders' rates are published but never rendered. -
msCell
Renders one timing column:
—when the stage has no timing to report, otherwise the value converted from nanoseconds and formatted as milliseconds.Every
PROCESS_TIME_*metric is published in nanoseconds; the conversion lives here so no caller has to remember the unit.Unlike
countCell(StageDiagnostics, String)andrateCell(StageDiagnostics, String), this method dashes on a zero as well as on a missing key, because for a timing metric zero is the absent case and the null check cannot see it. Every stage butOnErrorStagepublishes all fourPROCESS_TIME_*keys out of an unconditionalMap.of(...)literal — measured or not — and an empty Dropwizard reservoir answers0togetMean,get99thPercentileandgetMax. So a stage whose timer has never been written arrives here with the key present, carrying0.Rendering that
0as a measurement is the worst failure this class can produce, because the stage most likely to hit it is the one most worth diagnosing:Stage.markProcessEndTimerecords only on the success path, so a handler that throws on every call is never timed at all. It would rendermean 0 ms | p99 0 ms | max 0 ms, and the framing prompt tells the model a numeric zero is a real measurement — a handler doing no work becomes a handler doing work instantly.Folding zero to
—therefore costs no real signal. The only other way to reach zero would be a genuinely measured one, and these values areSystem.nanoTime()deltas spanning a stage's entireprocesscall, so the smallest real sample is tens of nanoseconds — and even a sub-microsecond one renders0.0 ms, still distinct from the dash. -
queueCell
Renders the queue column for one stage: the depth as reported, uninterpreted, left for the reader to judge.
A max is the exception, not the rule: only the batch stage reports
EventStreamConstants.Metrics.QUEUE_MAX_SIZE, and only when an operator configured a max queue size (the default is unbounded — seeBatchConfig, where any value<= 0means no limit). The filter and transform stages report a queue depth against an unbounded executor backlog, with no max at all. So the depth is rendered whenever the stage reports one:queued/max— e.g.812/1000— when the queue is bounded,- the depth alone — e.g.
42— with no maximum, when the queue is unbounded, and —only for stages that have no queue.
-
metricLong
Reads one metric as a
long, folding a key the stage does not publish to0.For threshold tests, where an unreported metric and a zero one both mean "no signal". A caller that must distinguish them reads
StageDiagnostics.metrics()itself. -
metricDouble
Reads one metric as a
double, folding a key the stage does not publish to0.0.Same contract as
metricLong(StageDiagnostics, String): for threshold tests only. The fold is what letslatencyTailSignalskip an uninstrumented stage without a null check —0.0lands below its floor. -
stageStateLabel
Renders a stage's state for a table cell, inlining a truncated fault reason so the row carries why it faulted without the trace. The full message and stack trace are rendered separately by the per-stream tool.
The call order —
redact, thensafeMessage, thentruncate— is load-bearing rather than stylistic:redactmust run beforetruncate, becauseUSERINFOanchors on the@that ends a URL's userinfo section. A cut landing before that@stops the pattern matching and the password is emitted verbatim.safeMessagemust also run beforetruncate, because a multi-line message's indentation spends the 120-character budget on whitespace that is then collapsed away. A Jython traceback loses roughly a fifth of the budget when flattened after the cut.
-
cell
Renders a free-text value into a Markdown table cell:—when blank, otherwise flattened to one line and escaped, so neither an embedded newline nor an embedded pipe can break the column layout. The newline is the more damaging of the two: Markdown ends a table at the first line that is not a row, so one multi-line cell drops every row below it. -
qualifiedName
-
redact
Blanks the credentials carried by any URL embedded in freeform text:
user:pass@userinfo is dropped, and the value of a credential-shaped query or parameter key —?api_key=,;password=,&token=— is replaced withREDACTED.This is the digest's one egress filter. Every string that reaches a prompt — stage fault messages, stage error messages, stack traces, log messages — passes through here, so a gap in this method is a gap in all of them.
Known bound:
SENSITIVE_PARAMis a denylist of key names, so an unconventionally named parameter —?x-vendor-cred=— still reaches the model. That is a deliberate trade rather than an oversight: blanking every query value would also erase the benign routing parameters (?site=plant4) that tell the model which endpoint and which route failed, which is much of why the digest exists. Widen the key list when a new convention turns up. -
truncate
-
safeMessage
-
formatMs
Formats a duration in milliseconds, widening the unit at one second and the precision below ten milliseconds.
Locale.ROOTis pinned on everyformatcall: a gateway running under a comma-decimal default locale would otherwise render1,2 s, which reads as twelve to a model that has been told these are decimals. -
formatRate
Formats a received-throughput rate — events per second, not a time in nanoseconds — so unlikeformatMs(double)it must never be scaled. Precision widens as the rate shrinks so a slow trickle still reads as more than "0". -
plural
Picks the singular or plural wording for a count.
Collapses what were a half-dozen inline
n == 1 ? ... : ...ternaries scattered across the section renderers into one decision point. Callers append the count themselves, so this returns only the word.- Parameters:
count- the quantity being described.singular- the wording used whencountis exactly 1.plural- the wording used otherwise, including for zero.- Returns:
- whichever wording matches
count.
-