@nwire/studio 0.12.1 → 0.13.1

package/src/lib/rca.ts

@@ -0,0 +1,193 @@
+/**
+ * Root-cause analysis — group raw failure records into incidents and read the
+ * story out of each one. A failed chain rarely produces a single record: an
+ * action.failed retries, then dlq.recorded, while a sibling projection.failed
+ * lands on the same correlation. This groups by correlation, picks the terminal
+ * outcome as the headline, gathers every record on the chain as evidence, and
+ * derives the blast radius (apps, tenant, retries). Pure — unit-testable, and
+ * the Errors view + RcaPanel render straight off these shapes.
+ */
+import { isFailure, type TelemetryRecord } from "./telemetry";
+import {
+  explainError,
+  severityOf,
+  maxSeverity,
+  type FriendlyError,
+  type Severity,
+} from "./error-friendly";
+
+/** One step on the incident timeline — a record plus whether it's a failure. */
+export interface TimelineEntry {
+  readonly record: TelemetryRecord;
+  readonly failure: boolean;
+  /** ms since the first record on the chain, when timestamps are present. */
+  readonly offsetMs?: number;
+}
+
+/** The blast radius of an incident. */
+export interface Impact {
+  readonly tenant?: string;
+  readonly userId?: string;
+  /** Apps that touched the chain. */
+  readonly apps: readonly string[];
+  /** Total records on the chain. */
+  readonly records: number;
+  /** Failure records on the chain. */
+  readonly failures: number;
+  /** Retries the runtime made before this settled (0 = first try). */
+  readonly retries: number;
+  /** The chain ended in the dead-letter queue / exhausted retries. */
+  readonly deadLettered: boolean;
+}
+
+/** A grouped failure — everything the Errors view needs about one incident. */
+export interface Incident {
+  /** Stable id — the correlationId, or `solo:<n>` for envelope-less failures. */
+  readonly id: string;
+  readonly correlationId?: string;
+  /**
+   * The failure that represents the incident — the terminal outcome (dead-letter
+   * / exhausted) when there is one, else the loudest failure. This is what the
+   * card headline + RcaPanel speak to; the full cascade lives in `failures`.
+   */
+  readonly root: TelemetryRecord;
+  /** Humanised view of the headline failure. */
+  readonly friendly: FriendlyError;
+  /** Loudest severity across the chain's failures. */
+  readonly severity: Severity;
+  /** Every failure record on the chain, in arrival order. */
+  readonly failures: readonly TelemetryRecord[];
+  /** Every record on the chain (failures + context), in arrival order. */
+  readonly related: readonly TelemetryRecord[];
+  /** How many failures — the card's count badge. */
+  readonly count: number;
+  /** Arrival index of the latest record — sort newest-first. */
+  readonly lastIndex: number;
+}
+
+const num = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+
+/**
+ * Group a flat record list into incidents, newest first. Failures sharing a
+ * correlationId form one incident (with their whole chain as context); a
+ * failure with no correlation becomes its own solo incident.
+ */
+export function groupIncidents(records: readonly TelemetryRecord[]): Incident[] {
+  const byCorrelation = new Map<string, number[]>(); // correlationId → record indices
+  const solo: number[] = [];
+
+  records.forEach((r, i) => {
+    if (!isFailure(r)) return;
+    const cid = r.envelope?.correlationId;
+    if (cid) {
+      const bucket = byCorrelation.get(cid);
+      if (bucket) bucket.push(i);
+      else byCorrelation.set(cid, [i]);
+    } else {
+      solo.push(i);
+    }
+  });
+
+  const incidents: Incident[] = [];
+
+  for (const [cid, failureIdx] of byCorrelation) {
+    const related = records.filter((r) => r.envelope?.correlationId === cid);
+    const failures = failureIdx.map((i) => records[i]!);
+    incidents.push(makeIncident(cid, cid, failures, related, Math.max(...failureIdx)));
+  }
+
+  for (const i of solo) {
+    const r = records[i]!;
+    incidents.push(makeIncident(`solo:${i}`, undefined, [r], [r], i));
+  }
+
+  return incidents.sort((a, b) => b.lastIndex - a.lastIndex);
+}
+
+function makeIncident(
+  id: string,
+  correlationId: string | undefined,
+  failures: TelemetryRecord[],
+  related: TelemetryRecord[],
+  lastIndex: number,
+): Incident {
+  const root = pickHeadline(failures);
+  const severity = failures.reduce<Severity>((acc, r) => maxSeverity(acc, severityOf(r)), "info");
+  return {
+    id,
+    correlationId,
+    root,
+    friendly: explainError(root),
+    severity,
+    failures,
+    related,
+    count: failures.length,
+    lastIndex,
+  };
+}
+
+/**
+ * The failure that best represents the incident: a terminal outcome
+ * (dead-letter / exhausted) when present — that's the actionable headline and
+ * carries the final error — otherwise the loudest failure, ties broken by
+ * arrival order (earliest).
+ */
+function pickHeadline(failures: TelemetryRecord[]): TelemetryRecord {
+  const terminal = failures.find(
+    (f) => f.kind === "dlq.recorded" || f.kind === "reaction.exhausted",
+  );
+  if (terminal) return terminal;
+  let best = failures[0]!;
+  for (const f of failures) {
+    if (
+      maxSeverity(severityOf(best), severityOf(f)) === severityOf(f) &&
+      severityOf(f) !== severityOf(best)
+    ) {
+      best = f;
+    }
+  }
+  return best;
+}
+
+/** Build the ordered timeline for an incident, with ms offsets when available. */
+export function buildTimeline(incident: Incident): TimelineEntry[] {
+  const times = incident.related
+    .map((r) => (r.ts ? Date.parse(r.ts) : NaN))
+    .filter((t) => !Number.isNaN(t));
+  const base = times.length ? Math.min(...times) : NaN;
+  return incident.related.map((record) => {
+    const t = record.ts ? Date.parse(record.ts) : NaN;
+    const offsetMs = !Number.isNaN(t) && !Number.isNaN(base) ? t - base : undefined;
+    return { record, failure: isFailure(record), offsetMs };
+  });
+}
+
+/** Derive the blast radius of an incident from its records. */
+export function computeImpact(incident: Incident): Impact {
+  const apps = new Set<string>();
+  let attemptsMax = 1;
+  let deadLettered = false;
+  let tenant: string | undefined;
+  let userId: string | undefined;
+
+  for (const r of incident.related) {
+    const app = str(r.appName);
+    if (app) apps.add(app);
+    attemptsMax = Math.max(attemptsMax, num(r.attempt) ?? 0, num(r.attempts) ?? 0);
+    if (r.kind === "dlq.recorded" || r.kind === "reaction.exhausted") deadLettered = true;
+    // tenant/user ride the whole chain — take the first record that carries them.
+    tenant ??= r.envelope?.tenant;
+    userId ??= r.envelope?.userId;
+  }
+
+  return {
+    tenant,
+    userId,
+    apps: [...apps],
+    records: incident.related.length,
+    failures: incident.failures.length,
+    retries: Math.max(0, attemptsMax - 1),
+    deadLettered,
+  };
+}

