next-observer 0.0.0-stage → 0.1.1

package/dist/collector/types.d.ts

@@ -0,0 +1,116 @@
+export type AttributeValue = string | number | boolean | null | AttributeValue[] | {
+    [key: string]: AttributeValue;
+};
+export type Attributes = Record<string, AttributeValue>;
+export type SpanKindName = 'unspecified' | 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+export type SpanStatusName = 'unset' | 'ok' | 'error';
+export interface SpanEvent {
+    name: string;
+    timeMs: number;
+    attributes: Attributes;
+}
+/** Storage-independent span shape — every storage adapter and every agent tool speaks this. */
+export interface NormalizedSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    name: string;
+    kind: SpanKindName;
+    service: string;
+    serviceVersion: string | null;
+    scope: string | null;
+    /** Unix epoch, milliseconds (fractional). */
+    startTimeMs: number;
+    durationMs: number;
+    status: SpanStatusName;
+    statusMessage: string | null;
+    attributes: Attributes;
+    resource: Attributes;
+    events: SpanEvent[];
+}
+export interface TraceFilter {
+    service?: string;
+    /** Case-insensitive substring match on any span name in the trace. */
+    operation?: string;
+    /** Minimum duration of the whole trace. */
+    minDurationMs?: number;
+    hasError?: boolean;
+    fromMs?: number;
+    toMs?: number;
+    /** Default 50. */
+    limit?: number;
+}
+export interface TraceSummary {
+    traceId: string;
+    rootName: string;
+    rootService: string;
+    services: string[];
+    startTimeMs: number;
+    durationMs: number;
+    spanCount: number;
+    errorCount: number;
+}
+export interface OperationFilter {
+    service?: string;
+    operation?: string;
+    fromMs?: number;
+    toMs?: number;
+    /** Split stats per service.version — the basis for "which deployment introduced the regression". */
+    byVersion?: boolean;
+    /** Skip Next.js internal spans (see isFrameworkSpan). */
+    hideFramework?: boolean;
+    /** Skip each route's first request in a fresh process (StorageAdapter.isColdStart); counted in `coldStarts`. */
+    hideColdStarts?: boolean;
+}
+export interface OperationStats {
+    service: string;
+    /** Set only when stats were requested with byVersion. */
+    serviceVersion?: string | null;
+    operation: string;
+    count: number;
+    errorCount: number;
+    errorRate: number;
+    avgMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    maxMs: number;
+    /** With hideColdStarts: how many cold-start requests were left out. */
+    coldStarts?: number;
+    /** With hideColdStarts: every request was a cold start, so they are kept — these numbers include compile time. */
+    onlyColdStarts?: boolean;
+}
+export interface SpanFilter {
+    service?: string;
+    /** Case-insensitive substring match on the span name. */
+    operation?: string;
+    status?: SpanStatusName;
+    fromMs?: number;
+    toMs?: number;
+    /** Default 100. */
+    limit?: number;
+    /** Skip Next.js internal spans (see isFrameworkSpan). */
+    hideFramework?: boolean;
+}
+export interface ServiceInfo {
+    name: string;
+    /** In order of first appearance — i.e. deploy order. */
+    versions: string[];
+    spanCount: number;
+    lastSeenMs: number;
+}
+export interface StorageAdapter {
+    insertSpans(spans: NormalizedSpan[]): Promise<void>;
+    queryTraces(filter: TraceFilter): Promise<TraceSummary[]>;
+    getTrace(traceId: string): Promise<NormalizedSpan[]>;
+    getOperationStats(filter: OperationFilter): Promise<OperationStats[]>;
+    /** Most recently received first. */
+    querySpans(filter: SpanFilter): Promise<NormalizedSpan[]>;
+    getServices(): Promise<ServiceInfo[]>;
+    count(): Promise<number>;
+    /**
+     * True for the first server span of a route in a process (resource `service.instance.id`, sent by next-observe): in
+     * `next dev` that request includes compiling the route, so it is not representative latency. False without an id.
+     */
+    isColdStart(span: NormalizedSpan): boolean;
+}

