Class DigestFormat

java.lang.Object
com.inductiveautomation.eventstream.gateway.diagnostic.DigestFormat

public final class DigestFormat extends Object

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 Type
    Method
    Description
    static String
    cell(@Nullable String value)
    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.
    static String
    Renders one count column: — when the stage reports no such metric, otherwise the value as a whole number.
    static String
    formatMs(double millis)
    Formats a duration in milliseconds, widening the unit at one second and the precision below ten milliseconds.
    static String
    formatRate(double rate)
    Formats a received-throughput rate — events per second, not a time in nanoseconds — so unlike formatMs(double) it must never be scaled.
    static double
    Reads one metric as a double, folding a key the stage does not publish to 0.0.
    static long
    Reads one metric as a long, folding a key the stage does not publish to 0.
    static String
    Renders one timing column: — when the stage has no timing to report, otherwise the value converted from nanoseconds and formatted as milliseconds.
    static String
    plural(long count, String singular, String plural)
    Picks the singular or plural wording for a count.
    static String
    qualifiedName(String project, String path)
    The project / path form used to name a stream everywhere in the digest.
    static String
    Renders the queue column for one stage: the depth as reported, uninterpreted, left for the reader to judge.
    static String
    Renders one received-rate column: — when the stage reports no such metric, otherwise the formatted rate.
    static String
    redact(@Nullable String value)
    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 with REDACTED.
    static String
    safeMessage(@Nullable String message)
    Collapses a log message's internal whitespace onto one line so it cannot break the bullet it is rendered into.
    static String
    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 String
    timeOfDay(long epochMillis)
    Formats an epoch-millisecond instant as a bare HH:mm:ss in the gateway's zone.
    static String
    truncate(@Nullable String value, int max)
    Truncates to at most max characters, marking the cut with an ellipsis.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • timeOfDay

      public static String timeOfDay(long epochMillis)

      Formats an epoch-millisecond instant as a bare HH:mm:ss in 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

      public static String countCell(StageDiagnostics stage, String key)

      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 Number is read as a long.

    • rateCell

      public static String rateCell(StageDiagnostics stage, String key)

      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 0 would tell the analysis agent that a healthy, busy stage is receiving nothing. A rate genuinely measured as zero still renders 0, 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

      public static String msCell(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.

      Every PROCESS_TIME_* metric is published in nanoseconds; the conversion lives here so no caller has to remember the unit.

      Unlike countCell(StageDiagnostics, String) and rateCell(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 but OnErrorStage publishes all four PROCESS_TIME_* keys out of an unconditional Map.of(...) literal — measured or not — and an empty Dropwizard reservoir answers 0 to getMean, get99thPercentile and getMax. So a stage whose timer has never been written arrives here with the key present, carrying 0.

      Rendering that 0 as 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.markProcessEndTime records only on the success path, so a handler that throws on every call is never timed at all. It would render mean 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 are System.nanoTime() deltas spanning a stage's entire process call, so the smallest real sample is tens of nanoseconds — and even a sub-microsecond one renders 0.0 ms, still distinct from the dash.

    • queueCell

      public static String queueCell(StageDiagnostics stage)

      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 — see BatchConfig, where any value <= 0 means 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

      public static long metricLong(StageDiagnostics stage, String key)

      Reads one metric as a long, folding a key the stage does not publish to 0.

      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

      public static double metricDouble(StageDiagnostics stage, String key)

      Reads one metric as a double, folding a key the stage does not publish to 0.0.

      Same contract as metricLong(StageDiagnostics, String): for threshold tests only. The fold is what lets latencyTailSignal skip an uninstrumented stage without a null check — 0.0 lands below its floor.

    • stageStateLabel

      public static String stageStateLabel(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. The full message and stack trace are rendered separately by the per-stream tool.

      The call order — redact, then safeMessage, then truncate — is load-bearing rather than stylistic:

      • redact must run before truncate, because USERINFO anchors on the @ that ends a URL's userinfo section. A cut landing before that @ stops the pattern matching and the password is emitted verbatim.
      • safeMessage must also run before truncate, 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

      public static String cell(@Nullable String value)
      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

      public static String qualifiedName(String project, String path)
      The project / path form used to name a stream everywhere in the digest. It is also the form the framing prompt tells the model to split when calling event_stream_diagnostics, so the separator is load-bearing rather than cosmetic.
    • redact

      public static String redact(@Nullable String value)

      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 with REDACTED.

      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_PARAM is 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

      public static String truncate(@Nullable String value, int max)
      Truncates to at most max characters, marking the cut with an ellipsis.
    • safeMessage

      public static String safeMessage(@Nullable String message)
      Collapses a log message's internal whitespace onto one line so it cannot break the bullet it is rendered into.
    • formatMs

      public static String formatMs(double millis)

      Formats a duration in milliseconds, widening the unit at one second and the precision below ten milliseconds.

      Locale.ROOT is pinned on every format call: a gateway running under a comma-decimal default locale would otherwise render 1,2 s, which reads as twelve to a model that has been told these are decimals.

    • formatRate

      public static String formatRate(double rate)
      Formats a received-throughput rate — events per second, not a time in nanoseconds — so unlike formatMs(double) it must never be scaled. Precision widens as the rate shrinks so a slow trickle still reads as more than "0".
    • plural

      public static String plural(long count, String singular, String 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 when count is exactly 1.
      plural - the wording used otherwise, including for zero.
      Returns:
      whichever wording matches count.