@autter/otlp-ingester 1.7.0 → 1.8.0

package/dist/sink.d.ts

@@ -26,6 +26,17 @@ export interface SinkTuning {
     /** Deliveries run concurrently while healthy, serially while failing. */
     healthyConcurrency: number;
 }
+/** A batch the sink gave up on (counted in runtime_ingest_drops, route "sink"). */
+export interface SinkDrop {
+    orgId: string;
+    repositoryId: string;
+    /** sink_overflow: buffer overflow, or a batch bigger than the buffer;
+     * sink_rejected: the consumer answered a permanent 4xx;
+     * sink_gave_up: SINK_MAX_ATTEMPTS deliveries failed. */
+    reason: "sink_overflow" | "sink_rejected" | "sink_gave_up";
+    /** Occurrences in the batch. */
+    occurrences: number;
+}
 /**
  * Operational counters for /healthz. Failure detail is reduced to a fixed
  * category (`timeout`, `connection_error`, `http_<status>`, `error`) — the
@@ -72,10 +83,13 @@ export declare class SinkForwarder {
     private lastFailureAt;
     private lastFailureReason;
     private readonly tuning;
+    /** Called for every batch given up on; must not throw (errors are swallowed). */
+    onDrop: ((drop: SinkDrop) => void) | null;
     constructor(config: IngesterConfig, fetchImpl?: typeof fetch, tuning?: Partial<SinkTuning>);
     /** Queue a batch for delivery. No-op when there is nothing to send. */
     enqueue(ctx: IngestContext, occurrences: RuntimeOccurrence[], metricPoints?: RuntimeMetricPoint[], llmCalls?: RuntimeLlmCall[]): void;
     stats(): SinkStats;
+    private noteDrop;
     pendingCount(): number;
     /** Stop scheduling new deliveries (shutdown). Queued batches are logged
      * by the caller — they are recoverable from ClickHouse, not from here. */

package/dist/sink.js

