@autter/otlp-ingester 1.6.0 → 1.7.0

package/dist/source-maps.js

@@ -1,7 +1,16 @@
 import { createHash } from "node:crypto";
 import { scrubText } from "./redact.js";
-/** Largest stored map (after `sourcesContent` is removed), in characters. */
-export const SOURCE_MAP_MAX_CHARS = 5 * 1024 * 1024;
+/**
+ * Largest stored map (after `sourcesContent` is removed), in characters:
+ * 32 MiB, room for vendor chunks of about 20 MB of minified code. Storage
+ * is a ZSTD-compressed String column, so size only costs disk; a map this
+ * big is still symbolicated, without being kept in the parse cache unless
+ * SOURCE_MAP_CACHE_MB allows it (symbolicate.ts). Was 5 MiB up to 1.6.0.
+ */
+export const SOURCE_MAP_MAX_CHARS = 32 * 1024 * 1024;
+/** `/v1/sourcemaps` body limit, counted after a gzip or deflate body is
+ * inflated: the largest map plus room for the rest of the request. */
+export const SOURCE_MAP_MAX_BODY_BYTES = SOURCE_MAP_MAX_CHARS + 1024 * 1024;
 /** Bundles a map can be uploaded for: `.js`, `.mjs` and `.cjs` (1.6.0+). */
 const BUNDLE_PATH_RE = /\.[cm]?js$/;
 /** A debug id: 8-4-4-4-12 lowercase hex. Written by `autter-runtime
@@ -83,7 +92,10 @@ export function validateSourceMap(body) {
     const debugId = rawDebugId === undefined || rawDebugId === null || rawDebugId === "" ? "" : normalizeDebugId(rawDebugId);
     if (debugId === null)
         return null;
-    // Source contents are unnecessary for position lookup and may contain secrets.
+    // Source contents are unnecessary for position lookup and may contain
+    // secrets. Everything else is stored as sent, extension fields included:
+    // symbolication reads `x_autter_scopes` (function scopes) from it, and the
+    // CLI hashes exactly this JSON to skip maps already uploaded.
     const { sourcesContent: _omitted, ...safe } = parsed;
     const map = JSON.stringify(safe);
     if (map.length > SOURCE_MAP_MAX_CHARS)
@@ -94,9 +106,12 @@ export function validateSourceMap(body) {
 export const SOURCE_MAP_CHECK_MAX = 500;
 /**
  * Validate a `/v1/sourcemaps/check` request:
- * `{ release, files: [{ filename, debugId?, hash }] }` (≤ 500 files). The
+ * `{ release, files: [{ filename, debugId?, hash? }] }` (≤ 500 files). The
  * filenames and debug ids are normalised exactly as an upload would store
- * them. Null when invalid.
+ * them. Each file needs a hash (is this exact map stored? — what `upload`
+ * asks to skip maps) or, from 1.7.0, a debug id alone (is any map stored
+ * for this bundle? — what `sourcemaps verify` asks after the maps were
+ * deleted). Null when invalid.
  */
 export function validateSourceMapCheck(body) {
     if (!body || typeof body !== "object")
@@ -111,7 +126,10 @@ export function validateSourceMapCheck(body) {
         if (!raw || typeof raw !== "object")
             return null;
         const file = raw;
-        if (typeof file.filename !== "string" || typeof file.hash !== "string" || !/^[0-9a-f]{64}$/.test(file.hash))
+        if (typeof file.filename !== "string")
+            return null;
+        const hash = file.hash === undefined || file.hash === null || file.hash === "" ? "" : file.hash;
+        if (typeof hash !== "string" || (hash !== "" && !/^[0-9a-f]{64}$/.test(hash)))
             return null;
         const filename = sourceMapPath(file.filename);
         if (!filename)
@@ -119,7 +137,9 @@ export function validateSourceMapCheck(body) {
         const debugId = file.debugId === undefined || file.debugId === null || file.debugId === "" ? "" : normalizeDebugId(file.debugId);
         if (debugId === null)
             return null;
-        entries.push({ filename, debugId, hash: file.hash });
+        if (!hash && !debugId)
+            return null;
+        entries.push({ filename, debugId, hash });
     }
     return { release: input.release, entries };
 }

package/dist/symbolicate.d.ts

@@ -1,4 +1,6 @@
 import { TraceMap } from "@jridgewell/trace-mapping";
+import { type GeneratedPosition, type MappedSegment } from "./source-map-mappings.js";
+import { ScopeIndex } from "./source-map-scopes.js";
 import type { SourceMapKey } from "./source-maps-lookup.js";
 import type { StackFrame } from "./types.js";
 /**
@@ -7,11 +9,17 @@ import type { StackFrame } from "./types.js";
  * fingerprinted, so `frames-v3` hashes `checkout.tsx`, not
  * `index-5f3a9c1e.js` — and an issue survives deploys and preview domains.
  *
- * - Function names come from the map's `names`: the name mapped at the
- *   CALLER's position is the callee's original name (the call site names
- *   what it calls). Without one, a resolved frame keeps its parsed name
- *   only when that is not an obviously mangled one (≤ 2 characters), since
- *   a mangled name changes on every build.
+ * - Function names: when the map carries function scopes
+ *   (`x_autter_scopes`, uploaded by @autter/runtime-cli after 1.0.0), a
+ *   frame is named after the innermost function containing it, with that
+ *   function's original name (null in an anonymous function or top-level
+ *   code) — see source-map-scopes.ts. Maps without scopes keep the earlier
+ *   rule: the name mapped at the CALLER's position is the callee's original
+ *   name; without one, a resolved frame keeps its parsed name only when
+ *   that is not an obviously mangled one (≤ 2 characters), since a mangled
+ *   name changes on every build. That rule is wrong for calls through a
+ *   variable (`const run = actions.captured; run()` names the frame `run`)
+ *   and for handlers a framework calls, which is why scopes exist.
  * - Sources the map lists in `ignoreList` / `x_google_ignoreList` are not
  *   in-app; a resolved path under node_modules/ etc. is not in-app either.
  * - Context lines only when the map carries `sourcesContent` (the upload
@@ -19,7 +27,10 @@ import type { StackFrame } from "./types.js";
  * - Never fails ingest: any error leaves the frame as parsed.
  *
  * Parsed maps are cached per (org, repository, release, file) — or per debug
- * id — in a byte-bounded LRU, so a busy issue never refetches its map.
+ * id — in a byte-bounded LRU, so a busy issue never refetches its map. A map
+ * that would take more than half of that budget is used for its lookup and
+ * not kept (source-map-mappings.ts reads it without decoding it), so one huge
+ * vendor chunk cannot flush every other map.
  */
 export type MapFetcher = (key: SourceMapKey) => Promise<string | null>;
 export interface SymbolicationScope {
@@ -32,7 +43,8 @@ export interface SymbolicationScope {
 /** Path-only form of a script URL — the key uploads are stored under. */
 export declare function scriptPath(filename: string): string | null;
 export interface SourceMapCacheOptions {
-    /** Budget for the estimated in-memory size of parsed maps (default 64 MiB). */
+    /** Budget for the estimated in-memory size of parsed maps (default 64 MiB).
+     * A map that would take more than half of it is not cached. */
     maxBytes?: number;
     maxEntries?: number;
     /** How long a found map is reused (default 1 h). */
@@ -43,6 +55,19 @@ export interface SourceMapCacheOptions {
     errorTtlMs?: number;
     now?: () => number;
 }
+/** A parsed map: its metadata, its function scopes, and position lookups. */
+export interface LoadedSourceMap {
+    /** Sources, names, ignore list and sourcesContent. Its own `mappings`
+     * are left empty: positions go through `lookup`. */
+    map: TraceMap;
+    scopes: ScopeIndex | null;
+    /** Original positions for 0-based generated positions (one call per stack). */
+    lookup(positions: readonly GeneratedPosition[]): Array<MappedSegment | null>;
+    /** Estimated heap: decoded mappings (when decoded), strings and scopes. */
+    bytes: number;
+    /** False when the map was too big to keep, so its mappings were not decoded. */
+    cacheable: boolean;
+}
 export declare class SourceMapCache {
     private readonly entries;
     private readonly inFlight;
@@ -55,15 +80,28 @@ export declare class SourceMapCache {
     private readonly now;
     /** Fetches made (cache misses) — for tests and /healthz-style debugging. */
     fetches: number;
+    /** Maps used without being cached because they were too big to keep. */
+    bypassed: number;
     constructor(options?: SourceMapCacheOptions);
     static keyOf(key: SourceMapKey): string;
     get size(): number;
+    /** Estimated bytes of the cached maps (what `maxBytes` bounds). */
+    get bytes(): number;
     /** The parsed map for `key` (null when none), fetching at most once at a time. */
-    get(key: SourceMapKey, fetchMap: MapFetcher): Promise<TraceMap | null>;
+    get(key: SourceMapKey, fetchMap: MapFetcher): Promise<LoadedSourceMap | null>;
     private load;
     private store;
     private remove;
 }
+/**
+ * Parse a stored map once: metadata, scopes (null when absent or malformed
+ * — a bad scope field never loses the map) and position lookups. When the
+ * estimated heap is at most `maxDecodedBytes`, the mappings are decoded
+ * once into a compact table; otherwise they are left encoded and each
+ * lookup reads them in one pass (`cacheable: false`). Throws when the map
+ * itself is unusable.
+ */
+export declare function parseSourceMap(json: string, maxDecodedBytes?: number): LoadedSourceMap;
 export declare class Symbolicator {
     private readonly fetchMap;
     readonly cache: SourceMapCache;

package/dist/symbolicate.js

@@ -1,4 +1,6 @@
-import { isIgnored, originalPositionFor, sourceContentFor, TraceMap, } from "@jridgewell/trace-mapping";
+import { isIgnored, sourceContentFor, TraceMap, } from "@jridgewell/trace-mapping";
+import { DecodedMappings, decodedMappingsBytes, findInMappings, } from "./source-map-mappings.js";
+import { SCOPES_KEY, ScopeIndex } from "./source-map-scopes.js";
 import { isInAppPath, stripQueryAndHash } from "./stack-frames.js";
 const JS_FILE_RE = /\.[cm]?js$/i;
 const MAX_CONTEXT_CHARS = 300;
@@ -13,10 +15,11 @@ export function scriptPath(filename) {
     }
 }
 /**
- * Decoded mappings take several times the JSON's size; the budget counts an
- * estimate so a handful of large bundles cannot exhaust a small container.
+ * The largest share of the budget one map may take. A bigger one is used
+ * for its lookup and dropped: keeping it would evict most other maps, and
+ * every event in those files would then refetch theirs.
  */
-const DECODED_WEIGHT_FACTOR = 8;
+const MAX_SHARE_OF_BUDGET = 0.5;
 export class SourceMapCache {
     entries = new Map();
     inFlight = new Map();
@@ -29,6 +32,8 @@ export class SourceMapCache {
     now;
     /** Fetches made (cache misses) — for tests and /healthz-style debugging. */
     fetches = 0;
+    /** Maps used without being cached because they were too big to keep. */
+    bypassed = 0;
     constructor(options = {}) {
         this.maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
         this.maxEntries = options.maxEntries ?? 500;
@@ -46,6 +51,10 @@ export class SourceMapCache {
     get size() {
         return this.entries.size;
     }
+    /** Estimated bytes of the cached maps (what `maxBytes` bounds). */
+    get bytes() {
+        return this.weight;
+    }
     /** The parsed map for `key` (null when none), fetching at most once at a time. */
     async get(key, fetchMap) {
         const id = SourceMapCache.keyOf(key);
@@ -81,17 +90,20 @@ export class SourceMapCache {
             this.store(id, null, 0, this.missTtlMs);
             return null;
         }
-        let map;
+        let loaded;
         try {
-            map = new TraceMap(json);
+            loaded = parseSourceMap(json, this.maxBytes * MAX_SHARE_OF_BUDGET);
         }
         catch {
             // A malformed upload is a miss until it is replaced.
             this.store(id, null, 0, this.missTtlMs);
             return null;
         }
-        this.store(id, map, json.length * DECODED_WEIGHT_FACTOR, this.hitTtlMs);
-        return map;
+        if (loaded.cacheable)
+            this.store(id, loaded, loaded.bytes, this.hitTtlMs);
+        else
+            this.bypassed += 1;
+        return loaded;
     }
     store(id, map, weight, ttlMs) {
         // A map bigger than the whole budget serves this lookup but is not kept:
@@ -115,6 +127,61 @@ export class SourceMapCache {
         this.weight -= entry.weight;
     }
 }
+/** Rough heap of a list of strings (V8 strings plus array slots). */
+function stringsBytes(list) {
+    if (!Array.isArray(list))
+        return 0;
+    let bytes = 16;
+    for (const item of list)
+        bytes += 8 + (typeof item === "string" ? 2 * item.length + 24 : 0);
+    return bytes;
+}
+/**
+ * Parse a stored map once: metadata, scopes (null when absent or malformed
+ * — a bad scope field never loses the map) and position lookups. When the
+ * estimated heap is at most `maxDecodedBytes`, the mappings are decoded
+ * once into a compact table; otherwise they are left encoded and each
+ * lookup reads them in one pass (`cacheable: false`). Throws when the map
+ * itself is unusable.
+ */
+export function parseSourceMap(json, maxDecodedBytes = Number.POSITIVE_INFINITY) {
+    const raw = JSON.parse(json);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("not a source map");
+    const fields = raw;
+    const { mappings } = fields;
+    if (typeof mappings !== "string")
+        throw new Error("no mappings");
+    // TraceMap copies only the standard fields, but given an object that has
+    // its private `_decodedMemo` it would return that object as is. It gets
+    // no mappings: decoding them is this module's job.
+    delete fields._decodedMemo;
+    const map = new TraceMap({ ...fields, mappings: "" });
+    let scopes = null;
+    try {
+        scopes = ScopeIndex.from(fields[SCOPES_KEY], map.names);
+    }
+    catch {
+        scopes = null;
+    }
+    const bytes = decodedMappingsBytes(mappings) +
+        stringsBytes(map.names) +
+        stringsBytes(map.sources) +
+        stringsBytes(map.resolvedSources) +
+        stringsBytes(map.sourcesContent) +
+        (scopes?.bytes ?? 0);
+    if (bytes <= maxDecodedBytes) {
+        const decoded = DecodedMappings.decode(mappings);
+        return {
+            map,
+            scopes,
+            bytes,
+            cacheable: true,
+            lookup: (positions) => positions.map((position) => decoded.find(position.line, position.column)),
+        };
+    }
+    return { map, scopes, bytes, cacheable: false, lookup: (positions) => findInMappings(mappings, positions) };
+}
 // ── Resolution ────────────────────────────────────────────────────────────
 /** A name a minifier evidently produced ("a", "Xe", "Object.t"). */
 function looksMangled(name) {
@@ -201,24 +268,20 @@ export class Symbolicator {
         if (!keys.some(Boolean))
             return frames;
         const maps = await Promise.all(keys.map((key) => (key ? this.cache.get(key, this.fetchMap) : Promise.resolve(null))));
-        const resolutions = frames.map((frame, i) => {
-            const map = maps[i];
-            if (!map)
-                return null;
-            try {
-                return resolveFrame(map, frame);
-            }
-            catch {
-                return null;
-            }
-        });
+        const resolutions = resolveFrames(frames, maps);
         if (!resolutions.some(Boolean))
             return frames;
         return frames.map((frame, i) => {
             const resolution = resolutions[i];
             if (!resolution)
                 return frame;
-            // Innermost first: the caller is the next frame.
+            const { scope } = resolution;
+            if (scope?.kind === "named")
+                return { ...resolution.frame, function: scope.name };
+            if (scope?.kind === "anonymous")
+                return { ...resolution.frame, function: null };
+            // No scopes (an older upload), or a function whose name the CLI
+            // could not map: innermost first, so the caller is the next frame.
             const callerName = resolutions[i + 1]?.nameHere ?? null;
             const parsed = frame.function;
             const name = callerName ?? (parsed && !looksMangled(parsed) ? parsed : null);
@@ -226,32 +289,75 @@ export class Symbolicator {
         });
     }
 }
-function resolveFrame(map, frame) {
-    const position = originalPositionFor(map, {
-        line: frame.lineno,
-        // Stack columns are 1-based, source map columns 0-based.
-        column: Math.max(0, (frame.colno ?? 1) - 1),
+/** A frame's 0-based generated position (stack lines and columns are 1-based). */
+function generatedPosition(frame) {
+    return { line: frame.lineno - 1, column: Math.max(0, (frame.colno ?? 1) - 1) };
+}
+/** Resolve every frame that has a map, with one lookup per map: a map too
+ * big to keep is read in a single pass for the whole stack. */
+function resolveFrames(frames, maps) {
+    const resolutions = frames.map(() => null);
+    const byMap = new Map();
+    maps.forEach((loaded, index) => {
+        if (!loaded)
+            return;
+        const indexes = byMap.get(loaded);
+        if (indexes)
+            indexes.push(index);
+        else
+            byMap.set(loaded, [index]);
     });
-    if (!position.source || position.line == null)
+    for (const [loaded, indexes] of byMap) {
+        const positions = indexes.map((index) => generatedPosition(frames[index]));
+        let segments;
+        try {
+            segments = loaded.lookup(positions);
+        }
+        catch {
+            continue;
+        }
+        indexes.forEach((frameIndex, k) => {
+            try {
+                resolutions[frameIndex] = resolveFrame(loaded, frames[frameIndex], positions[k], segments[k] ?? null);
+            }
+            catch {
+                resolutions[frameIndex] = null;
+            }
+        });
+    }
+    return resolutions;
+}
+function resolveFrame(loaded, frame, position, segment) {
+    const { map } = loaded;
+    if (!segment)
+        return null;
+    const source = map.resolvedSources[segment.source];
+    if (!source)
         return null;
-    const filename = stripQueryAndHash(position.source);
+    const filename = stripQueryAndHash(source);
     const ignored = (() => {
         try {
-            return isIgnored(map, position.source);
+            return isIgnored(map, source);
         }
         catch {
             return false;
         }
     })();
+    const line = segment.line + 1;
     const resolved = {
         function: frame.function,
         module: null,
         filename,
-        lineno: position.line,
-        colno: position.column == null ? null : position.column + 1,
+        lineno: line,
+        colno: segment.column + 1,
         inApp: !ignored && isInAppPath(filename),
         resolved: true,
-        ...contextFor(map, position.source, position.line),
+        ...contextFor(map, source, line),
+    };
+    const name = segment.name >= 0 ? map.names[segment.name] : undefined;
+    return {
+        frame: resolved,
+        nameHere: typeof name === "string" ? name : null,
+        scope: loaded.scopes ? loaded.scopes.nameAt(position.line, position.column) : null,
     };
-    return { frame: resolved, nameHere: position.name ?? null };
 }

package/dist/trace-dedupe.d.ts

@@ -0,0 +1,98 @@
+import type { RuntimeOccurrenceInput } from "./types.js";
+/**
+ * One error can be recorded on several spans of a trace. In a Next.js app a
+ * route handler's error is recorded by @autter/runtime-node on the request's
+ * HTTP server span AND by Next's own "executing api route" / render span
+ * (OpenTelemetry `recordException`); Express, Fastify, NestJS and gRPC
+ * instrumentations do the same, and errored ancestor spans with no event
+ * would add a stackless `HttpServerError` / `SpanError` on top. Each of
+ * those used to become its own occurrence, so one thrown error was counted
+ * two or three times. This pass, run on one export batch, keeps one
+ * occurrence per thrown error.
+ *
+ * Rule 1, duplicate recordings. Two exception occurrences are recordings of
+ * the same thrown error when ALL of these hold:
+ *   - same trace, service, environment and release (a thrown error lives in
+ *     one process);
+ *   - on DIFFERENT spans, one an ancestor of the other through parent links
+ *     present in the batch (an error propagating outward through nested
+ *     spans). Two events on one span are two recordings made on purpose (a
+ *     retry loop capturing each attempt on the request span) and are never
+ *     merged; nor are errors on sibling spans (one span per attempt);
+ *   - the same error type, or the OpenTelemetry JS `recordException`
+ *     convention: a third-party recording (no `autter.*` on its event) of an
+ *     error with a `code` reports the code as `exception.type` ("P2002",
+ *     "ECONNREFUSED"), so its type may instead equal the other's declared
+ *     `autter.error.code`, or its stack header may name the other's type;
+ *   - the same message after scrubbing and `normalizeMessage`;
+ *   - the same stack: the parsed in-app frames (function, file, line) are
+ *     equal or one list is a prefix (truncated) or suffix (captured at record
+ *     time, higher up) of the other. A side without a stack is no evidence
+ *     against; without in-app frames all frames are compared;
+ *   - recorded within DUPLICATE_WINDOW_MS of the group's latest recording.
+ * Recordings are grouped greedily in time order: each joins the eligible
+ * group (no member on its span, every member on its ancestor/descendant
+ * chain and matching it) whose latest recording is the most recent, so when
+ * every attempt of a retry loop is recorded on a child span and again on the
+ * parent, each attempt pairs with its own parent recording.
+ *
+ * The group keeps the occurrence with the most information: the one the
+ * Autter SDK recorded (`autter.*` on the event, or `autter.severity` on the
+ * span), then the one carrying runtime-next's `onRequestError` context, then
+ * the one on the span closest to the root. It keeps that occurrence's type,
+ * message, severity, time and batch position (so its deterministic id), and
+ * takes from the others what it lacks: attributes (its own win), stack,
+ * route, method, status, request id, declared error fields, fingerprint
+ * override and breadcrumbs. `autter.merged_recordings` counts the merged
+ * recordings.
+ *
+ * Rule 2, redundant status-only occurrences. A status-only `HttpServerError`
+ * / `SpanError` (an errored span without exception or failed-outcome events)
+ * is dropped when the same trace and service in this batch has an exception
+ * or failed outcome of severity error or fatal, not `autter.handled`, on an
+ * ancestor or descendant of its span: the span failed because of that
+ * error. It is kept when it is the trace's only signal, when the only
+ * errors are warnings or handled ones, or when no ancestor/descendant link
+ * is visible in the batch (sibling branches, a parent exported elsewhere).
+ *
+ * Scope: one export batch. A request's spans normally end, and are
+ * exported, together; when the exporter's timer splits them across batches,
+ * the recordings in different batches are still counted separately.
+ */
+/** Two recordings of one thrown error happen as it propagates outward:
+ * milliseconds apart, seconds at most for an error handler that awaits. */
+export declare const DUPLICATE_WINDOW_MS = 5000;
+export interface TraceSignal {
+    occurrence: RuntimeOccurrenceInput;
+    traceId: string;
+    spanId: string;
+    /** What produced it: an `exception` event, a failed `autter.outcome`
+     * event, or the span's error status alone. */
+    signal: "exception" | "outcome" | "status";
+    /** The Autter SDK recorded it: `autter.*` on the event, or
+     * `autter.severity` (captureException's marker) on the span. */
+    autterCapture: boolean;
+    /** `autter.*` attributes on the event itself. */
+    eventAutter: boolean;
+    /** runtime-next's `onRequestError` context on the span or event. */
+    nextContext: boolean;
+    /** `autter.handled` on the event: handled on purpose, not why a span failed. */
+    handled: boolean;
+}
+export interface SpanLink {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+}
+export interface DedupedSignals {
+    /** The surviving occurrences, in batch order (merged where rule 1 applied). */
+    occurrences: RuntimeOccurrenceInput[];
+    /** Input index of each survivor: its position in the batch, which its
+     * deterministic occurrence id is derived from. */
+    sourceIndexes: number[];
+    /** Input indexes each survivor stands for (itself first). */
+    members: number[][];
+}
+export declare function hasNextContext(...sources: Array<Map<string, string>>): boolean;
+export declare function hasAutterKey(attrs: Map<string, string>): boolean;
+export declare function dedupeTraceSignals(signals: TraceSignal[], spans: SpanLink[]): DedupedSignals;