package/dist/collector/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/collector/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/collector/types.ts"],"names":[],"mappings":""}

package/dist/debug/demo.d.ts

@@ -0,0 +1,4 @@
+import type { NormalizedSpan, StorageAdapter } from '../collector/types.js';
+export declare function demoSpans(now?: number): NormalizedSpan[];
+/** Inserts the demo scenario. Old v0 data goes first so deploy order is v0 → v1 → v2. */
+export declare function seedDemo(storage: StorageAdapter, now?: number): Promise<void>;

package/dist/debug/demo.js

@@ -0,0 +1,90 @@
+const MIN = 60_000;
+let seq = 0;
+const id = (length) => (++seq).toString(16).padStart(length, '0');
+function span(traceId, parent, name, startTimeMs, durationMs, extra = {}) {
+    return {
+        traceId,
+        spanId: id(16),
+        parentSpanId: parent?.spanId ?? null,
+        name,
+        kind: parent ? 'internal' : 'server',
+        service: 'shop',
+        serviceVersion: parent?.serviceVersion ?? 'v1',
+        scope: 'test',
+        startTimeMs,
+        durationMs,
+        status: 'unset',
+        statusMessage: null,
+        attributes: {},
+        resource: {},
+        events: [],
+        ...extra,
+    };
+}
+// Like a real Next.js app: the request span (kind server) and Next's own "executing api route" step around user code.
+const nextRequest = { 'next.span_type': 'BaseServer.handleRequest' };
+function nextRoute(t, root, at, durationMs, extra = {}) {
+    const route = String(root.attributes['http.route']);
+    return span(t, root, `executing api route (app) ${route}`, at, durationMs, { ...extra, attributes: { 'next.span_type': 'AppRouteRouteHandlers.runHandler', 'next.route': route } });
+}
+function checkout(version, at, paymentMs) {
+    const t = id(32);
+    const root = span(t, null, 'POST /api/checkout', at, paymentMs + 20, { serviceVersion: version, attributes: { ...nextRequest, 'http.route': '/api/checkout', 'http.status_code': 200 } });
+    const route = nextRoute(t, root, at + 5, paymentMs + 10);
+    return [root, route, span(t, route, 'chargePayment', at + 10, paymentMs, { attributes: { 'code.filepath': 'lib/payment.ts', 'code.function': 'chargePayment' } })];
+}
+function inventory(version, at, fails) {
+    const t = id(32);
+    const root = span(t, null, 'GET /api/inventory/[id]', at, 15, {
+        serviceVersion: version,
+        status: fails ? 'error' : 'unset',
+        attributes: { ...nextRequest, 'http.route': '/api/inventory/[id]', 'http.status_code': fails ? 500 : 200 },
+    });
+    const route = nextRoute(t, root, at + 1, 12, { status: fails ? 'error' : 'unset', statusMessage: fails ? 'Inventory service timeout: upstream not responding' : null });
+    const check = span(t, route, 'inventory.check', at + 2, 10, {
+        status: fails ? 'error' : 'unset',
+        statusMessage: fails ? 'Inventory service timeout: upstream not responding' : null,
+        attributes: { 'code.filepath': 'app/api/inventory/[id]/route.ts' },
+        events: fails ? [{ name: 'exception', timeMs: at + 12, attributes: { 'exception.message': 'Inventory service timeout: upstream not responding' } }] : [],
+    });
+    return [root, route, check];
+}
+function catalog(version, at) {
+    const t = id(32);
+    const root = span(t, null, 'GET /api/products', at, 120, { serviceVersion: version, attributes: { ...nextRequest, 'http.route': '/api/products' } });
+    const route = nextRoute(t, root, at + 1, 118);
+    const ids = span(t, route, 'getProductIds', at + 1, 8);
+    const queries = [0, 1, 2, 3, 4].map((i) => span(t, route, 'db.query', at + 10 + i * 20, 18, { attributes: { 'db.statement': 'SELECT * FROM products WHERE id = ?' } }));
+    return [root, route, ids, ...queries];
+}
+const PAYMENT_V1 = [160, 180, 200, 240, 260, 300];
+const PAYMENT_V2 = [1400, 1450, 1600, 2100, 2380, 2490];
+export function demoSpans(now = Date.now()) {
+    seq = 0;
+    const spans = [];
+    // v1: 12–8 minutes ago
+    for (let i = 0; i < 30; i++) {
+        const at = now - 12 * MIN + i * 8_000;
+        spans.push(...checkout('v1', at, PAYMENT_V1[i % PAYMENT_V1.length]));
+        spans.push(...inventory('v1', at + 1000, i % 10 < 3));
+        if (i % 5 === 0)
+            spans.push(...catalog('v1', at + 2000));
+    }
+    // v2: 5–1 minutes ago (fresh enough not to look like a silent service)
+    for (let i = 0; i < 30; i++) {
+        const at = now - 5 * MIN + i * 8_000;
+        spans.push(...checkout('v2', at, PAYMENT_V2[i % PAYMENT_V2.length]));
+        spans.push(...inventory('v2', at + 1000, i % 10 < 3));
+        if (i % 5 === 0)
+            spans.push(...catalog('v2', at + 2000));
+    }
+    // Old data outside the default 15-minute window (seedDemo inserts these 3 spans first).
+    spans.push(...checkout('v0', now - 40 * MIN, 50));
+    return spans;
+}
+/** Inserts the demo scenario. Old v0 data goes first so deploy order is v0 → v1 → v2. */
+export async function seedDemo(storage, now = Date.now()) {
+    const spans = demoSpans(now);
+    await storage.insertSpans([...spans.slice(-3), ...spans.slice(0, -3)]);
+}
+//# sourceMappingURL=demo.js.map

