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; /** A verified wrong-data response (incident F) — distinct from `error`: status was fine, duration was fine, the * data inside was not what was asked for. Only an app that instruments its own identity check can ever report this. */ integrityCheck?: { expected: unknown; actual: unknown; }; attributes?: Record; } 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[]; versionLastSpanSecondsAgo: { [k: string]: number; }; 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; /** false skips the scan for the app's own checks — for callers that only want `changes`. */ integrity?: boolean; } & 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; errorRateChangeSignificant: boolean; }[]; integrity?: { service: string; operation: string; versions: { checked: number; failed: number; version: string; }[]; }[] | undefined; } | { 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; errorRateChangeSignificant: boolean; }[]; integrity?: { service: string; operation: string; versions: { checked: number; failed: number; version: string; }[]; }[] | undefined; }>; /** 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: { firstSeenMinutesAgo: number; firstSeenVersion?: string | undefined; seenInVersions?: string[] | undefined; message: string; count: number; }[]; exampleTraceIds: string[]; }[]; } | { note?: undefined; errors: { service: string; operation: string; errors: number; errorRate: number | null; topMessages: { firstSeenMinutesAgo: number; firstSeenVersion?: string | undefined; seenInVersions?: string[] | undefined; 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; export {};