package/src/lib/telemetry.ts

@@ -0,0 +1,155 @@
+/**
+ * Typed telemetry — the live behavior feed.
+ *
+ * Mirrors the record union the runtime + forge push onto `runtime.onTelemetry`
+ * (`@nwire/runtime` base kinds + `@nwire/forge` domain kinds). Kept as a local
+ * mirror (not a runtime import) so Studio stays a browser bundle with no kernel
+ * dependency; the shape is the contract. Pure helpers (parse, group, tree) live
+ * here so they're unit-testable without a DOM.
+ */
+
+/** Correlation envelope carried on every domain record. */
+export interface TelemetryEnvelope {
+  readonly messageId: string;
+  readonly correlationId: string;
+  readonly causationId: string;
+  readonly tenant?: string;
+  readonly userId?: string;
+}
+
+/** A serialized thrown value, as the runtime stamps it. */
+export interface SerializedError {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+  readonly [k: string]: unknown;
+}
+
+/** The known telemetry kinds. Open-ended (`string & {}`) — the UI tolerates kinds it doesn't enumerate. */
+export type TelemetryKind =
+  | "hook.step"
+  | "source.stage"
+  | "sink.stage"
+  | "action.dispatched"
+  | "action.completed"
+  | "action.failed"
+  | "event.published"
+  | "event.deduped"
+  | "event.emitted"
+  | "event.listener.failed"
+  | "actor.transitioned"
+  | "projection.folded"
+  | "projection.failed"
+  | "reaction.fired"
+  | "reaction.failed"
+  | "reaction.exhausted"
+  | "dlq.recorded"
+  | "timer.fired"
+  | "timer.scheduled"
+  | "query.executed"
+  | "listener.fired"
+  | "external.call.started"
+  | "external.call.completed"
+  | "external.call.failed"
+  | "enqueue.failed";
+
+/**
+ * One telemetry record. The discriminant is `kind`; common fields are typed,
+ * kind-specific fields stay open. The UI narrows on `kind` where it needs more.
+ */
+export interface TelemetryRecord {
+  readonly kind: TelemetryKind | (string & {});
+  readonly ts?: string;
+  readonly appName?: string;
+  readonly envelope?: TelemetryEnvelope;
+  readonly durationMs?: number;
+  readonly error?: SerializedError;
+  readonly [k: string]: unknown;
+}
+
+/** Kinds that represent a failure — the Errors surface keys off these. */
+const FAILURE_KINDS: ReadonlySet<string> = new Set([
+  "action.failed",
+  "projection.failed",
+  "reaction.failed",
+  "reaction.exhausted",
+  "dlq.recorded",
+  "external.call.failed",
+  "event.listener.failed",
+  "enqueue.failed",
+]);
+
+/** True when a record represents a failure (for Errors / RCA grouping). */
+export function isFailure(r: TelemetryRecord): boolean {
+  return FAILURE_KINDS.has(r.kind) || r.error != null;
+}
+
+/** Parse a raw SSE payload into a record, or `null` if it isn't one. Never throws. */
+export function parseRecord(data: unknown): TelemetryRecord | null {
+  let obj: unknown = data;
+  if (typeof data === "string") {
+    try {
+      obj = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (obj && typeof obj === "object" && typeof (obj as { kind?: unknown }).kind === "string") {
+    return obj as TelemetryRecord;
+  }
+  return null;
+}
+
+/** Group records by their correlation id (chain). Records without an envelope go under `""`. */
+export function groupByCorrelation(
+  records: readonly TelemetryRecord[],
+): Map<string, TelemetryRecord[]> {
+  const out = new Map<string, TelemetryRecord[]>();
+  for (const r of records) {
+    const cid = r.envelope?.correlationId ?? "";
+    const bucket = out.get(cid);
+    if (bucket) bucket.push(r);
+    else out.set(cid, [r]);
+  }
+  return out;
+}
+
+/** A node in a causation tree — one record + the records it caused. */
+export interface TraceNode {
+  readonly record: TelemetryRecord;
+  readonly children: TraceNode[];
+}
+
+/**
+ * Build causation trees from a flat record list, one tree per chain head.
+ * Links by `envelope`: a record's parent is whichever record's `messageId`
+ * equals this record's `causationId`. A chain head (`causationId === messageId`,
+ * or a parent not present in the set) becomes a root. Records lacking an
+ * envelope are skipped (they have no place in a causal tree).
+ *
+ * Stable: roots + children keep first-seen order. Records that share a
+ * `messageId` (rare — multiple stages of one dispatch) attach to the first.
+ */
+export function buildCorrelationTree(records: readonly TelemetryRecord[]): TraceNode[] {
+  const byMessage = new Map<string, TraceNode>();
+  const ordered: TraceNode[] = [];
+  for (const record of records) {
+    const id = record.envelope?.messageId;
+    if (!id) continue;
+    if (byMessage.has(id)) continue; // first record per messageId owns the node
+    const node: TraceNode = { record, children: [] };
+    byMessage.set(id, node);
+    ordered.push(node);
+  }
+
+  const roots: TraceNode[] = [];
+  for (const node of ordered) {
+    const env = node.record.envelope!;
+    const parentId = env.causationId;
+    const isHead = !parentId || parentId === env.messageId;
+    const parent = isHead ? undefined : byMessage.get(parentId);
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  }
+  return roots;
+}