@senpi/runtime 3.0.108 → 3.0.111

package/dist/telemetry/live-telemetry.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The publisher: the piece that turns the buffer and the three builders into frames on the gateway
+ * websocket, plus the snapshot a client reads when it connects.
+ *
+ * Two things about the transport shape the whole module:
+ * - The only route to the websocket is a captured `context.broadcast`, and `context` exists only
+ *   inside a gateway RPC handler — the plugin api object has no push surface at all. So the handle is
+ *   captured from the FIRST request of ANY kind, not only from the subscribe method: a box whose
+ *   client never calls subscribe would otherwise hold nothing to publish through, silently.
+ * - The gateway drops any event name that does not start with `plugin.`, and closes the socket with
+ *   1008 for a slow client unless the call passes `dropIfSlow`. Both are enforced here rather than at
+ *   each call site, because either mistake is invisible until a client is missing frames.
+ *
+ * Three cadences, because the three payloads cost different things to build:
+ * - timeline, on the flush tick — a drain plus a filter, cheap, and the one a live screen feels.
+ * - stats, on the sample tick — a scan of the whole held window and an async read of every runtime's
+ *   health and system state, so it runs an order of magnitude less often.
+ * - topology, on the sample tick but published only when it changes — it rides the same gather as
+ *   stats, and nothing in the plugin signals a topology change, so "on change" means polled and
+ *   diffed rather than pushed.
+ *
+ * The snapshot is what stops a client that joins mid-life from seeing an empty screen: it is read
+ * from the buffer's held window, which the flush drain never evicts.
+ *
+ * Everything that leaves the box is scrubbed here. `logger.event` redacts its `redact` slot and not
+ * its `attributes`, which is sound for the disk ring — that never leaves — but not for a stream a
+ * browser reads. There are three ways out — the timeline frame, the stats frame and the snapshot
+ * that carries one of each — and two kinds of free text between them, so the scrub sits in two
+ * places:
+ * - {@link toWireRecord} for a timeline record's attributes. It is what makes the flush tick
+ *   asynchronous and gives it an in-flight guard.
+ * - {@link scrubStatsPayload} for the scanner state's three free-text fields, which reach both the
+ *   stats frame and the snapshot. Their content is a stringified throwable from a scanner process,
+ *   so it is the one string on the wire with no bound of its own and it is capped as well as
+ *   scrubbed.
+ *
+ * The topology payload carries no captured text: its `name` and `scannerId` are operator-authored
+ * config keys the client joins on, and the scanner `config` that could hold a resolved secret is
+ * never copied onto it.
+ */
+import type { EventName } from "../utils/event-catalog.js";
+import { type TimelineBuffer } from "./timeline-buffer.js";
+import { type ScannerStateSnapshot, type ScannerStatsPayload } from "./scanner-stats.js";
+import { type IdMembership, type RuntimeHealthLike, type StrategyTopologyPayload, type TopologyStrategySource } from "./strategy-topology.js";
+/** The gateway drops any broadcast whose name does not carry this prefix, with no error. */
+export declare const EVENT_TIMELINE = "plugin.senpi.timeline";
+export declare const EVENT_STATS = "plugin.senpi.scanner.stats";
+export declare const EVENT_TOPOLOGY = "plugin.senpi.strategies";
+/**
+ * Byte ceiling for one frame. A frame published here travels southbound — gateway to bridge — and
+ * meets the bridge's southbound read limit, 1 MiB unless a deployment sets its own; a frame past it
+ * takes the whole connection down rather than costing the one frame. The budget is set far inside
+ * that: the payload envelope the gateway wraps around ours, and the growth of a single record's
+ * attribute bag, both have to fit in the margin, and neither is measured here.
+ */
+export declare const MAX_FRAME_BYTES: number;
+/**
+ * Character ceiling for one of the scanner state's free-text fields on the wire — `lastRunReason`,
+ * `lastRunStatus` and `degradedReason`.
+ *
+ * These carry a stringified throwable from a scanner process, which nothing upstream bounds: an HTTP
+ * client's error message alone runs to a few hundred characters and a stack-bearing one to
+ * kilobytes, once per scanner per sample. 1024 holds the sentence that says what failed — the error
+ * type, the operation and the endpoint. It is also what keeps the payload bounded at all: this frame
+ * is published whole, with no splitting of the kind the timeline does, so two hundred scanners each
+ * reporting a 4 KiB error in every one of the three fields serialise to about 1.7 MB — past the read
+ * limit that ends the connection — and at this cap the same box lands under half of it.
+ */
+export declare const MAX_SCANNER_TEXT_CHARS = 1024;
+/**
+ * What one of those fields reads as when its text could not be scrubbed — no redactor registered, or
+ * a redactor that threw.
+ *
+ * Not `null` and not an absent key: the producer reporting no reason and this box withholding one it
+ * cannot vouch for are different facts, and a summary screen is read as if they were the same.
+ */
+export declare const SCANNER_TEXT_WITHHELD = "[withheld: not scrubbed]";
+/** Flush cadence for the timeline. A live screen feels this number. */
+export declare const DEFAULT_FLUSH_INTERVAL_MS = 1000;
+/**
+ * Sample cadence for stats and topology. Both are built from one async read of every runtime's health
+ * and system state, so they share a tick. Five seconds is roughly a third of the default bucket width
+ * — fast enough that a counter visibly moves and a hung scan is seen while it is still running, slow
+ * enough that the per-scanner store read behind the system state is not a poll loop.
+ */
+export declare const DEFAULT_SAMPLE_INTERVAL_MS = 5000;
+/**
+ * The PUBLICATION list: what leaves on the timeline event. A name being on this list AND on the
+ * admission list is the normal case, not a duplication — `signal.outcome` is the decision row the feed
+ * is built around and the source of `opens`/`closes`/`skips`, and the two `scaffold.tick_*` names are
+ * the source of `errors` and the rows behind the Errors filter. A failing external scanner has to
+ * leave a visible line, not only a number that silently goes up.
+ *
+ * The two lists are separate so admission can be widened for a counter the feed does not display,
+ * which is the direction that has to stay open: the display filter belongs here at publish time,
+ * where it is still recoverable, never at append time, where it is not. Today nothing is admitted for
+ * counting alone, so the sets are equal — the seam is what matters, not the difference.
+ */
+export declare const PUBLISHED_EVENT_NAMES: ReadonlySet<EventName>;
+/**
+ * The share of its own interval a tick may take before it is warned about. A fraction rather than a
+ * constant, so a deployment that changes a cadence gets a proportional threshold: 250ms on the
+ * one-second timeline flush, 1.25s on the five-second sample.
+ *
+ * A quarter, not a whole interval. Both ticks share an event loop with the serial trading path, so a
+ * tick holding it for a quarter of its own period is already adding latency to trading; and a tick
+ * that fills its interval has already started stacking on the next one, which is too late to be told.
+ */
+export declare const SLOW_TICK_FRACTION = 0.25;
+/**
+ * How often the timing summary is logged, and the floor between two slow-tick warns of the same kind.
+ * The flush tick runs every second, so a line per tick would be tens of thousands a day for numbers
+ * that only mean anything aggregated — and a repeating tick that is slow is slow every time.
+ */
+export declare const TIMING_REPORT_INTERVAL_MS = 60000;
+export interface GatewayBroadcastOpts {
+    dropIfSlow?: boolean;
+    stateVersion?: number;
+}
+export type GatewayBroadcastFn = (event: string, payload: unknown, opts?: GatewayBroadcastOpts) => void;
+/** One record as it goes on the wire. */
+export interface TimelineWireRecord {
+    seq: number;
+    ts: number;
+    name: string;
+    level: string;
+    address: string;
+    scannerId?: string;
+    body: string;
+    attrs: Record<string, string | number | boolean>;
+}
+export interface TimelinePayload {
+    v: 1;
+    epoch: string;
+    batchSeq: number;
+    records: TimelineWireRecord[];
+}
+export interface TelemetrySnapshot {
+    epoch: string;
+    topology: StrategyTopologyPayload;
+    stats: ScannerStatsPayload;
+    recent: TimelinePayload;
+    /**
+     * The client asked to resume from a cursor inside THIS epoch whose successor is no longer held, or
+     * the window it is owed did not fit one frame. Either way there is a gap this response cannot fill,
+     * and only the box knows it: `recent.records` alone looks like a normal short window.
+     *
+     * A cursor from another epoch is not truncation. It buys nothing, so the whole retained window is
+     * served — which is the most this box could ever serve, and so nothing was withheld.
+     */
+    truncated: boolean;
+}
+/** Everything the two builders need that the buffer cannot supply, gathered once per tick. */
+export interface TelemetryFacts {
+    strategies: TopologyStrategySource[];
+    runningRuntimeIds: IdMembership;
+    unwiredRuntimeIds: IdMembership;
+    readHealth?: (runtimeId: string) => RuntimeHealthLike | undefined;
+    scannerState: ScannerStateSnapshot[];
+}
+export interface LiveTelemetryOptions {
+    /** Defaults to the process buffer — one per process, shared by every address. */
+    buffer?: TimelineBuffer;
+    collectFacts: () => Promise<TelemetryFacts>;
+    flushIntervalMs?: number;
+    sampleIntervalMs?: number;
+    now?: () => number;
+    /**
+     * Monotonic millisecond reader for tick durations. Defaults to `performance.now`; `now` is wall
+     * clock and can step backwards under NTP, which would report a negative tick.
+     */
+    monotonicMs?: () => number;
+}
+export interface LiveTelemetry {
+    readonly epoch: string;
+    /** Take the broadcast handle off a gateway request context if we do not hold one yet. */
+    captureBroadcast(ctx: unknown, methodName: string): void;
+    /** `afterSeq` counts only when `afterEpoch` is the epoch this box is running. */
+    snapshot(params?: {
+        afterEpoch?: unknown;
+        afterSeq?: unknown;
+    }): Promise<TelemetrySnapshot>;
+    /** One flush tick: drain, filter to the publication list, scrub, frame, broadcast. */
+    flushTimeline(): Promise<void>;
+    /** One sample tick: stats always, topology when it changed. */
+    sample(): Promise<void>;
+    start(): void;
+    /** Clear both timers, drop the captured handle, and empty the buffer. */
+    stop(): void;
+}
+export declare function createLiveTelemetry(options: LiveTelemetryOptions): LiveTelemetry;
+//# sourceMappingURL=live-telemetry.d.ts.map

package/dist/telemetry/live-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/live-telemetry.ts"],"names":[],"mappings":"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"}