@@ -44,6 +44,8 @@ export class SinkForwarder {
     lastFailureAt = null;
     lastFailureReason = null;
     tuning;
+    /** Called for every batch given up on; must not throw (errors are swallowed). */
+    onDrop = null;
     constructor(config, fetchImpl = fetch, tuning = {}) {
         this.config = config;
         this.fetchImpl = fetchImpl;
@@ -65,6 +67,7 @@ export class SinkForwarder {
         if (batch.bytes > this.maxBufferedBytes()) {
             this.droppedOverflow += 1;
             console.warn(`sink batch ${batch.batchId} (org ${batch.orgId}) exceeds the buffer cap (${batch.bytes} bytes) — dropped; replay signals ${batch.signalsFrom ?? "?"} .. ${batch.signalsTo ?? "?"} from ClickHouse`);
+            this.noteDrop(batch, "sink_overflow");
             return;
         }
         this.queue.push(batch);
@@ -88,6 +91,14 @@ export class SinkForwarder {
             oldestQueuedSince: oldest ? new Date(oldest).toISOString() : null,
         };
     }
+    noteDrop(batch, reason) {
+        try {
+            this.onDrop?.({ orgId: batch.orgId, repositoryId: batch.repositoryId, reason, occurrences: batch.occurrences });
+        }
+        catch {
+            // Drop accounting must never affect delivery.
+        }
+    }
     pendingCount() {
         return this.queue.length + this.inFlight;
     }
@@ -122,6 +133,8 @@ export class SinkForwarder {
         return {
             batchId,
             orgId: ctx.orgId,
+            repositoryId: ctx.repositoryId,
+            occurrences: occurrences.length,
             body,
             bytes: Buffer.byteLength(body),
             seq: ++this.seqCounter,
@@ -170,6 +183,7 @@ export class SinkForwarder {
                 break;
             this.droppedOverflow += 1;
             console.warn(`sink buffer overflow: dropped batch ${dropped.batchId} (org ${dropped.orgId}, signals ${dropped.signalsFrom ?? "?"} .. ${dropped.signalsTo ?? "?"}) — replay this range from ClickHouse`);
+            this.noteDrop(dropped, "sink_overflow");
         }
     }
     /** The oldest batch of the org holding the most buffered bytes. */
@@ -280,6 +294,7 @@ export class SinkForwarder {
         if (permanent || batch.attempts >= this.config.sinkMaxAttempts) {
             this.droppedPermanent += 1;
             console.error(`sink delivery gave up after ${batch.attempts} attempt(s) (${detail}): batch ${batch.batchId} (signals ${batch.signalsFrom ?? "?"} .. ${batch.signalsTo ?? "?"}) — replay this range from ClickHouse`);
+            this.noteDrop(batch, permanent ? "sink_rejected" : "sink_gave_up");
             return;
         }
         this.retried += 1;

package/dist/stack-frames.d.ts

@@ -11,8 +11,10 @@ import type { StackFrame } from "./types.js";
  * - V8 (Node, Chrome, Edge): `at fn (file:line:col)` / `at file:line:col`
  * - Firefox / Safari: `fn@url:line:col` / `@url:line:col`
  * - Python: `File "…", line N, in fn` — tracebacks list the OUTERMOST frame
- *   first, so the frames are reversed; only the last (reported) traceback
- *   of a chained exception is used
+ *   first, so the frames are reversed; only the reported exception's own
+ *   frames are used: the last top-level block of a chained exception, and
+ *   for an exception group (3.11+) its own `| `-margined block, never its
+ *   sub-exceptions
  * - Go: function line + `\t<file>.go:<line> +0x…`, first goroutine only
  * - JVM: `at pkg.Class.method(File.java:N)`, first exception block only
  *   (before `Caused by:`)
@@ -34,6 +36,7 @@ export type FrameLanguage = "javascript" | "python" | "go" | "jvm" | "dotnet" |
  * `C:\app\node_modules\x.js` counts too. A frame with no path is in-app.
  */
 export declare function isInAppPath(path: string | null): boolean;
+export declare function isPythonStdlibPath(path: string | null): boolean;
 /**
  * Contract §3. Source-map ignore lists are applied by symbolicate.ts; the
  * language rules apply only to frames of that language, so a JS object

package/dist/stack-frames.js

@@ -11,8 +11,10 @@ import { detectStackLanguage } from "./fingerprint.js";
  * - V8 (Node, Chrome, Edge): `at fn (file:line:col)` / `at file:line:col`
  * - Firefox / Safari: `fn@url:line:col` / `@url:line:col`
  * - Python: `File "…", line N, in fn` — tracebacks list the OUTERMOST frame
- *   first, so the frames are reversed; only the last (reported) traceback
- *   of a chained exception is used
+ *   first, so the frames are reversed; only the reported exception's own
+ *   frames are used: the last top-level block of a chained exception, and
+ *   for an exception group (3.11+) its own `| `-margined block, never its
+ *   sub-exceptions
  * - Go: function line + `\t<file>.go:<line> +0x…`, first goroutine only
  * - JVM: `at pkg.Class.method(File.java:N)`, first exception block only
  *   (before `Caused by:`)
@@ -63,6 +65,22 @@ export function isInAppPath(path) {
         return false;
     return true;
 }
+/**
+ * Python's standard library: frozen modules (`<frozen runpy>`) and the
+ * version directory of an installation (`/usr/local/lib/python3.12/`,
+ * `…/Versions/3.14/lib/python3.14/`, `C:\Python312\Lib\`); a
+ * virtualenv's packages are `site-packages`, covered by the path rule. Like
+ * Go's `/usr/local/go/`, they are the runtime, not the app: an asyncio or
+ * socket error's first five frames would otherwise all be stdlib frames.
+ */
+const PY_STDLIB_RE = /\/lib\/(?:python|pypy)\d\.\d+t?\/|\/python\d{2,3}t?\/lib\//i;
+export function isPythonStdlibPath(path) {
+    if (!path)
+        return false;
+    if (path.startsWith("<frozen "))
+        return true;
+    return PY_STDLIB_RE.test(path.replace(/\\/g, "/"));
+}
 /** Fully qualified name for the language rules (`module.function`). */
 function qualifiedName(frame) {
     if (frame.module && frame.function)
@@ -84,6 +102,8 @@ export function isInAppFrame(frame, language) {
         if ((frame.filename ?? "").replace(/\\/g, "/").includes("/usr/local/go/"))
             return false;
     }
+    if (language === "python" && isPythonStdlibPath(frame.filename))
+        return false;
     if (language === "jvm" && /^(?:java|javax|kotlin|jdk)\./.test(qualified))
         return false;
     if (language === "dotnet" && /^(?:System|Microsoft)\./.test(qualified))
@@ -225,15 +245,41 @@ function parseGecko(lines) {
 // ── Python ────────────────────────────────────────────────────────────────
 const PY_FILE_RE = /^\s*File "(.+)", line (\d+)(?:, in (.+?))?\s*$/;
 const PY_TRACEBACK_RE = /^\s*Traceback \(most recent call last\):\s*$/;
+// 3.11+: an exception group prints its own frames behind a "| " margin,
+// under this header (nested groups' headers carry the margin instead of "+"),
+// then its sub-exceptions after a "+-+---- 1 ----" separator.
+const PY_GROUP_TRACEBACK_RE = /^\s*\+ Exception Group Traceback \(most recent call last\):\s*$/;
+const PY_GROUP_MARGIN_RE = /^\s*\|/;
+const PY_GROUP_SUBEXCEPTIONS_RE = /^\s*\+-/;
+function isPythonFrameLine(line) {
+    return PY_FILE_RE.test(line) || PY_FILE_RE.test(line.replace(PY_GROUP_MARGIN_RE, ""));
+}
 function parsePython(lines) {
-    // A chained exception prints one traceback per exception; the reported
-    // (final) exception's frames are the last block.
-    let start = 0;
-    for (let i = 0; i < lines.length; i++)
-        if (PY_TRACEBACK_RE.test(lines[i]))
+    // A chained exception prints one block per exception, the reported
+    // (final) one last, whether the chain says "During handling of the above
+    // exception" or "The above exception was the direct cause". Blocks of
+    // sub-exceptions and of groups in the chain carry a margin, so the last
+    // unmargined header starts the reported exception's own frames.
+    let start = -1;
+    let group = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (PY_TRACEBACK_RE.test(lines[i])) {
+            start = i;
+            group = false;
+        }
+        else if (PY_GROUP_TRACEBACK_RE.test(lines[i])) {
             start = i;
+            group = true;
+        }
+    }
     const outermostFirst = [];
-    for (const line of lines.slice(start)) {
+    for (const raw of lines.slice(start + 1)) {
+        let line = raw;
+        if (group) {
+            if (PY_GROUP_SUBEXCEPTIONS_RE.test(line))
+                break;
+            line = line.replace(PY_GROUP_MARGIN_RE, "");
+        }
         const m = PY_FILE_RE.exec(line);
         if (!m)
             continue;
@@ -391,7 +437,7 @@ export function detectFrameLanguage(lines) {
             return "dotnet";
         default:
     }
-    if (lines.some((line) => PY_FILE_RE.test(line)))
+    if (lines.some(isPythonFrameLine))
         return "python";
     if (lines.some((line) => DOTNET_BARE_RE.test(line)) &&
         !lines.some((line) => /:\d+(?::\d+)?\)?\s*$/.test(line))) {

package/dist/symbolicate.d.ts

@@ -40,6 +40,19 @@ export interface SymbolicationScope {
     /** Script URL → debug id (EI-13), when the browser sent them. */
     debugIds?: Record<string, string> | null;
 }
+/**
+ * In-app browser frames a source map could resolve, counted after
+ * symbolication (EI-27): `resolved` ones, and `unresolved` .js/.mjs/.cjs
+ * frames left as parsed (no map uploaded, no release or debug id, no
+ * mapping at that position). Frames a map moved out of the app
+ * (node_modules, ignoreList) and non-JS frames count in neither. Stored per
+ * occurrence (`in_app_frames_resolved` / `in_app_frames_unresolved`) for the
+ * EI-14 rule: over 30% unresolved means the release needs source maps.
+ */
+export declare function inAppFrameResolution(frames: readonly StackFrame[] | undefined): {
+    resolved: number;
+    unresolved: number;
+};
 /** Path-only form of a script URL — the key uploads are stored under. */
 export declare function scriptPath(filename: string): string | null;
 export interface SourceMapCacheOptions {

package/dist/symbolicate.js

@@ -5,6 +5,28 @@ import { isInAppPath, stripQueryAndHash } from "./stack-frames.js";
 const JS_FILE_RE = /\.[cm]?js$/i;
 const MAX_CONTEXT_CHARS = 300;
 const CONTEXT_LINES = 3;
+/**
+ * In-app browser frames a source map could resolve, counted after
+ * symbolication (EI-27): `resolved` ones, and `unresolved` .js/.mjs/.cjs
+ * frames left as parsed (no map uploaded, no release or debug id, no
+ * mapping at that position). Frames a map moved out of the app
+ * (node_modules, ignoreList) and non-JS frames count in neither. Stored per
+ * occurrence (`in_app_frames_resolved` / `in_app_frames_unresolved`) for the
+ * EI-14 rule: over 30% unresolved means the release needs source maps.
+ */
+export function inAppFrameResolution(frames) {
+    let resolved = 0;
+    let unresolved = 0;
+    for (const frame of frames ?? []) {
+        if (!frame.inApp)
+            continue;
+        if (frame.resolved)
+            resolved += 1;
+        else if (frame.filename && JS_FILE_RE.test(frame.filename))
+            unresolved += 1;
+    }
+    return { resolved, unresolved };
+}
 /** Path-only form of a script URL — the key uploads are stored under. */
 export function scriptPath(filename) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@autter/otlp-ingester",
-	"version": "1.7.0",
+	"version": "1.8.0",
 	"description": "Self-hostable OTLP + browser-error ingest service for Autter Runtime: normalises telemetry into a per-repo ClickHouse data model",
 	"license": "MIT",
 	"type": "module",