autotel-devtools 22.0.0 → 23.0.0

package/dist/exporter-BrEcnzoT.d.ts

@@ -0,0 +1,546 @@
+import { c as QueryError, r as SignalSchema } from "./compile-JDFHUCo5.js";
+import { n as SpanAttributes } from "./types-DHDvZnnn.js";
+import { i as LogData, n as ErrorGroup, o as TraceData, t as DevtoolsData } from "./types-DM8y4A9Z.js";
+import { Server } from "node:http";
+import { AgentRawEvent, OtelMetricRecord } from "autotel-agents";
+import { ExportResult } from "@opentelemetry/core";
+import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+//#region src/server/metric-streams.d.ts
+type MetricKind = 'gauge' | 'sum' | 'histogram' | 'exponentialHistogram' | 'summary';
+type MetricTemporality = 'delta' | 'cumulative';
+/** A data point's link back to the trace that produced it. */
+interface MetricExemplar {
+  value: number;
+  timestamp: number;
+  traceId?: string;
+  spanId?: string;
+}
+interface ExponentialBuckets {
+  offset: number;
+  bucketCounts: number[];
+}
+interface MetricPoint {
+  timestamp: number;
+  startTimestamp?: number;
+  attributes: SpanAttributes;
+  /** Gauge and sum. */
+  value?: number;
+  /** Histogram and summary. */
+  count?: number;
+  sum?: number;
+  min?: number;
+  max?: number;
+  /** Histogram: one longer than `explicitBounds` — the last is +Inf. */
+  bucketCounts?: number[];
+  explicitBounds?: number[];
+  /** Exponential histogram fields, preserved without lossy rebucketing. */
+  scale?: number;
+  zeroCount?: number;
+  zeroThreshold?: number;
+  positive?: ExponentialBuckets;
+  negative?: ExponentialBuckets;
+  /** Summary: precomputed quantiles. */
+  quantiles?: Array<{
+    quantile: number;
+    value: number;
+  }>;
+  exemplars?: MetricExemplar[];
+}
+interface MetricStreamRecord {
+  name: string;
+  unit?: string;
+  description?: string;
+  kind: MetricKind;
+  temporality?: MetricTemporality;
+  /** Sums only. A non-monotonic sum is an up/down counter, not a rate. */
+  monotonic?: boolean;
+  service: string;
+  scope?: {
+    name: string;
+    version?: string;
+  };
+  resource: SpanAttributes;
+  points: MetricPoint[];
+}
+//#endregion
+//#region src/server/store/store.d.ts
+interface TimeWindow {
+  /** Epoch ms, inclusive. */
+  start: number;
+  /** Epoch ms, inclusive. */
+  end: number;
+}
+interface DevtoolsStoreOptions {
+  /** File path. Omit for an in-memory database (nothing persists). */
+  path?: string;
+  /** Maximum traces retained; the oldest are pruned past this. */
+  maxTraces?: number;
+  /**
+   * Maximum metric points retained **per series**, not in total.
+   *
+   * Per-series is the point: a global cap lets one chatty instrument evict
+   * every other series, so the quiet metric you were actually watching goes
+   * blank while a noisy one fills the buffer.
+   */
+  maxMetricPoints?: number;
+  /** Maximum logs retained; the oldest are pruned past this. */
+  maxLogs?: number;
+  /** Logical sqlite size cap. Defaults to 512 MiB in memory or 2 GiB on disk. */
+  maxBytes?: number;
+}
+interface StoreStats {
+  bytesUsed: number;
+  maxBytes: number;
+  traceCount: number;
+  spanCount: number;
+  logCount: number;
+  metricSeriesCount: number;
+  metricPointCount: number;
+}
+interface TraceProjection {
+  traceId: string;
+  serviceName: string;
+  durationMs: number;
+  statusCode: 'OK' | 'ERROR' | 'UNSET';
+  spanCount: number;
+  errorSpanCount: number;
+  serviceCount: number;
+  llmSpanCount: number;
+  totalTokens: number;
+  modelsUsed: string[];
+  topOperations: Array<{
+    operation: string;
+    count: number;
+  }>;
+  slowestSpans: Array<{
+    spanId: string;
+    name: string;
+    service: string;
+    durationMs: number;
+    /** Selects this span, not just the trace containing it. */
+    deepLink: string;
+  }>;
+  deepLink: string;
+}
+interface QueryTracesArgs {
+  query: string;
+  window?: TimeWindow;
+  limit?: number;
+  /** Opaque keyset cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+}
+interface QueryTracesResult {
+  traces: TraceData[];
+  /** Cursor for the next page, or null when this is the last one. */
+  nextCursor: string | null;
+  /** Present only when the query text failed to parse. */
+  errors?: QueryError[];
+}
+/** One chart line, with the points to draw it. */
+interface MetricSeries {
+  seriesId: string;
+  name: string;
+  unit?: string;
+  description?: string;
+  kind: MetricKind;
+  temporality?: MetricTemporality;
+  monotonic?: boolean;
+  service: string;
+  scope?: {
+    name: string;
+    version?: string;
+  };
+  /** Full resource identity (host, pod, process, deployment, and service). */
+  resource: SpanAttributes;
+  /** The attributes that distinguish this series from its siblings. */
+  attributes: SpanAttributes;
+  points: MetricPoint[];
+}
+/** A row in the metric catalogue. */
+interface MetricCatalogEntry {
+  name: string;
+  kind: MetricKind;
+  unit?: string;
+  description?: string;
+  seriesCount: number;
+}
+interface QueryMetricSeriesArgs {
+  name: string;
+  window?: TimeWindow;
+  /** Maximum points returned per series after server-side reduction. */
+  maxPoints?: number;
+}
+interface QueryLogsArgs {
+  query: string;
+  window?: TimeWindow;
+  limit?: number;
+  cursor?: string;
+}
+interface QueryLogsResult {
+  logs: LogData[];
+  nextCursor: string | null;
+  errors?: QueryError[];
+}
+declare const SPAN_SCHEMA: SignalSchema;
+declare class DevtoolsStore {
+  private readonly db;
+  private readonly maxTraces;
+  private readonly maxMetricPoints;
+  private readonly maxLogs;
+  private readonly maxBytes;
+  constructor(options?: DevtoolsStoreOptions);
+  /** Refuse a file this build cannot read, before any query touches it. */
+  private guardSchemaVersion;
+  /** Upgrade databases created before span identity included the trace id. */
+  private migrateSpanIdentity;
+  /** Add lossless metric fields to databases created by earlier releases. */
+  private migrateMetricFidelity;
+  private hasColumn;
+  private addColumnIfMissing;
+  private migrateLegacyMetricSeriesIdentity;
+  /**
+   * SQLite parses `REGEXP` but ships no implementation — using it without
+   * registering one is a runtime error, not a syntax error. The language offers
+   * regex matching, so the function has to exist.
+   *
+   * An invalid pattern matches nothing rather than throwing: the user is
+   * probably mid-typing, and a thrown error would blank the whole result list.
+   */
+  private registerRegexp;
+  ingestTraces(traces: TraceData[]): void;
+  /**
+   * Find traces matching a query.
+   *
+   * The filter runs against *spans* and the results are traces: a trace matches
+   * when any of its spans does. That is what makes `http.status_code = 500`
+   * useful — the attribute is on one span, but the thing you want to open is
+   * the trace containing it.
+   */
+  queryTraces(args: QueryTracesArgs): QueryTracesResult;
+  ingestLogs(logs: LogData[]): void;
+  queryLogs(args: QueryLogsArgs): QueryLogsResult;
+  countLogs(): number;
+  /**
+   * Store metric points, grouped into series.
+   *
+   * One series is one chart line: `(name, kind, unit, service, scope, point
+   * attributes)`. Both directions of getting this wrong are bad — too coarse
+   * and every line collapses into one meaningless average, too fine and one
+   * logical series sprouts a new line on every export — so the identity is a
+   * content hash over exactly those fields, with attribute keys sorted so an
+   * exporter's key ordering cannot split a series in two.
+   */
+  ingestMetrics(streams: MetricStreamRecord[]): void;
+  /** Every metric name held, for the catalogue the Metrics tab lists. */
+  listMetricNames(): MetricCatalogEntry[];
+  queryMetricCatalog(query: string): {
+    metrics: MetricCatalogEntry[];
+    errors?: QueryError[];
+  };
+  /**
+   * The series for one metric, with their points.
+   *
+   * A series whose points all fall outside the window is omitted rather than
+   * returned empty: an empty line in the legend claims data exists where none
+   * does, and the caller cannot tell the two apart.
+   */
+  queryMetricSeries(args: QueryMetricSeriesArgs): MetricSeries[];
+  getTrace(traceId: string): TraceData | null;
+  describeTrace(traceId: string): TraceProjection | null;
+  findSlowest(limit?: number): TraceProjection[];
+  countSpans(): number;
+  countTraces(): number;
+  /**
+   * One row per matching span, for a cohort comparison.
+   *
+   * Attributes plus the first-class columns, because "the slow ones are all
+   * `service=payments`" is exactly the shape of answer wanted and `service` is
+   * a column rather than an attribute. Ids are left out: they take a distinct
+   * value per span, so they can never describe a group, and including them
+   * only gives the ranking noise to wade through.
+   *
+   * Throws on a query that does not parse. Returning an empty cohort instead
+   * would surface as "no difference found", which is a different and much
+   * more misleading answer than "your query is wrong".
+   */
+  cohortRows(args: QueryTracesArgs): Array<Record<string, unknown>>;
+  /**
+   * What the store has actually seen, for the coverage join.
+   *
+   * Both routes in are counted: the `http.route` attribute a framework
+   * integration sets, and the span name, which is what `trace('name', fn)`
+   * produces and is all a non-HTTP entry point ever has. Counting is cheap
+   * here because `attribute_values` already carries per-value totals.
+   */
+  observedSpans(): {
+    routeCounts: Record<string, number>;
+    spanNameCounts: Record<string, number>;
+  };
+  /** Query fields currently present, for editor completion. */
+  listQueryFields(signal: 'traces' | 'logs', limit?: number): string[];
+  searchAttributes(signal: 'traces' | 'logs', value: string, limit?: number): Array<{
+    key: string;
+    value: unknown;
+    count: number;
+  }>;
+  private attributeUpsert;
+  private attributeOccurrenceUpsert;
+  private indexAttributes;
+  /**
+   * Index the events and links already sitting in the span JSON.
+   *
+   * A `--db` file written before these tables existed holds spans whose events
+   * no query can reach. Reading them out of the JSON on open is what makes
+   * `event.name = …` work against telemetry captured yesterday. Keyed on the
+   * table being empty while spans exist, so it runs once rather than on every
+   * open.
+   */
+  private backfillSpanChildren;
+  private backfillAttributeDictionary;
+  /**
+   * Prune the oldest traces past the row cap, and their spans with them.
+   *
+   * Spans are deleted in the same transaction as their traces: a pruned trace
+   * that left its spans behind would leave rows that no query can reach and no
+   * later sweep would find, since every sweep starts from `traces`.
+   */
+  enforceRetention(): void;
+  getStats(): StoreStats;
+  private enforceByteRetention;
+  /**
+   * Trim each series to its newest `maxMetricPoints`.
+   *
+   * Per series, not globally: a global cap would let one chatty instrument
+   * evict every other series, blanking the quiet chart someone was watching.
+   */
+  private enforceMetricRetention;
+  /** Trim the log table to its newest `maxLogs` rows. */
+  private enforceLogRetention;
+  private removeOrphanedAttributes;
+  clear(): void;
+  clearSignal(signal: 'traces' | 'logs' | 'metrics'): void;
+  deleteMetric(name: string): number;
+  deleteTraces(traceIds: string[]): number;
+  close(): void;
+  /**
+   * Hydrate a page of traces with one span query rather than one per trace.
+   *
+   * A list of 100 traces was 101 statements: the page, then a `SELECT` per
+   * trace. Grouping in memory costs the same rows and one round of planning.
+   * Ordering is `trace_id, start_time` so each group arrives already in the
+   * order a waterfall draws it, which is what the list-hydration test pins.
+   */
+  private hydrateTracePage;
+  private hydrateTrace;
+  /** The row-to-trace mapping, shared by the single and batched paths. */
+  private assembleTrace;
+}
+//#endregion
+//#region src/server/server.d.ts
+interface DevtoolsServerOptions {
+  port?: number;
+  server?: Server;
+  path?: string;
+  verbose?: boolean;
+  maxHistory?: number;
+  maxTraceCount?: number;
+  maxLogCount?: number;
+  maxMetricCount?: number;
+  /**
+   * Bind host, used only to decide the WebSocket origin policy. A loopback host
+   * (the default) enables the DNS-rebinding `Host` check on the live stream; an
+   * explicit non-loopback bind opts out, leaving just the cross-origin check.
+   */
+  host?: string;
+  /**
+   * Called after each ingest, with the incremental data just broadcast to WS
+   * clients. Lets an embedder (e.g. the VS Code extension) react to new
+   * telemetry — refresh its own tree views — while the server owns the buffer.
+   */
+  onData?: (incremental: DevtoolsData) => void;
+  /**
+   * Path to the sqlite database backing the store. Omit for in-memory, which
+   * is the default so existing embedders keep their previous behaviour: they
+   * get querying and paging, but nothing is written to disk unless asked for.
+   */
+  dbPath?: string;
+  /** Maximum traces retained in the store before the oldest are pruned. */
+  maxTraces?: number;
+  /** Maximum logs retained in the store before the oldest are pruned. */
+  maxLogs?: number;
+  /** Maximum logical sqlite size before oldest telemetry is pruned. */
+  maxDbBytes?: number;
+  /**
+   * How often to prune the store past its caps, in ms. `0` disables the loop.
+   *
+   * Retention has to run on a timer, not only on ingest: a session that stops
+   * receiving telemetry should not keep whatever it accumulated forever, and
+   * pruning inside the ingest path would put a delete on the hot path of every
+   * batch.
+   */
+  retentionIntervalMs?: number;
+}
+/**
+ * Traces read when aggregating errors.
+ *
+ * Deliberately large: an error group's count is only right if every occurrence
+ * in the window is seen, and a page-sized read would under-report the common
+ * failures most — the ones with occurrences past the page boundary.
+ */
+declare class DevtoolsServer {
+  private wss;
+  private readonly wsPath;
+  private readonly loopbackOnly;
+  private clients;
+  private httpServer;
+  private traces;
+  private logs;
+  private agentSessions;
+  private errorAggregator;
+  private limits;
+  private verbose;
+  private _port;
+  private onData?;
+  /**
+   * Durable store. The in-memory `traces`/`logs` arrays above remain the live
+   * tail — what a freshly-connected client is handed and what streams over WS —
+   * while the store answers queries and outlives the process. Both are written
+   * on every ingest; neither is derived from the other.
+   */
+  private store;
+  private retentionTimer;
+  constructor(options?: DevtoolsServerOptions);
+  get port(): number;
+  get clientCount(): number;
+  addTrace(trace: TraceData): void;
+  addTraces(traces: TraceData[]): void;
+  addLog(log: LogData): void;
+  addLogs(logs: LogData[]): void;
+  /** Ingest one decoded OTLP request, regardless of its transport. */
+  /**
+   * Serve the live tail on another HTTP listener.
+   *
+   * A loopback bind produces two listeners, one per IP family, because
+   * `localhost` resolves to `::1` on macOS and `127.0.0.1` elsewhere. The HTTP
+   * routes were attached to both from the start and the WebSocket was not, so
+   * the widget connected over one address and silently failed over the other:
+   * telemetry visible, live tail dead, and nothing in the UI saying why.
+   *
+   * Both listeners hand their upgrades to the same `WebSocketServer`, so there
+   * is still one client set and one broadcast.
+   */
+  attachWebSocket(server: Server): void;
+  ingestOtlp(signal: 'traces' | 'logs' | 'metrics', payload: unknown): number;
+  /** Fold decoded agent log events into sessions and broadcast the full set. */
+  ingestAgentEvents(records: AgentRawEvent[]): void;
+  /**
+   * Store decoded metric streams for the Metrics tab.
+   *
+   * Separate from `ingestAgentMetrics`: that folds the same OTLP batch into
+   * coding-agent sessions through a counter-shaped model, while this keeps the
+   * full data points — buckets, quantiles, exemplars — that charts need.
+   */
+  ingestMetricStreams(streams: MetricStreamRecord[]): void;
+  /** Metric catalogue: every metric name held, with its kind and series count. */
+  listMetricNames(): MetricCatalogEntry[];
+  queryMetricCatalog(query: string): {
+    metrics: MetricCatalogEntry[];
+    errors?: QueryError[];
+  };
+  /** The series for one metric, with their points. */
+  queryMetricSeries(args: QueryMetricSeriesArgs): MetricSeries[];
+  /** Fold decoded agent metric records into sessions and broadcast the full set. */
+  ingestAgentMetrics(records: OtelMetricRecord[]): void;
+  private broadcastAgents;
+  /**
+   * Run a query against the durable store.
+   *
+   * Distinct from `getCurrentData()`, which returns the live tail: this reaches
+   * the whole retained history, which is normally far larger than the tail and
+   * is the only way to see anything from before the process restarted.
+   */
+  queryTraces(args: QueryTracesArgs): QueryTracesResult;
+  /** Route and span-name counts, for the instrumentation coverage join. */
+  observedSpans(): ReturnType<DevtoolsStore['observedSpans']>;
+  /** One row per matching span, as the population for a cohort comparison. */
+  cohortRows(args: QueryTracesArgs): Array<Record<string, unknown>>;
+  /**
+   * Aggregate errors from the store for a window and query.
+   *
+   * A fresh aggregator over whatever the store returns, rather than a second
+   * implementation: the grouping, fingerprinting and sampling rules are the
+   * same ones the live path uses, so the two cannot describe the same failure
+   * differently.
+   *
+   * The live `errorAggregator` stays as it is — it backs the WS full-state
+   * broadcast, which has no window and needs none.
+   */
+  queryErrors(args: QueryTracesArgs): {
+    errors: ErrorGroup[];
+    errors_parse?: QueryError[];
+  };
+  /** Run a log query against the durable store. */
+  queryLogs(args: QueryLogsArgs): QueryLogsResult;
+  listQueryFields(signal: 'traces' | 'logs'): string[];
+  searchAttributes(signal: 'traces' | 'logs', value: string, limit?: number): {
+    key: string;
+    value: unknown;
+    count: number;
+  }[];
+  getStoreStats(): StoreStats;
+  describeTrace(traceId: string): TraceProjection | null;
+  findSlowestTraces(limit?: number): TraceProjection[];
+  /** Prune the store to its retention cap. Safe to call on a timer. */
+  enforceRetention(): void;
+  /**
+   * Prune periodically for the life of the server.
+   *
+   * `unref` matters: without it this timer alone keeps the Node process alive,
+   * so a CLI that has finished its work would hang instead of exiting. A
+   * failure is logged rather than thrown — an interval callback that throws
+   * takes the process down, and a missed prune is not worth that.
+   */
+  private startRetentionLoop;
+  getCurrentData(): DevtoolsData;
+  clearData(): void;
+  clearSignal(signal: 'traces' | 'logs' | 'metrics'): void;
+  deleteMetric(name: string): number;
+  deleteTraces(traceIds: string[]): number;
+  private broadcast;
+  private log;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/server/exporter.d.ts
+declare class DevtoolsSpanExporter implements SpanExporter {
+  private server;
+  private serviceName;
+  constructor(server: DevtoolsServer, serviceName?: string);
+  /**
+   * Export spans to the WebSocket server
+   */
+  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): Promise<void>;
+  /**
+   * Shutdown the exporter
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Force flush any buffered spans
+   */
+  forceFlush(): Promise<void>;
+  /**
+   * Convert OpenTelemetry spans to TraceData
+   */
+  private convertToTraceData;
+  /**
+   * Convert OpenTelemetry span to SpanData
+   */
+  private convertSpan;
+  private convertScope;
+  /**
+   * Convert OpenTelemetry SpanKind to string
+   */
+  private convertSpanKind;
+}
+//#endregion
+export { DevtoolsStoreOptions as a, QueryLogsArgs as c, QueryTracesArgs as d, QueryTracesResult as f, DevtoolsStore as i, QueryLogsResult as l, TimeWindow as m, DevtoolsServer as n, MetricCatalogEntry as o, SPAN_SCHEMA as p, DevtoolsServerOptions as r, MetricSeries as s, DevtoolsSpanExporter as t, QueryMetricSeriesArgs as u };