import type { NormalizedSpan, SpanEvent } from '../collector/types.js'; export type AnomalyType = 'high_error_rate' | 'high_latency' | 'no_traffic' | 'data_integrity' | 'check_failed'; export interface Anomaly { id: string; type: AnomalyType; /** 'all' = share of all server requests; 'operation' = one operation failing/slow on its own (see `subject`). */ scope: 'all' | 'operation'; subject?: { service: string; operation: string; }; severity: 'warning' | 'critical'; detectedAtMs: number; /** What was measured: error share, slow share, seconds of silence, or (data_integrity) a raw failure count. */ value: number; threshold: number; /** Server requests in the window the value is based on (0 for no_traffic). */ sampleSize: number; windowMs: number; /** Operations behind the anomaly, worst first. */ operations: { service: string; operation: string; count: number; errors: number; slow: number; }[]; /** * `data_integrity` only: the specific checks that failed, each one evidence a latency/error-rate chart can never * show — the response came back fast, with a 2xx, and still was not the one that was asked for. */ integrityFailures?: { service: string; operation: string; traceId: string; expected: unknown; actual: unknown; }[]; /** * `check_failed` only (raised by checks/watch.ts, not by this detector): the scheduled check that keeps failing. * `value` is then the failures in a row (`rule: 'in_row'`) or the failures among the latest `sampleSize` runs (`'share'`). */ check?: { name: string; method: string; url: string; rule: 'in_row' | 'share'; reason: string; status?: number; unreachable?: true; traceId: string; /** Set when other checks get no connection to the same address either: the app is down, not one route. */ origin?: string; alsoUnreachable?: string[]; }; } export interface DetectorOptions { /** Window for the app-wide rule. */ windowMs?: number; /** * Window for the per-operation rule. Longer than the app-wide one: an operation is a fraction of the traffic, and in * 10 s a checkout at ~0.6 requests/s gets 3–5 samples — under minSamples, so a ×7 slowdown went unnoticed. */ operationWindowMs?: number; /** Error share of server requests in the window. */ errorRate?: number; /** A request slower than this counts as slow. */ slowMs?: number; /** Slow share of server requests in the window. */ slowRate?: number; /** Silence after traffic was seen. */ noTrafficMs?: number; /** Below this many server requests in the window, rates are not judged. */ minSamples?: number; /** The same anomaly type is not reported again within this time. */ cooldownMs?: number; now?: () => number; } /** * A span whose own status/duration are both unremarkable — fast, 2xx — can still carry proof that the data inside it * was wrong: code that verified "did I get back what I asked for" records that verdict as this event, independent of * whether the span threw. See docs/APM_FINDINGS.md, incident F: a connection pooler in transaction-pooling mode can * return another concurrent query's result instead of erroring or hanging — nothing about status or latency shows it. */ export declare const INTEGRITY_CHECK_EVENT = "integrity_check"; /** Exported so agent tools (debug/queries.ts: getTrace) can show the same evidence the detector acted on — an * anomaly whose question names a trace id is only as trustworthy as the agent's own ability to go look at it. */ export declare function integrityFailureEvent(s: NormalizedSpan): SpanEvent | undefined; export declare class AnomalyDetector { readonly options: Required>; private readonly now; private window; private lastSeenMs; /** Cooldown per type (app-wide) or per type + operation. */ private readonly lastReportedMs; /** Reported anomalies within the cooldown — to skip ones that only repeat them at the other scope. */ private reported; private seq; constructor(options?: DetectorOptions); /** * Feed spans as they are ingested. Kept beyond server-entry spans: any span carrying a failed `integrity_check` * event, since that check naturally lives on the call that did the verifying (e.g. a `db.query` child span) — * dropping non-server spans here would make the data_integrity rule below unable to ever see its own evidence. */ observe(spans: NormalizedSpan[]): void; /** Evaluate the window now; returns new anomalies (respecting cooldowns). */ check(): Anomaly[]; /** * The same problem seen at the other scope, in another check: one failing endpoint first trips its operation rule * (30 s window), seconds later the app-wide one (10 s) — two investigations of one problem. An app-wide anomaly is * explained when every culprit operation already had its own anomaly of that type; an operation anomaly when a recent * app-wide one already named it. An app-wide anomaly with a culprit nobody reported yet still says something new. */ private alreadyExplained; private anomaly; /** * `bad` are spans whose own status/duration passed every other rule and still carry proof they returned the wrong * data (see `integrityFailureEvent`) — always `critical`, there is no "warning" tier for a response that lied. */ private integrityAnomaly; } /** The question the agents get when an anomaly fires — carries the evidence so they know where to start. */ export declare function questionFor(anomaly: Anomaly): string;