package/dist/debug/demo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../src/debug/demo.ts"],"names":[],"mappings":"AAIA,MAAM,GAAG,GAAG,MAAM,CAAA;AAElB,IAAI,GAAG,GAAG,CAAC,CAAA;AACX,MAAM,EAAE,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEzE,SAAS,IAAI,CAAC,OAAe,EAAE,MAA6B,EAAE,IAAY,EAAE,WAAmB,EAAE,UAAkB,EAAE,KAAK,GAA4B,EAAE;IACtJ,OAAO;QACL,OAAO;QACP,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;QACd,YAAY,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI;QACpC,IAAI;QACJ,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;QACpC,OAAO,EAAE,MAAM;QACf,cAAc,EAAE,MAAM,EAAE,cAAc,IAAI,IAAI;QAC9C,KAAK,EAAE,MAAM;QACb,WAAW;QACX,UAAU;QACV,MAAM,EAAE,OAAO;QACf,aAAa,EAAE,IAAI;QACnB,UAAU,EAAE,EAAE;QACd,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,EAAE;QACV,GAAG,KAAK;KACT,CAAA;AACH,CAAC;AAED,sHAAsH;AACtH,MAAM,WAAW,GAAG,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,CAAA;AACpE,SAAS,SAAS,CAAC,CAAS,EAAE,IAAoB,EAAE,EAAU,EAAE,UAAkB,EAAE,KAAK,GAA4B,EAAE;IACrH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAA;IACnD,OAAO,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,6BAA6B,KAAK,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,EAAE,gBAAgB,EAAE,kCAAkC,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,CAAC,CAAA;AACrL,CAAC;AAED,SAAS,QAAQ,CAAC,OAAe,EAAE,EAAU,EAAE,SAAiB;IAC9D,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAChB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,EAAE,SAAS,GAAG,EAAE,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,GAAG,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,GAAG,EAAE,EAAE,CAAC,CAAA;IACzL,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC,CAAA;IACxD,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,EAAE,CAAC,CAAC,CAAA;AACpK,CAAC;AAED,SAAS,SAAS,CAAC,OAAe,EAAE,EAAU,EAAE,KAAc;IAC5D,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAChB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,yBAAyB,EAAE,EAAE,EAAE,EAAE,EAAE;QAC5D,cAAc,EAAE,OAAO;QACvB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;QACjC,UAAU,EAAE,EAAE,GAAG,WAAW,EAAE,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE;KAC3G,CAAC,CAAA;IACF,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,oDAAoD,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IACvK,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE;QAC1D,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;QACjC,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,oDAAoD,CAAC,CAAC,CAAC,IAAI;QAClF,UAAU,EAAE,EAAE,eAAe,EAAE,iCAAiC,EAAE;QAClE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,EAAE,mBAAmB,EAAE,oDAAoD,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;KACzJ,CAAC,CAAA;IACF,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;AAC7B,CAAC;AAED,SAAS,OAAO,CAAC,OAAe,EAAE,EAAU;IAC1C,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAChB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,GAAG,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,EAAE,CAAC,CAAA;IACpJ,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,MAAM,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,qCAAqC,EAAE,EAAE,CAAC,CAAC,CAAA;IACvK,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AACjD,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAEvD,MAAM,UAAU,SAAS,CAAC,GAAG,GAAW,IAAI,CAAC,GAAG,EAAE;IAChD,GAAG,GAAG,CAAC,CAAA;IACP,MAAM,KAAK,GAAqB,EAAE,CAAA;IAClC,uBAAuB;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC,GAAG,KAAK,CAAA;QACrC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QACpE,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;QACrD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,CAAA;IAC1D,CAAC;IACD,uEAAuE;IACvE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,KAAK,CAAA;QACpC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QACpE,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;QACrD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,CAAA;IAC1D,CAAC;IACD,wFAAwF;IACxF,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC,CAAC,CAAA;IACjD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAuB,EAAE,GAAG,GAAW,IAAI,CAAC,GAAG,EAAE;IAC9E,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IAC5B,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACxE,CAAC"}

