@autter/otlp-ingester 1.4.0 → 1.6.0

package/dist/error-fields.js

@@ -0,0 +1,103 @@
+import { sanitizeRuntimeContext } from "./context.js";
+import { validErrorCode } from "./fingerprint.js";
+/**
+ * Declared error metadata on the wire (span/event attributes, log
+ * attributes, browser context keys):
+ *
+ *   autter.error.code      string matching CODE_PATTERN (≤80) — grouping key
+ *   autter.error.why       declared cause   (≤1000 chars)
+ *   autter.error.fix       declared remedy  (≤1000 chars)
+ *   autter.error.link      docs link        (http(s) only, ≤500 chars)
+ *   autter.error.expected  boolean — expected business failure
+ *   autter.request.id      request id joining the error to its summary
+ *
+ * Every field is optional and validated independently: a bad value is
+ * dropped on its own and never rejects the signal. Values are lifted onto
+ * dedicated occurrence fields (and columns) instead of living only in the
+ * attributes JSON, because the generic context sanitiser rewrites URLs
+ * (query AND fragment stripped) — the declared link keeps its #anchor here.
+ */
+export const REQUEST_ID_PATTERN = /^[\w.-]{8,128}$/;
+const EMAIL_RE = /(?<![A-Z0-9._%+-])[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+function lookup(sources, key) {
+    for (const source of sources) {
+        if (!source)
+            continue;
+        const value = source instanceof Map ? source.get(key) : source[key];
+        if (value !== undefined && value !== null && value !== "")
+            return value;
+    }
+    return undefined;
+}
+/** First source whose value for `key` passes `valid` (an invalid value on
+ * the exception event must not hide a valid one on its span). */
+function lookupValid(sources, key, valid) {
+    for (const source of sources) {
+        const value = valid(lookup([source], key));
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+/** Free text through the same scrubber as custom context, then capped. */
+function declaredText(value, max) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = sanitizeRuntimeContext({ text: value.trim() }).text;
+    return typeof text === "string" && text ? text.slice(0, max) : undefined;
+}
+/**
+ * http(s) only; credentials and query string removed (a docs link never
+ * needs them), fragment kept. Over-long links are dropped rather than
+ * truncated — a cut URL is a broken link.
+ */
+export function declaredLink(value) {
+    if (typeof value !== "string")
+        return undefined;
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return undefined;
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    const link = url.toString().replace(EMAIL_RE, "[redacted]");
+    return link.length <= 500 ? link : undefined;
+}
+export function validRequestId(value) {
+    return typeof value === "string" && REQUEST_ID_PATTERN.test(value)
+        ? value
+        : undefined;
+}
+/**
+ * Lift the declared fields from one or more attribute sources; the first
+ * source carrying a key wins (e.g. exception event before its span).
+ * Returns only the fields that are present and valid.
+ */
+export function liftErrorFields(...sources) {
+    const out = {};
+    const code = lookupValid(sources, "autter.error.code", validErrorCode);
+    if (code)
+        out.errorCode = code;
+    const why = declaredText(lookup(sources, "autter.error.why"), 1000);
+    if (why)
+        out.why = why;
+    const fix = declaredText(lookup(sources, "autter.error.fix"), 1000);
+    if (fix)
+        out.fix = fix;
+    const link = declaredLink(lookup(sources, "autter.error.link"));
+    if (link)
+        out.link = link;
+    const expected = lookup(sources, "autter.error.expected");
+    if (expected === true || expected === "true")
+        out.expected = true;
+    const requestId = lookupValid(sources, "autter.request.id", validRequestId);
+    if (requestId)
+        out.requestId = requestId;
+    return out;
+}

package/dist/fingerprint-override.d.ts

@@ -0,0 +1,42 @@
+import type { RuntimeOccurrenceInput } from "./types.js";
+/**
+ * SDK fingerprint override (EI-16) → the `manual-v1` issue identity.
+ *
+ * Where it comes from:
+ * - browser events: `fingerprint` (a string or an array of strings), from
+ *   `captureException(err, { fingerprint })` or `beforeSend`;
+ * - OTLP exception events (or their span) and promoted error logs:
+ *   `autter.fingerprint`, a string or a JSON array of strings (the SDKs always
+ *   send the JSON array, so a single value never reads as a list by accident).
+ *
+ * The normalisers carry it as `RuntimeOccurrenceInput.fingerprintOverride`:
+ * strings only, empty values dropped, at most 10 values, each scrubbed like
+ * the rest of the occurrence and then cut to 200 characters. A malformed
+ * override is dropped on its own; it never rejects the signal.
+ *
+ * `manualFingerprint` hashes it. `manual-v1` takes precedence over every
+ * other scheme (rule-v1, code-v1, frames-v3, message-v1) and is only ever
+ * computed here, never on the platform:
+ *
+ *   sha256("manual-v1" \0 service \0 values.join("\u0001")).hex()[:32]
+ */
+export declare const MANUAL_FINGERPRINT_SCHEME = "manual-v1";
+export declare const FINGERPRINT_ATTRIBUTE = "autter.fingerprint";
+export declare const MAX_FINGERPRINT_VALUES = 10;
+export declare const MAX_FINGERPRINT_VALUE_LENGTH = 200;
+/**
+ * The override values carried on the wire, cleaned: `value` is a string, a
+ * JSON array string, or an already-decoded array. Undefined when absent or
+ * unusable.
+ */
+export declare function parseFingerprintOverride(value: unknown): string[] | undefined;
+/** `{ fingerprintOverride }` to spread into an occurrence, or `{}`. */
+export declare function fingerprintOverrideOf(value: unknown): {
+    fingerprintOverride?: string[];
+};
+/**
+ * The `manual-v1` fingerprint (32 lowercase hex) of an occurrence's override,
+ * or null when it has none. The values are bounded again here (at most 10,
+ * each ≤ 200 chars), so the hash never depends on how the input was built.
+ */
+export declare function manualFingerprint(input: Pick<RuntimeOccurrenceInput, "service" | "fingerprintOverride">): string | null;

package/dist/fingerprint-override.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { scrubText } from "./redact.js";
+/**
+ * SDK fingerprint override (EI-16) → the `manual-v1` issue identity.
+ *
+ * Where it comes from:
+ * - browser events: `fingerprint` (a string or an array of strings), from
+ *   `captureException(err, { fingerprint })` or `beforeSend`;
+ * - OTLP exception events (or their span) and promoted error logs:
+ *   `autter.fingerprint`, a string or a JSON array of strings (the SDKs always
+ *   send the JSON array, so a single value never reads as a list by accident).
+ *
+ * The normalisers carry it as `RuntimeOccurrenceInput.fingerprintOverride`:
+ * strings only, empty values dropped, at most 10 values, each scrubbed like
+ * the rest of the occurrence and then cut to 200 characters. A malformed
+ * override is dropped on its own; it never rejects the signal.
+ *
+ * `manualFingerprint` hashes it. `manual-v1` takes precedence over every
+ * other scheme (rule-v1, code-v1, frames-v3, message-v1) and is only ever
+ * computed here, never on the platform:
+ *
+ *   sha256("manual-v1" \0 service \0 values.join("\u0001")).hex()[:32]
+ */
+export const MANUAL_FINGERPRINT_SCHEME = "manual-v1";
+export const FINGERPRINT_ATTRIBUTE = "autter.fingerprint";
+export const MAX_FINGERPRINT_VALUES = 10;
+export const MAX_FINGERPRINT_VALUE_LENGTH = 200;
+/** Strings only, empty dropped, first 10, each cut to 200 chars; null when none remain. */
+function boundValues(list, scrub) {
+    const values = list
+        .filter((value) => typeof value === "string" && value !== "")
+        .slice(0, MAX_FINGERPRINT_VALUES)
+        // Cut with slack, scrub, then cut: a secret straddling the limit is
+        // masked whole.
+        .map((value) => scrub(value.slice(0, MAX_FINGERPRINT_VALUE_LENGTH + 512)).slice(0, MAX_FINGERPRINT_VALUE_LENGTH))
+        .filter((value) => value !== "");
+    return values.length > 0 ? values : null;
+}
+/**
+ * The override values carried on the wire, cleaned: `value` is a string, a
+ * JSON array string, or an already-decoded array. Undefined when absent or
+ * unusable.
+ */
+export function parseFingerprintOverride(value) {
+    let list = value;
+    if (typeof value === "string" && /^\s*\[/.test(value)) {
+        try {
+            list = JSON.parse(value);
+        }
+        catch {
+            /* not JSON: one plain value */
+        }
+    }
+    return boundValues(Array.isArray(list) ? list : [list], scrubText) ?? undefined;
+}
+/** `{ fingerprintOverride }` to spread into an occurrence, or `{}`. */
+export function fingerprintOverrideOf(value) {
+    const values = parseFingerprintOverride(value);
+    return values ? { fingerprintOverride: values } : {};
+}
+/**
+ * The `manual-v1` fingerprint (32 lowercase hex) of an occurrence's override,
+ * or null when it has none. The values are bounded again here (at most 10,
+ * each ≤ 200 chars), so the hash never depends on how the input was built.
+ */
+export function manualFingerprint(input) {
+    if (!Array.isArray(input.fingerprintOverride))
+        return null;
+    const values = boundValues(input.fingerprintOverride, (text) => text);
+    if (!values)
+        return null;
+    return createHash("sha256")
+        .update(`${MANUAL_FINGERPRINT_SCHEME}\u0000${input.service}\u0000${values.join("\u0001")}`)
+        .digest("hex")
+        .slice(0, 32);
+}

package/dist/fingerprint-v3.d.ts

@@ -0,0 +1,54 @@
+import type { FingerprintCandidate, FingerprintRecord, RuntimeOccurrenceInput, StackFrame } from "./types.js";
+/**
+ * `frames-v3` — the structural issue identity (contract §2). Byte-for-byte
+ * shared with the platform mirror (`runtime-frames-fingerprint.ts`); the
+ * vectors in fingerprint-v3-vectors.json pin both.
+ *
+ * It hashes service + error type + up to five in-app frames reduced to
+ * `function@file`, where file is a lowercased basename with build hashes
+ * (`index-5f3a9c1e.js` → `index-*.js`) templated out. Line and column
+ * numbers, route, source (browser vs server) and release are never part of
+ * it, so one bug stays one issue across deploys, pages, preview domains and
+ * tiers. The normalised message is hashed only when no frame was picked.
+ */
+export declare const FRAMES_V3 = "frames-v3";
+/** §2.3 — the function half of a frame token. */
+export declare function frameTokenFunction(frame: Pick<StackFrame, "function" | "resolved">): string;
+/** §2.3 — the file half of a frame token. */
+export declare function frameTokenFile(frame: Pick<StackFrame, "filename" | "module">): string;
+export declare function frameToken(frame: StackFrame): string;
+/** §2.1–2.2 — in-app frames in order, else only the first frame; at most 5. */
+export declare function pickFrames(frames: StackFrame[]): StackFrame[];
+export interface FramesV3Input {
+    service: string;
+    errorType: string;
+    message: string;
+    frames: StackFrame[];
+}
+export interface FramesV3Result {
+    fingerprint: string;
+    record: FingerprintRecord;
+}
+export declare function framesV3Fingerprint(input: FramesV3Input): FramesV3Result;
+export interface OccurrenceIdentity {
+    /** Legacy identity, unchanged: what `fingerprint`/`fingerprintScheme` carry. */
+    legacy: {
+        fingerprint: string;
+        scheme: "message-v1" | "code-v1";
+    };
+    /** Every applicable scheme, highest precedence first; ends with the legacy one. */
+    candidates: FingerprintCandidate[];
+    /** What went into the frames-v3 fingerprint, when one was computed. */
+    record: FingerprintRecord | null;
+}
+/**
+ * The candidate list the sink carries (contract §1/§4), highest precedence
+ * first:
+ *   manual-v1 (SDK override) → code-v1 (valid error code) → frames-v3 →
+ *   message-v1 (legacy).
+ * A coded error's legacy identity IS code-v1, which outranks every auto
+ * scheme, so its list is [manual-v1?, code-v1]; an uncoded one is
+ * [manual-v1?, frames-v3, message-v1]. Either way the list ends with the
+ * legacy fingerprint, so the platform can always fall back to it.
+ */
+export declare function occurrenceIdentity(input: RuntimeOccurrenceInput, frames: StackFrame[]): OccurrenceIdentity;

package/dist/fingerprint-v3.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { normalizeMessage, occurrenceFingerprint } from "./fingerprint.js";
+import { manualFingerprint } from "./fingerprint-override.js";
+/**
+ * `frames-v3` — the structural issue identity (contract §2). Byte-for-byte
+ * shared with the platform mirror (`runtime-frames-fingerprint.ts`); the
+ * vectors in fingerprint-v3-vectors.json pin both.
+ *
+ * It hashes service + error type + up to five in-app frames reduced to
+ * `function@file`, where file is a lowercased basename with build hashes
+ * (`index-5f3a9c1e.js` → `index-*.js`) templated out. Line and column
+ * numbers, route, source (browser vs server) and release are never part of
+ * it, so one bug stays one issue across deploys, pages, preview domains and
+ * tiers. The normalised message is hashed only when no frame was picked.
+ */
+export const FRAMES_V3 = "frames-v3";
+const MAX_PICKED_FRAMES = 5;
+/** §2.3 — the function half of a frame token. */
+export function frameTokenFunction(frame) {
+    let fn = frame.function ?? "";
+    fn = fn.replace(/^async /, "");
+    fn = fn.replace(/^new /, "");
+    fn = fn.replace(/^(?:Object|Module)\./, "");
+    if (frame.resolved === false && fn.length <= 2)
+        fn = "";
+    if (fn === "<anonymous>" || fn === "anonymous")
+        fn = "";
+    return fn;
+}
+/** §2.3 — the file half of a frame token. */
+export function frameTokenFile(frame) {
+    let file = frame.filename ?? frame.module ?? "";
+    const cut = file.search(/[?#]/);
+    if (cut !== -1)
+        file = file.slice(0, cut);
+    file = file.slice(Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")) + 1);
+    file = file.replace(/[A-Za-z0-9]{8,}/g, (run) => /[0-9]/.test(run) || run === run.toUpperCase() ? "*" : run);
+    return file.toLowerCase();
+}
+export function frameToken(frame) {
+    return `${frameTokenFunction(frame)}@${frameTokenFile(frame)}`;
+}
+/** §2.1–2.2 — in-app frames in order, else only the first frame; at most 5. */
+export function pickFrames(frames) {
+    const inApp = frames.filter((frame) => frame.inApp === true);
+    const picked = inApp.length > 0 ? inApp : frames.slice(0, 1);
+    return picked.slice(0, MAX_PICKED_FRAMES);
+}
+export function framesV3Fingerprint(input) {
+    const tokens = pickFrames(input.frames).map(frameToken);
+    const message = tokens.length === 0 ? normalizeMessage(input.message) : "";
+    const fingerprint = createHash("sha256")
+        .update([FRAMES_V3, input.service, input.errorType, tokens.join("\u0001"), message].join("\u0000"))
+        .digest("hex")
+        .slice(0, 32);
+    return {
+        fingerprint,
+        record: {
+            scheme: FRAMES_V3,
+            parts: [input.errorType, ...tokens, message].filter((part) => part !== ""),
+        },
+    };
+}
+/**
+ * The candidate list the sink carries (contract §1/§4), highest precedence
+ * first:
+ *   manual-v1 (SDK override) → code-v1 (valid error code) → frames-v3 →
+ *   message-v1 (legacy).
+ * A coded error's legacy identity IS code-v1, which outranks every auto
+ * scheme, so its list is [manual-v1?, code-v1]; an uncoded one is
+ * [manual-v1?, frames-v3, message-v1]. Either way the list ends with the
+ * legacy fingerprint, so the platform can always fall back to it.
+ */
+export function occurrenceIdentity(input, frames) {
+    const legacy = occurrenceFingerprint(input);
+    const candidates = [];
+    const manual = manualFingerprint(input);
+    if (manual)
+        candidates.push({ scheme: "manual-v1", fingerprint: manual });
+    let record = null;
+    if (legacy.scheme === "code-v1") {
+        candidates.push({ scheme: "code-v1", fingerprint: legacy.fingerprint });
+    }
+    else {
+        const v3 = framesV3Fingerprint({
+            service: input.service,
+            errorType: input.errorType,
+            message: input.message,
+            frames,
+        });
+        record = v3.record;
+        candidates.push({ scheme: FRAMES_V3, fingerprint: v3.fingerprint });
+        candidates.push({ scheme: "message-v1", fingerprint: legacy.fingerprint });
+    }
+    return { legacy, candidates, record };
+}

package/dist/fingerprint.d.ts

@@ -2,7 +2,61 @@ import type { RuntimeOccurrenceInput } from "./types.js";
 export declare function normalizeMessage(message: string): string;
 /** Replace id-like path segments so /orders/812 and /orders/44 group. */
 export declare function normalizeRoute(route: string | null): string;
+/**
+ * Backend exceptions reach us in many native stack formats. The fingerprint
+ * groups by the top stack frames, so a format we cannot parse yields an EMPTY
+ * frame list — and then every error sharing a message collapses into one
+ * issue (two unrelated Go panics, say, become a single group). To keep
+ * unrelated defects apart, each officially-supported language is parsed and
+ * every frame reduced to a stable `function (file)` token that preserves the
+ * function, module and file.
+ *
+ * Volatile parts are stripped: line/column numbers, `+0x` offsets, pointer
+ * arguments and memory addresses. Line numbers are parsed but deliberately
+ * left OUT of the token — they shift on every re-deploy, and the JS path has
+ * always dropped them for exactly this reason, so the same defect stays one
+ * issue across rebuilds. The raw stack is retained verbatim on its own column.
+ *
+ * JavaScript/TypeScript, Firefox `@` frames and Python `File` frames keep
+ * their historical normalisation byte-for-byte (parseScriptFrames) so existing
+ * issues never regroup.
+ */
+export type StackLanguage = "go" | "rust" | "jvm" | "dotnet" | "script";
+/**
+ * Classify a whole stack by language. Signatures are chosen to be unique to
+ * each runtime so a JS or Python stack always falls through to "script".
+ */
+export declare function detectStackLanguage(lines: string[]): StackLanguage;
 export declare function normalizeStackFrames(stack: string | null, topN?: number): string[];
+/**
+ * Error codes (`autter.error.code`) — namespaced, stable, low-cardinality
+ * identifiers such as "billing.declined". Anything else (Node's "ECONNRESET",
+ * ids, free text) is not a code and the error groups by message as before.
+ * Shared spec: runtime-core and the Autter backend validate identically.
+ */
+export declare const CODE_PATTERN: RegExp;
+export declare const CODE_MAX_LENGTH = 80;
+export declare function validErrorCode(value: unknown): string | undefined;
+export type FingerprintScheme = "message-v1" | "code-v1";
+/**
+ * Scheme "code-v1": a SOURCE-INDEPENDENT issue identity for coded errors.
+ * Source, error type, message, stack and route are deliberately left out so
+ * the same code from the trace path, log promotion, the browser or an
+ * external connector (Sentry, PostHog, …) lands in ONE issue. Route and
+ * message stay as facets on the occurrence rows. Mirrored byte-for-byte by
+ * the backend (`runtime-code-fingerprint.ts`) — shared test vectors pin it.
+ */
+export declare function codeFingerprint(service: string, code: string): string;
+/**
+ * Issue identity plus the scheme that produced it. A valid
+ * `autter.error.code` selects "code-v1"; everything else keeps the
+ * historical message/stack/route fingerprint ("message-v1") byte-for-byte,
+ * so existing issues never regroup.
+ */
+export declare function occurrenceFingerprint(input: RuntimeOccurrenceInput): {
+    fingerprint: string;
+    scheme: FingerprintScheme;
+};
 export declare function fingerprintOccurrence(input: RuntimeOccurrenceInput): string;
 /**
  * Deterministic per-occurrence identity (as opposed to the fingerprint,

package/dist/fingerprint.js

@@ -70,7 +70,7 @@ const RUST_AT_RS_RE = /^\s*at\s+\S+\.rs:\d+/;
  * Classify a whole stack by language. Signatures are chosen to be unique to
  * each runtime so a JS or Python stack always falls through to "script".
  */
-function detectStackLanguage(lines) {
+export function detectStackLanguage(lines) {
     let hasDotnet = false;
     let hasJvm = false;
     let hasRust = false;
@@ -233,7 +233,52 @@ export function normalizeStackFrames(stack, topN = 5) {
     }
     return frames.length > 0 ? frames : fallbackFrames(lines, topN);
 }
+/**
+ * Error codes (`autter.error.code`) — namespaced, stable, low-cardinality
+ * identifiers such as "billing.declined". Anything else (Node's "ECONNRESET",
+ * ids, free text) is not a code and the error groups by message as before.
+ * Shared spec: runtime-core and the Autter backend validate identically.
+ */
+export const CODE_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+){0,3}$/;
+export const CODE_MAX_LENGTH = 80;
+export function validErrorCode(value) {
+    return typeof value === "string" &&
+        value.length <= CODE_MAX_LENGTH &&
+        CODE_PATTERN.test(value)
+        ? value
+        : undefined;
+}
+/**
+ * Scheme "code-v1": a SOURCE-INDEPENDENT issue identity for coded errors.
+ * Source, error type, message, stack and route are deliberately left out so
+ * the same code from the trace path, log promotion, the browser or an
+ * external connector (Sentry, PostHog, …) lands in ONE issue. Route and
+ * message stay as facets on the occurrence rows. Mirrored byte-for-byte by
+ * the backend (`runtime-code-fingerprint.ts`) — shared test vectors pin it.
+ */
+export function codeFingerprint(service, code) {
+    return createHash("sha256")
+        .update(`code-v1\u0000${service}\u0000${code}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * Issue identity plus the scheme that produced it. A valid
+ * `autter.error.code` selects "code-v1"; everything else keeps the
+ * historical message/stack/route fingerprint ("message-v1") byte-for-byte,
+ * so existing issues never regroup.
+ */
+export function occurrenceFingerprint(input) {
+    const code = validErrorCode(input.errorCode);
+    return code
+        ? { fingerprint: codeFingerprint(input.service, code), scheme: "code-v1" }
+        : { fingerprint: messageFingerprint(input), scheme: "message-v1" };
+}
 export function fingerprintOccurrence(input) {
+    return occurrenceFingerprint(input).fingerprint;
+}
+/** Scheme "message-v1" — the pre-1.5.0 fingerprint, unchanged. */
+function messageFingerprint(input) {
     const parts = [
         input.source,
         input.service,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createIngesterApp } from "./server.js";
 export { loadConfig } from "./config.js";
+export * from "./compat.js";
 export { SinkForwarder, type SinkStats, type SinkTuning } from "./sink.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,14 +1,15 @@
 import { loadConfig } from "./config.js";
 import { createIngesterApp } from "./server.js";
+import { ingesterVersion } from "./sdk-versions.js";
 const config = loadConfig();
-const { app, store, sink } = createIngesterApp(config);
+const { app, store, sink, reportIngesterInfo } = createIngesterApp(config);
 const server = app.listen(config.port, () => {
-    console.log(`autter otlp-ingester listening on :${config.port} ` +
+    console.log(`autter otlp-ingester ${ingesterVersion()} listening on :${config.port} ` +
         `(clickhouse: ${config.clickhouseUrl ? "configured" : "NOT configured"})`);
 });
 // Warm the schema at boot so the first ingest request doesn't pay for DDL.
 if (store.configured) {
-    store.ensureSchema().catch((err) => {
+    store.ensureSchema().then(reportIngesterInfo).catch((err) => {
         console.error("clickhouse schema bootstrap failed (will retry on first ingest):", err?.message ?? err);
     });
 }
@@ -32,5 +33,6 @@ process.on("SIGTERM", () => void shutdown("SIGTERM"));
 process.on("SIGINT", () => void shutdown("SIGINT"));
 export { createIngesterApp } from "./server.js";
 export { loadConfig } from "./config.js";
+export * from "./compat.js";
 export { SinkForwarder } from "./sink.js";
 export * from "./types.js";

package/dist/llm.js

@@ -1,4 +1,5 @@
 import { estimateLlmCostUsd } from "./llm-pricing.js";
+import { isSensitiveKey, scrubText } from "./redact.js";
 /**
  * LLM-call extraction from OTLP spans. Three attribute families are
  * recognised, so most stacks work with zero Autter-specific code:
@@ -101,12 +102,17 @@ export function extractLlmCall(attrs, facts) {
         errorType: facts.isError
             ? (strAttr(attrs, "error.type") ?? facts.exceptionType ?? "Error").slice(0, 200)
             : "",
-        userId: (strAttr(attrs, "autter.user_id", "ai.telemetry.metadata.userId", "ai.telemetry.metadata.user_id", "enduser.id", "user.id") ?? "").slice(0, 200),
-        sessionId: (strAttr(attrs, "autter.session_id", "ai.telemetry.metadata.sessionId", "session.id") ?? "").slice(0, 200),
+        userId: scrubText(strAttr(attrs, "autter.user_id", "ai.telemetry.metadata.userId", "ai.telemetry.metadata.user_id", "enduser.id", "user.id") ?? "").slice(0, 200),
+        sessionId: scrubText(strAttr(attrs, "autter.session_id", "ai.telemetry.metadata.sessionId", "session.id") ?? "").slice(0, 200),
         attributes: llmAttributeSubset(attrs),
         startedAt: facts.startedAt,
     };
 }
+/** Numeric token/usage counters are kept even though their keys contain
+ * "token" — cost tracking depends on them. */
+function isUsageCount(key, value) {
+    return /tokens?$|token_?count$|usage/i.test(key) && /^\d+(\.\d+)?$/.test(value);
+}
 /**
  * Drill-down context stored as JSON alongside the typed columns: only the
  * LLM-relevant attribute families, size-capped so a prompt accidentally
@@ -121,7 +127,14 @@ function llmAttributeSubset(attrs) {
             !key.startsWith("autter.llm.")) {
             continue;
         }
-        const trimmed = value.length > 500 ? `${value.slice(0, 500)}…` : value;
+        // Prompts/completions (ai.prompt, gen_ai.prompt, …) land here: scrub
+        // before the size cap so a secret straddling it can't half-survive.
+        const safe = isUsageCount(key, value)
+            ? value
+            : isSensitiveKey(key)
+                ? "[redacted]"
+                : scrubText(value);
+        const trimmed = safe.length > 500 ? `${safe.slice(0, 500)}…` : safe;
         size += key.length + trimmed.length;
         if (size > 4000)
             break;

package/dist/log-promotion.d.ts

@@ -0,0 +1,55 @@
+import type { RuntimeLogRecord } from "./logs.js";
+import type { RuntimeMetricPoint, RuntimeOccurrence, RuntimeOccurrenceInput } from "./types.js";
+/**
+ * Log promotion — errors from SDKs running WITHOUT a trace pipeline.
+ *
+ * Logger-only mode (`initAutterLogging`) and `@autter/runtime-edge` have no
+ * span to record an exception on, so they emit an error log record with
+ * `exception.*` and `autter.capture.mode = "log"`. /v1/logs turns those
+ * records into ordinary server occurrences (fingerprinted, stored in
+ * runtime_error_occurrences, forwarded to the sink) — otherwise their
+ * errors would never reach issue grouping.
+ *
+ * Dedupe, so one failure never becomes two occurrences through two export
+ * paths:
+ * - in-batch: at most one promoted occurrence per trace id (first wins);
+ * - cross-batch: a trace id that already produced an occurrence for this
+ *   tenant within ±PROMOTION_DEDUPE_WINDOW_MS (ClickHouse lookup) is skipped.
+ * Records without a trace id are always promoted. The lookup is
+ * best-effort and bounded (see promotionLookups, plus a per-tenant lookup
+ * budget in server.ts): when it fails, is skipped or is over budget the
+ * record is promoted anyway — a rare duplicate beats a silently dropped
+ * error.
+ */
+export declare const PROMOTION_DEDUPE_WINDOW_MS = 60000;
+/** Widest single lookup window. Candidate timestamps come from the client,
+ * so one batch could otherwise ask ClickHouse to scan an arbitrary range. */
+export declare const MAX_LOOKUP_SPAN_MS: number;
+/** At most this many lookup windows (queries) per request. */
+export declare const MAX_LOOKUP_WINDOWS = 4;
+/** Candidates outside [now − 24 h, now + 5 min] are never looked up: their
+ * trace cannot plausibly have a recent occurrence to dedupe against. */
+export declare const LOOKUP_PAST_MS: number;
+export declare const LOOKUP_FUTURE_MS: number;
+/** Promotion candidates in record order, deduped by trace id in-batch. */
+export declare function logPromotionCandidates(rows: RuntimeLogRecord[]): RuntimeOccurrenceInput[];
+export interface PromotionLookup {
+    from: Date;
+    to: Date;
+    traceIds: string[];
+}
+/**
+ * Bounded dedupe lookups for the candidates that carry a trace id: each
+ * window is [oldest − 60 s, newest + 60 s] over candidates taken newest first
+ * and spans at most MAX_LOOKUP_SPAN_MS; at most MAX_LOOKUP_WINDOWS windows are
+ * planned.
+ * Candidates outside the plausible time range or beyond the window cap are
+ * not looked up — they are still deduped in-batch and promoted.
+ */
+export declare function promotionLookups(occurrences: RuntimeOccurrenceInput[], now?: number): PromotionLookup[];
+/**
+ * One event / one error event per promoted occurrence — the same counting
+ * the trace path applies to occurrences outside a server span, so issue
+ * counters for logger-only services don't read 0.
+ */
+export declare function promotionRollups(occurrences: RuntimeOccurrence[]): RuntimeMetricPoint[];