package/dist/debug/detector.d.ts

@@ -0,0 +1,61 @@
+import type { NormalizedSpan } from '../collector/types.js';
+export type AnomalyType = 'high_error_rate' | 'high_latency' | 'no_traffic';
+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, or seconds of silence. */
+    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;
+    }[];
+}
+export interface DetectorOptions {
+    windowMs?: 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;
+}
+export declare class AnomalyDetector {
+    readonly options: Required<Omit<DetectorOptions, 'now'>>;
+    private readonly now;
+    private window;
+    private lastSeenMs;
+    /** Cooldown per type (app-wide) or per type + operation. */
+    private readonly lastReportedMs;
+    private seq;
+    constructor(options?: DetectorOptions);
+    /** Feed spans as they are ingested. */
+    observe(spans: NormalizedSpan[]): void;
+    /** Evaluate the window now; returns new anomalies (respecting cooldowns). */
+    check(): Anomaly[];
+    private anomaly;
+}
+/** 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;

package/dist/debug/detector.js

@@ -0,0 +1,116 @@
+const DEFAULTS = { windowMs: 10_000, errorRate: 0.2, slowMs: 1000, slowRate: 0.3, noTrafficMs: 120_000, minSamples: 5, cooldownMs: 300_000 };
+// Only server entry spans count: Next emits ~7 internal spans per request, which would dilute a 30% error rate below
+// any threshold. Browser and internal spans are ignored.
+const isServerRequest = (s) => s.kind === 'server';
+export class AnomalyDetector {
+    options;
+    now;
+    window = [];
+    lastSeenMs = null;
+    /** Cooldown per type (app-wide) or per type + operation. */
+    lastReportedMs = new Map();
+    seq = 0;
+    constructor(options = {}) {
+        const { now, ...rest } = options;
+        this.options = { ...DEFAULTS, ...rest };
+        this.now = now ?? Date.now;
+    }
+    /** Feed spans as they are ingested. */
+    observe(spans) {
+        const atMs = this.now();
+        if (spans.length > 0)
+            this.lastSeenMs = atMs;
+        for (const span of spans)
+            if (isServerRequest(span))
+                this.window.push({ atMs, span });
+    }
+    /** Evaluate the window now; returns new anomalies (respecting cooldowns). */
+    check() {
+        const now = this.now();
+        const o = this.options;
+        this.window = this.window.filter((w) => now - w.atMs <= o.windowMs);
+        const requests = this.window.map((w) => w.span);
+        const found = [];
+        const judge = (list, subject) => {
+            if (list.length < o.minSamples)
+                return;
+            const errorRate = list.filter((s) => s.status === 'error').length / list.length;
+            const slowRate = list.filter((s) => s.durationMs > o.slowMs).length / list.length;
+            // An operation-level anomaly would only repeat an app-wide one of the same type.
+            const covered = (type) => subject && found.some((a) => a.type === type && a.scope === 'all');
+            if (errorRate > o.errorRate && !covered('high_error_rate')) {
+                found.push(this.anomaly('high_error_rate', errorRate, o.errorRate, list, now, errorRate >= 2 * o.errorRate, subject));
+            }
+            if (slowRate > o.slowRate && !covered('high_latency')) {
+                found.push(this.anomaly('high_latency', slowRate, o.slowRate, list, now, slowRate >= 2 * o.slowRate, subject));
+            }
+        };
+        judge(requests);
+        // Per operation: on a realistic route mix one broken endpoint (30% errors) is only ~10% of all requests —
+        // below the app-wide threshold, yet clearly an incident.
+        const byOperation = new Map();
+        for (const s of requests) {
+            const key = `${s.service}\u0000${s.name}`;
+            byOperation.set(key, [...(byOperation.get(key) ?? []), s]);
+        }
+        for (const list of byOperation.values())
+            judge(list, { service: list[0].service, operation: list[0].name });
+        if (this.lastSeenMs !== null && now - this.lastSeenMs > o.noTrafficMs) {
+            found.push(this.anomaly('no_traffic', Math.round((now - this.lastSeenMs) / 1000), o.noTrafficMs / 1000, [], now, true));
+        }
+        return found.filter((a) => {
+            const key = a.subject ? `${a.type}\u0000${a.subject.service}\u0000${a.subject.operation}` : a.type;
+            const last = this.lastReportedMs.get(key);
+            if (last !== undefined && now - last < o.cooldownMs)
+                return false;
+            this.lastReportedMs.set(key, now);
+            return true;
+        });
+    }
+    anomaly(type, value, threshold, requests, now, critical, subject) {
+        const byOperation = new Map();
+        for (const s of requests) {
+            const key = `${s.service}\u0000${s.name}`;
+            const entry = byOperation.get(key) ?? { service: s.service, operation: s.name, count: 0, errors: 0, slow: 0 };
+            entry.count++;
+            if (s.status === 'error')
+                entry.errors++;
+            if (s.durationMs > this.options.slowMs)
+                entry.slow++;
+            byOperation.set(key, entry);
+        }
+        const culprit = (e) => (type === 'high_error_rate' ? e.errors : e.slow);
+        const operations = [...byOperation.values()]
+            .filter((e) => type === 'no_traffic' || culprit(e) > 0)
+            .sort((a, b) => culprit(b) - culprit(a))
+            .slice(0, 3);
+        return {
+            id: `${type}-${now}-${++this.seq}`,
+            type,
+            scope: subject ? 'operation' : 'all',
+            ...(subject ? { subject } : {}),
+            severity: critical ? 'critical' : 'warning',
+            detectedAtMs: now,
+            value: Math.round(value * 1000) / 1000,
+            threshold,
+            sampleSize: requests.length,
+            windowMs: this.options.windowMs,
+            operations,
+        };
+    }
+}
+/** The question the agents get when an anomaly fires — carries the evidence so they know where to start. */
+export function questionFor(anomaly) {
+    const ops = anomaly.operations.map((o) => `${o.operation} (${o.service}: ${o.errors} errors, ${o.slow} slow of ${o.count})`).join('; ');
+    const seconds = Math.round(anomaly.windowMs / 1000);
+    const what = anomaly.subject ? `${anomaly.subject.operation} requests` : 'server requests';
+    switch (anomaly.type) {
+        case 'high_error_rate':
+            return `Anomaly detected: ${Math.round(anomaly.value * 100)}% of ${what} failed in the last ${seconds}s (${anomaly.sampleSize} requests). Most affected: ${ops}. Find the failing operation, the exact error and its source.`;
+        case 'high_latency':
+            return `Anomaly detected: ${Math.round(anomaly.value * 100)}% of ${what} were slower than threshold in the last ${seconds}s (${anomaly.sampleSize} requests). Most affected: ${ops}. Find what is slow and which deployment introduced it.`;
+        case 'no_traffic':
+            return `Anomaly detected: no spans received for ${anomaly.value}s after traffic was flowing. Check which services went silent.`;
+    }
+}
+//# sourceMappingURL=detector.js.map

package/dist/debug/detector.js.map

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

package/dist/debug/index.d.ts

@@ -0,0 +1,3 @@
+export { createAgentQueries, type AgentQueries, type QueryOptions, type TraceRow } from './queries.js';
+export { demoSpans, seedDemo } from './demo.js';
+export { AnomalyDetector, questionFor, type Anomaly, type AnomalyType, type DetectorOptions } from './detector.js';

package/dist/debug/index.js

@@ -0,0 +1,5 @@
+// Agent building blocks. No LLM framework is imported here — ADK wiring comes on top.
+export { createAgentQueries } from './queries.js';
+export { demoSpans, seedDemo } from './demo.js';
+export { AnomalyDetector, questionFor } from './detector.js';
+//# sourceMappingURL=index.js.map

package/dist/debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/debug/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAAE,kBAAkB,EAAuD,MAAM,cAAc,CAAA;AACtG,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAwD,MAAM,eAAe,CAAA"}

package/dist/debug/queries.d.ts

@@ -0,0 +1,207 @@
+import type { StorageAdapter } from '../collector/types.js';
+export interface QueryOptions {
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+interface Window {
+    /** Look back this many minutes. Default 15. */
+    sinceMinutes?: number;
+}
+export interface TraceRow {
+    depth: number;
+    name: string;
+    service: string;
+    durationMs: number;
+    /** Duration minus direct children — where the time was actually spent. */
+    selfMs: number;
+    /** First request of this route after a server start — in next dev its time includes compiling the route. */
+    coldStart?: boolean;
+    /** Self time of hidden Next.js internal spans under this one (routing, rendering, dev compilation) — not user code. */
+    nextInternalMs?: number;
+    error?: string;
+    attributes?: Record<string, unknown>;
+}
+export declare function createAgentQueries(storage: StorageAdapter, options?: QueryOptions): {
+    /** Services, their deployed versions and how fresh their data is. */
+    getServices(): Promise<{
+        services: {
+            name: string;
+            versions: string[];
+            spans: number;
+            lastSpanSecondsAgo: number;
+        }[];
+    }>;
+    /** Slowest operations by p95 with error rates. */
+    getOperationStats(args?: {
+        service?: string;
+        operation?: string;
+        limit?: number;
+    } & Window): Promise<{
+        note: string;
+        operations: {
+            service: string;
+            operation: string;
+            count: number;
+            errorRate: number;
+            p50Ms: number;
+            p95Ms: number;
+            p99Ms: number;
+            onlyColdStarts?: boolean | undefined;
+        }[];
+    } | {
+        note?: undefined;
+        operations: {
+            service: string;
+            operation: string;
+            count: number;
+            errorRate: number;
+            p50Ms: number;
+            p95Ms: number;
+            p99Ms: number;
+            onlyColdStarts?: boolean | undefined;
+        }[];
+    }>;
+    /**
+     * Latest deployed version vs the one before it, per operation (versions ordered by first appearance = deploy order).
+     * Biggest p95 increase first — the answer to "which deployment introduced the regression".
+     */
+    compareVersions(args?: {
+        service?: string;
+        operation?: string;
+    } & Window): Promise<{
+        note: string;
+        changes: {
+            service: string;
+            operation: string;
+            from: {
+                version: string;
+                count: number;
+                p50Ms: number;
+                p95Ms: number;
+                errorRate: number;
+                onlyColdStarts?: boolean | undefined;
+            };
+            to: {
+                version: string;
+                count: number;
+                p50Ms: number;
+                p95Ms: number;
+                errorRate: number;
+                onlyColdStarts?: boolean | undefined;
+            };
+            p95Ratio: number | null;
+            errorRateDelta: number;
+        }[];
+    } | {
+        note?: undefined;
+        changes: {
+            service: string;
+            operation: string;
+            from: {
+                version: string;
+                count: number;
+                p50Ms: number;
+                p95Ms: number;
+                errorRate: number;
+                onlyColdStarts?: boolean | undefined;
+            };
+            to: {
+                version: string;
+                count: number;
+                p50Ms: number;
+                p95Ms: number;
+                errorRate: number;
+                onlyColdStarts?: boolean | undefined;
+            };
+            p95Ratio: number | null;
+            errorRateDelta: number;
+        }[];
+    }>;
+    /** Failing operations: error rate, most common exception messages and example traces. */
+    getErrors(args?: {
+        service?: string;
+        operation?: string;
+        limit?: number;
+    } & Window): Promise<{
+        note: string;
+        errors: {
+            service: string;
+            operation: string;
+            errors: number;
+            errorRate: number | null;
+            topMessages: {
+                message: string;
+                count: number;
+            }[];
+            exampleTraceIds: string[];
+        }[];
+    } | {
+        note?: undefined;
+        errors: {
+            service: string;
+            operation: string;
+            errors: number;
+            errorRate: number | null;
+            topMessages: {
+                message: string;
+                count: number;
+            }[];
+            exampleTraceIds: string[];
+        }[];
+    }>;
+    /** Recent traces matching filters — to get example trace ids. */
+    searchTraces(args?: {
+        service?: string;
+        operation?: string;
+        minDurationMs?: number;
+        hasError?: boolean;
+        limit?: number;
+    } & Window): Promise<{
+        note: string;
+        traces: {
+            traceId: string;
+            root: string;
+            services: string[];
+            durationMs: number;
+            spans: number;
+            errors: number;
+            secondsAgo: number;
+        }[];
+    } | {
+        note?: undefined;
+        traces: {
+            traceId: string;
+            root: string;
+            services: string[];
+            durationMs: number;
+            spans: number;
+            errors: number;
+            secondsAgo: number;
+        }[];
+    }>;
+    /**
+     * One trace as a compact tree: depth, duration, self time (duration minus children), errors and code location.
+     * `repeated` flags ≥3 same-named siblings — the N+1 signature.
+     */
+    getTrace(args: {
+        traceId: string;
+        maxSpans?: number;
+    }): Promise<{
+        note: string;
+        spans: never[];
+        repeated: never[];
+    } | {
+        traceId: string;
+        note?: string | undefined;
+        nextInternalSpansHidden?: number | undefined;
+        spans: TraceRow[];
+        repeated: {
+            parent: string;
+            operation: string;
+            count: number;
+            totalMs: number;
+        }[];
+    }>;
+};
+export type AgentQueries = ReturnType<typeof createAgentQueries>;
+export {};