@autter/otlp-ingester 1.4.0 → 1.6.0

package/dist/compat-manifest.json

@@ -0,0 +1,123 @@
+{
+    "manifestVersion": 1,
+    "docs": "https://github.com/Autter-dev/autter-runtime/blob/main/docs/COMPATIBILITY.md",
+    "upgrade": {
+        "ingester": "docker pull ghcr.io/autter-dev/otlp-ingester:latest and restart it (ClickHouse migrations run at boot)",
+        "sdk": "npm install {package}@latest"
+    },
+    "features": [
+        {
+            "id": "llm_calls",
+            "title": "LLM call tracking",
+            "ingester": "1.1.0",
+            "migrations": ["0004-llm-calls"],
+            "sdks": { "@autter/runtime-node": "1.1.0", "@autter/runtime-next": "1.1.0" }
+        },
+        {
+            "id": "endpoint_latency",
+            "title": "Endpoint latency regression detection",
+            "ingester": "1.3.1",
+            "migrations": ["0005-latency-histograms"],
+            "sdks": { "@autter/runtime-node": "1.3.0", "@autter/runtime-next": "1.3.0" }
+        },
+        {
+            "id": "browser_network_events",
+            "title": "Browser network, timing and outcome capture",
+            "ingester": "1.3.2",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.3.2", "@autter/runtime-next": "1.3.2" },
+            "browserEvents": ["request_failure", "timing", "outcome"]
+        },
+        {
+            "id": "profiles",
+            "title": "Profile ingestion",
+            "ingester": "1.3.2",
+            "migrations": ["0006-profile-samples"],
+            "route": "/v1/profiles",
+            "sdks": {}
+        },
+        {
+            "id": "source_maps",
+            "title": "Source map upload",
+            "ingester": "1.3.2",
+            "migrations": ["0007-source-maps"],
+            "route": "/v1/sourcemaps",
+            "sdks": {}
+        },
+        {
+            "id": "memory_metrics",
+            "title": "Memory pressure detection",
+            "ingester": "1.3.3",
+            "migrations": ["0008-memory-signals", "0010-memory-temporality"],
+            "sdks": { "@autter/runtime-node": "1.3.3", "@autter/runtime-next": "1.3.3" }
+        },
+        {
+            "id": "platform_events",
+            "title": "Platform OOM/restart events",
+            "ingester": "1.3.3",
+            "migrations": ["0008-memory-signals"],
+            "route": "/v1/platform-events",
+            "sdks": {}
+        },
+        {
+            "id": "csp_violations",
+            "title": "Browser CSP violation capture",
+            "ingester": "1.3.4",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.3.3", "@autter/runtime-next": "1.3.4" },
+            "browserEvents": ["csp_violation"]
+        },
+        {
+            "id": "operation_logging",
+            "title": "Operation logging",
+            "ingester": "1.4.0",
+            "migrations": ["0011-runtime-logs"],
+            "route": "/v1/logs",
+            "sdks": { "@autter/runtime-node": "1.4.0", "@autter/runtime-next": "1.4.0" }
+        },
+        {
+            "id": "request_summaries",
+            "title": "Request summaries and the per-route request rollup",
+            "ingester": "1.5.0",
+            "migrations": ["0012-runtime-logs-requests", "0014-runtime-request-1m"],
+            "route": "/v1/logs",
+            "sdks": { "@autter/runtime-node": "1.5.0", "@autter/runtime-next": "1.5.0", "@autter/runtime-edge": "1.0.0" }
+        },
+        {
+            "id": "coded_errors",
+            "title": "Coded errors and code-based grouping",
+            "ingester": "1.5.0",
+            "migrations": ["0013-occurrence-codes"],
+            "sdks": { "@autter/runtime-node": "1.5.0", "@autter/runtime-next": "1.5.0", "@autter/runtime-browser": "1.4.0", "@autter/runtime-edge": "1.0.0" }
+        },
+        {
+            "id": "breadcrumbs",
+            "title": "Breadcrumbs: the steps before an error",
+            "ingester": "1.6.0",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-node": "1.6.0", "@autter/runtime-next": "1.6.0" }
+        },
+        {
+            "id": "source_map_debug_ids",
+            "title": "Source map debug ids",
+            "ingester": "1.6.0",
+            "migrations": ["0017-source-maps-debug-id"],
+            "route": "/v1/sourcemaps/check",
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-next": "1.6.0" }
+        },
+        {
+            "id": "fingerprint_override",
+            "title": "Fingerprint override",
+            "ingester": "1.6.0",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-node": "1.6.0", "@autter/runtime-next": "1.6.0", "@autter/runtime-edge": "1.1.0" }
+        },
+        {
+            "id": "browser_trace_propagation",
+            "title": "Browser trace propagation (browser errors linked to server traces)",
+            "ingester": "1.6.0",
+            "migrations": [],
+            "sdks": { "@autter/runtime-browser": "1.6.0", "@autter/runtime-next": "1.6.0", "@autter/runtime-node": "1.6.0" }
+        }
+    ]
+}

package/dist/compat.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Version compatibility between Autter Runtime SDKs, this ingester and its
+ * ClickHouse schema — the single source of truth.
+ *
+ * `compat-manifest.json` lists every feature that needs a minimum ingester
+ * version, a ClickHouse migration, a dedicated ingest route, or a minimum SDK
+ * version. Everything else derives from it:
+ *
+ * - the ingester serves it (evaluated against its own version and applied
+ *   migrations) at `GET /v1/compat`;
+ * - `@autter/runtime-node` / `@autter/runtime-next` bundle this file at build
+ *   time to warn once when an enabled feature needs a newer ingester, and to
+ *   power `npx @autter/runtime-node doctor`;
+ * - the Python adapter (`adapters/python/compat.py`) embeds a copy that a
+ *   parity test keeps identical.
+ *
+ * This module is dependency-free and side-effect-free on purpose: it is
+ * bundled into the Node SDK. Keep it that way.
+ *
+ * Adding a feature: append an entry to compat-manifest.json with the first
+ * ingester release that handles it, the migrations it writes to, its route
+ * (if it has its own), and the first SDK release that emits it. The
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
+ */
+export interface CompatFeature {
+    id: string;
+    title: string;
+    /** First ingester release that stores this feature correctly. */
+    ingester: string;
+    /** ClickHouse migrations (migrations.ts ids) the feature writes to. */
+    migrations: string[];
+    /** Dedicated ingest route, when the feature has one. */
+    route?: string;
+    /** First release of each SDK package that emits the feature. */
+    sdks: Record<string, string>;
+    /** Browser payload event types that belong to this feature. */
+    browserEvents?: string[];
+}
+export interface CompatManifest {
+    manifestVersion: number;
+    docs: string;
+    upgrade: {
+        ingester: string;
+        sdk: string;
+    };
+    features: CompatFeature[];
+}
+export declare const COMPAT_MANIFEST: CompatManifest;
+export declare const INGESTER_PACKAGE = "@autter/otlp-ingester";
+/** Response header carrying the ingester version on every ingest response. */
+export declare const INGESTER_VERSION_HEADER = "x-autter-ingester-version";
+/** Semver-ish comparison; null when either side is unparsable. */
+export declare function compareVersions(a: string, b: string): number | null;
+/** True/false when comparable, null when the version is unknown/unparsable. */
+export declare function versionAtLeast(version: string | null | undefined, minimum: string): boolean | null;
+export type SchemaStatus = "ready" | "pending" | "failed" | "unconfigured";
+/** What is known about the ingester an SDK talks to. */
+export interface IngesterCompatInfo {
+    /** Exact version, or null when the ingester predates /v1/compat. */
+    version: string | null;
+    /** True when /v1/compat returned 404 (ingester 1.4.0 or older). */
+    legacy?: boolean;
+    schema?: {
+        status: SchemaStatus;
+        applied: string[];
+    };
+    /** Legacy ingesters: route → exists, learned by probing. */
+    routes?: Record<string, boolean>;
+}
+export type CompatIssueKind = "ingester_too_old" | "schema_not_applied" | "sdk_too_old";
+export interface CompatIssue {
+    feature: string;
+    title: string;
+    kind: CompatIssueKind;
+    /** Package that must change: the ingester or an SDK package name. */
+    component: string;
+    required: string;
+    /** What was found ("1.3.4", "1.4.0 or older", …). */
+    actual: string;
+    /** One line: what is wrong, versions, and the fix. */
+    message: string;
+    fix: string;
+}
+export interface SdkIdentity {
+    name: string;
+    version: string;
+}
+export declare function featureById(id: string, manifest?: CompatManifest): CompatFeature | undefined;
+/** Features the given browser payload event types belong to. */
+export declare function featuresForBrowserEvents(types: Iterable<string>, manifest?: CompatManifest): string[];
+export declare function ingesterUpgradeHint(manifest?: CompatManifest): string;
+/**
+ * Every incompatibility for the features in use. Unknown is never an issue:
+ * when the ingester version can't be determined (and a legacy route probe
+ * didn't prove a route missing) nothing is reported, so the check has no
+ * false positives.
+ */
+export declare function evaluateCompat(input: {
+    features: Iterable<string>;
+    ingester: IngesterCompatInfo | null;
+    sdk?: SdkIdentity | null;
+    manifest?: CompatManifest;
+}): CompatIssue[];
+export interface CompatFeatureStatus {
+    id: string;
+    title: string;
+    ingester: string;
+    migrations: string[];
+    route?: string;
+    sdks: Record<string, string>;
+    browserEvents?: string[];
+    /** This ingester's version is new enough. */
+    ingesterSupported: boolean;
+    /** Migrations the feature needs that are not applied yet. */
+    missingMigrations: string[];
+    /** Ingester new enough AND schema ready with every migration applied. */
+    available: boolean;
+}
+export interface CompatReport {
+    ingester: {
+        name: string;
+        version: string;
+    };
+    schema: {
+        status: SchemaStatus;
+        /** Highest applied migration id ("" when none known). */
+        level: string;
+        /** Highest migration this ingester ships. */
+        latest: string;
+        applied: string[];
+    };
+    features: CompatFeatureStatus[];
+    manifestVersion: number;
+    docs: string;
+    upgrade: CompatManifest["upgrade"];
+    /** Present when the request named features (and optionally an SDK). */
+    issues?: CompatIssue[];
+}
+export declare function buildCompatReport(input: {
+    version: string;
+    schemaStatus: SchemaStatus;
+    applied: string[];
+    allMigrations: string[];
+    manifest?: CompatManifest;
+}): CompatReport;
+/** IngesterCompatInfo from a /v1/compat response body (defensive: it's network input). */
+export declare function ingesterInfoFromReport(body: unknown): IngesterCompatInfo | null;

package/dist/compat.js

@@ -0,0 +1,221 @@
+/**
+ * Version compatibility between Autter Runtime SDKs, this ingester and its
+ * ClickHouse schema — the single source of truth.
+ *
+ * `compat-manifest.json` lists every feature that needs a minimum ingester
+ * version, a ClickHouse migration, a dedicated ingest route, or a minimum SDK
+ * version. Everything else derives from it:
+ *
+ * - the ingester serves it (evaluated against its own version and applied
+ *   migrations) at `GET /v1/compat`;
+ * - `@autter/runtime-node` / `@autter/runtime-next` bundle this file at build
+ *   time to warn once when an enabled feature needs a newer ingester, and to
+ *   power `npx @autter/runtime-node doctor`;
+ * - the Python adapter (`adapters/python/compat.py`) embeds a copy that a
+ *   parity test keeps identical.
+ *
+ * This module is dependency-free and side-effect-free on purpose: it is
+ * bundled into the Node SDK. Keep it that way.
+ *
+ * Adding a feature: append an entry to compat-manifest.json with the first
+ * ingester release that handles it, the migrations it writes to, its route
+ * (if it has its own), and the first SDK release that emits it. The
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
+ */
+import manifestJson from "./compat-manifest.json" with { type: "json" };
+export const COMPAT_MANIFEST = manifestJson;
+export const INGESTER_PACKAGE = "@autter/otlp-ingester";
+/** Response header carrying the ingester version on every ingest response. */
+export const INGESTER_VERSION_HEADER = "x-autter-ingester-version";
+// ── versions ────────────────────────────────────────────────────────────
+/** [major, minor, patch, isPrerelease] or null when unparsable. */
+function parseVersion(version) {
+    if (typeof version !== "string")
+        return null;
+    const match = /^v?(\d{1,6})\.(\d{1,6})\.(\d{1,6})(-[0-9A-Za-z.-]+)?/.exec(version.trim());
+    if (!match)
+        return null;
+    return [
+        Number(match[1]),
+        Number(match[2]),
+        Number(match[3]),
+        // A prerelease sorts before its release: 1.4.0-rc.1 < 1.4.0.
+        match[4] ? 0 : 1,
+    ];
+}
+/** Semver-ish comparison; null when either side is unparsable. */
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 4; i++) {
+        if (left[i] !== right[i])
+            return left[i] < right[i] ? -1 : 1;
+    }
+    return 0;
+}
+/** True/false when comparable, null when the version is unknown/unparsable. */
+export function versionAtLeast(version, minimum) {
+    if (!version)
+        return null;
+    const result = compareVersions(version, minimum);
+    return result === null ? null : result >= 0;
+}
+export function featureById(id, manifest = COMPAT_MANIFEST) {
+    return manifest.features.find((feature) => feature.id === id);
+}
+/** Features the given browser payload event types belong to. */
+export function featuresForBrowserEvents(types, manifest = COMPAT_MANIFEST) {
+    const wanted = new Set(types);
+    return manifest.features
+        .filter((feature) => feature.browserEvents?.some((type) => wanted.has(type)))
+        .map((feature) => feature.id);
+}
+export function ingesterUpgradeHint(manifest = COMPAT_MANIFEST) {
+    return `Upgrade the ingester: ${manifest.upgrade.ingester}. See ${manifest.docs}`;
+}
+function sdkUpgradeHint(pkg, manifest) {
+    return `Upgrade the SDK: ${manifest.upgrade.sdk.replace("{package}", pkg)}. See ${manifest.docs}`;
+}
+/**
+ * Every incompatibility for the features in use. Unknown is never an issue:
+ * when the ingester version can't be determined (and a legacy route probe
+ * didn't prove a route missing) nothing is reported, so the check has no
+ * false positives.
+ */
+export function evaluateCompat(input) {
+    const manifest = input.manifest ?? COMPAT_MANIFEST;
+    const issues = [];
+    const seen = new Set();
+    for (const id of input.features) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const feature = featureById(id, manifest);
+        if (!feature)
+            continue;
+        const sdkMin = input.sdk ? feature.sdks[input.sdk.name] : undefined;
+        if (input.sdk && sdkMin && versionAtLeast(input.sdk.version, sdkMin) === false) {
+            const fix = sdkUpgradeHint(input.sdk.name, manifest);
+            issues.push({
+                feature: id,
+                title: feature.title,
+                kind: "sdk_too_old",
+                component: input.sdk.name,
+                required: sdkMin,
+                actual: input.sdk.version,
+                message: `${feature.title} needs ${input.sdk.name} >= ${sdkMin}; yours is ${input.sdk.version}. ${fix}`,
+                fix,
+            });
+        }
+        const ingester = input.ingester;
+        if (!ingester)
+            continue;
+        const fix = ingesterUpgradeHint(manifest);
+        const atLeast = versionAtLeast(ingester.version, feature.ingester);
+        if (atLeast === false) {
+            issues.push({
+                feature: id,
+                title: feature.title,
+                kind: "ingester_too_old",
+                component: INGESTER_PACKAGE,
+                required: feature.ingester,
+                actual: ingester.version,
+                message: `${feature.title} needs ingester >= ${feature.ingester}; yours is ${ingester.version}. ${fix}`,
+                fix,
+            });
+            continue;
+        }
+        if (ingester.version === null &&
+            feature.route &&
+            ingester.routes?.[feature.route] === false) {
+            const actual = "1.4.0 or older (no /v1/compat)";
+            issues.push({
+                feature: id,
+                title: feature.title,
+                kind: "ingester_too_old",
+                component: INGESTER_PACKAGE,
+                required: feature.ingester,
+                actual,
+                message: `${feature.title} needs ingester >= ${feature.ingester}; yours is ${actual} and has no ${feature.route} route, so this data is dropped. ${fix}`,
+                fix,
+            });
+            continue;
+        }
+        const schema = ingester.schema;
+        if (atLeast && schema && feature.migrations.length) {
+            const applied = new Set(schema.applied);
+            const missing = feature.migrations.filter((m) => !applied.has(m));
+            if (schema.status === "failed" || (schema.status === "ready" && missing.length)) {
+                const schemaFix = "Check the ingester's CLICKHOUSE_URL/credentials and its logs, then restart it so the boot migrations run. " +
+                    `See ${manifest.docs}`;
+                const what = missing.length ? missing.join(", ") : feature.migrations.join(", ");
+                issues.push({
+                    feature: id,
+                    title: feature.title,
+                    kind: "schema_not_applied",
+                    component: INGESTER_PACKAGE,
+                    required: feature.migrations.join(", "),
+                    actual: schema.status === "failed" ? "migrations failed" : `missing ${what}`,
+                    message: `${feature.title} needs ClickHouse migration ${what}, which ingester ${ingester.version} has not applied (schema ${schema.status}). ${schemaFix}`,
+                    fix: schemaFix,
+                });
+            }
+        }
+    }
+    return issues;
+}
+export function buildCompatReport(input) {
+    const manifest = input.manifest ?? COMPAT_MANIFEST;
+    const applied = new Set(input.applied);
+    const appliedOrdered = input.allMigrations.filter((id) => applied.has(id));
+    return {
+        ingester: { name: INGESTER_PACKAGE, version: input.version },
+        schema: {
+            status: input.schemaStatus,
+            level: appliedOrdered[appliedOrdered.length - 1] ?? "",
+            latest: input.allMigrations[input.allMigrations.length - 1] ?? "",
+            applied: appliedOrdered,
+        },
+        features: manifest.features.map((feature) => {
+            const ingesterSupported = versionAtLeast(input.version, feature.ingester) !== false;
+            const missingMigrations = feature.migrations.filter((m) => !applied.has(m));
+            return {
+                ...feature,
+                ingesterSupported,
+                missingMigrations,
+                available: ingesterSupported &&
+                    (feature.migrations.length === 0 ||
+                        (input.schemaStatus === "ready" && missingMigrations.length === 0)),
+            };
+        }),
+        manifestVersion: manifest.manifestVersion,
+        docs: manifest.docs,
+        upgrade: manifest.upgrade,
+    };
+}
+/** IngesterCompatInfo from a /v1/compat response body (defensive: it's network input). */
+export function ingesterInfoFromReport(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const report = body;
+    const version = report.ingester?.version;
+    if (typeof version !== "string" || !parseVersion(version))
+        return null;
+    const schema = report.schema;
+    const statuses = ["ready", "pending", "failed", "unconfigured"];
+    return {
+        version,
+        ...(schema && statuses.includes(schema.status) && Array.isArray(schema.applied)
+            ? {
+                schema: {
+                    status: schema.status,
+                    applied: schema.applied.filter((id) => typeof id === "string"),
+                },
+            }
+            : {}),
+    };
+}

package/dist/config.d.ts

@@ -32,10 +32,33 @@ export interface IngesterConfig {
     rateLimitPerMinute: number;
     /** Per-key requests per minute for publishable client keys. */
     clientRateLimitPerMinute: number;
+    /** ClickHouse dedupe lookups per tenant per minute for /v1/logs promotion. */
+    promotionLookupsPerMinute?: number;
     /** Retention, overridable per deployment. */
     occurrenceTtlDays: number;
     spanTtlDays: number;
     metricsTtlDays: number;
     llmCallTtlDays: number;
+    /**
+     * runtime_logs retention (LOG_TTL_DAYS, default 14). Request summaries are
+     * always kept (never sampled), so this is the main volume knob. Applied to
+     * fresh tables by the baseline and to existing ones at boot.
+     */
+    logTtlDays: number;
+    /**
+     * Extra regex sources scrubbed from stored/forwarded free text and
+     * attribute values, and extra regex sources for sensitive attribute
+     * keys — on top of the built-in secret/PII patterns (see redact.ts).
+     * Env: AUTTER_REDACT_VALUE_PATTERNS / AUTTER_REDACT_KEY_PATTERNS (JSON
+     * arrays of strings).
+     */
+    redactValuePatterns?: string[];
+    redactKeyPatterns?: string[];
+    /**
+     * In-memory budget (MiB, estimated decoded size) for parsed source maps
+     * used to symbolicate browser frames at ingest (SOURCE_MAP_CACHE_MB,
+     * default 64).
+     */
+    sourceMapCacheMb?: number;
 }
 export declare function loadConfig(): IngesterConfig;

package/dist/config.js

@@ -5,6 +5,20 @@ function intEnv(name, fallback) {
     const value = Number.parseInt(raw, 10);
     return Number.isFinite(value) && value > 0 ? value : fallback;
 }
+/** JSON array of regex sources; invalid input fails startup loudly rather
+ * than silently running without the operator's extra patterns. */
+function patternListEnv(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || !parsed.every((p) => typeof p === "string")) {
+        throw new Error(`${name} must be a JSON array of regex source strings`);
+    }
+    for (const source of parsed)
+        new RegExp(source);
+    return parsed;
+}
 function parseIngestKeys(raw) {
     if (!raw)
         return [];
@@ -42,12 +56,17 @@ export function loadConfig() {
         maxBodyBytes: intEnv("MAX_BODY_BYTES", 1024 * 1024),
         rateLimitPerMinute: intEnv("RATE_LIMIT_PER_MINUTE", 300),
         clientRateLimitPerMinute: intEnv("CLIENT_RATE_LIMIT_PER_MINUTE", 120),
+        promotionLookupsPerMinute: intEnv("PROMOTION_LOOKUPS_PER_MINUTE", 30),
         occurrenceTtlDays: intEnv("OCCURRENCE_TTL_DAYS", 14),
         spanTtlDays: intEnv("SPAN_TTL_DAYS", 7),
         metricsTtlDays: intEnv("METRICS_TTL_DAYS", 90),
         // LLM calls keep the metrics horizon, not the span one — cost trends
         // need months, and per-call volume is small next to HTTP spans.
         llmCallTtlDays: intEnv("LLM_CALL_TTL_DAYS", 90),
+        logTtlDays: intEnv("LOG_TTL_DAYS", 14),
+        redactValuePatterns: patternListEnv("AUTTER_REDACT_VALUE_PATTERNS"),
+        redactKeyPatterns: patternListEnv("AUTTER_REDACT_KEY_PATTERNS"),
+        sourceMapCacheMb: intEnv("SOURCE_MAP_CACHE_MB", 64),
     };
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.clickhouseDatabase)) {
         throw new Error(`Invalid CLICKHOUSE_DATABASE name: ${config.clickhouseDatabase}`);

package/dist/context.js

@@ -1,24 +1,32 @@
+import { isSensitiveKey, scrubText } from "./redact.js";
+import { BREADCRUMBS_ATTRIBUTE } from "./breadcrumbs.js";
 /** Bounded, defensive privacy boundary for custom telemetry from any OTLP SDK. */
 export function sanitizeRuntimeContext(input) {
     let budget = 512;
     const seen = new WeakSet();
-    const scrub = (value) => value
-        .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted]")
-        .replace(/\b(?:bearer\s+[A-Za-z0-9._~+\/=~-]{10,}|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|gh[pousr]_[A-Za-z0-9]{20,}|sk-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|autter_(?:rt|pat)_[A-Za-z0-9_-]{10,}|(?:AKIA|ASIA)[A-Z0-9]{16})\b/gi, "[redacted]")
-        .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, "[redacted]")
-        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi, "$1[redacted]@")
-        .replace(/(https?:\/\/[^\s?#]+)[?#][^\s]*/gi, "$1");
+    // Shared secret/PII patterns (redact.ts), then drop URL query strings
+    // and fragments outright — whitelist-style privacy for free text.
+    const scrub = (value) => scrubText(value)
+        // Query strings: procedural (a `[^\s?#]+[?#]` regex is quadratic on
+        // long runs of URLs without a query).
+        .replace(/https?:\/\/[^\s]*/gi, (url) => {
+        const rest = url.slice(url.indexOf("://") + 3);
+        const cut = rest.search(/[?#]/);
+        return cut <= 0 ? url : url.slice(0, url.length - rest.length + cut);
+    });
     const visit = (value, key, depth) => {
         if (--budget < 0 || depth > 6)
             return "[truncated]";
         if (/__proto__|constructor|prototype/i.test(key))
             return undefined;
-        const usage = /(?:^|\.)(?:input|output|total|prompt|completion)_?tokens$/i.test(key) &&
+        const usage = 
+        // Numeric token COUNTS (incl. the AI rollup's cache_read_tokens) are
+        // usage, not secrets.
+        /(?:^|\.)(?:input|output|total|prompt|completion|cache_read|cache_creation)_?tokens$/i.test(key) &&
             typeof value === "number" &&
             Number.isFinite(value) &&
             value >= 0;
-        if (!usage &&
-            /password|passwd|secret|token|credential|authorization|cookie|email|phone|ssn|card[._-]?number|connection[._-]?string|api[._-]?key|private[._-]?key|request[._-]?body|response[._-]?body|headers|url[._-]?query/i.test(key))
+        if (!usage && key && isSensitiveKey(key))
             return "[redacted]";
         if (typeof value === "string") {
             // Serialized custom context crosses the same privacy boundary as nested values.
@@ -33,7 +41,10 @@ export function sanitizeRuntimeContext(input) {
             const text = /(?:url|path|route|target)$/i.test(key)
                 ? value.split(/[?#]/)[0]
                 : value;
-            return scrub(text).slice(0, /stack/i.test(key) ? 32000 : 2048);
+            // Cut before scrubbing so scrub work is bounded by the stored size;
+            // the slack keeps a secret straddling the cut whole for the scrubber.
+            const limit = /stack/i.test(key) ? 32000 : 2048;
+            return scrub(text.slice(0, limit + 512)).slice(0, limit);
         }
         if (typeof value === "number")
             return Number.isFinite(value) ? value : undefined;
@@ -87,6 +98,8 @@ export function decodeOtlpAttributes(attributes) {
         .sort((a, b) => Number(/^autter\.(?:operation|event)\./.test(b.key ?? "")) -
         Number(/^autter\.(?:operation|event)\./.test(a.key ?? "")))
         .slice(0, 128)
-        .filter((a) => a.key && !/^(?:__proto__|constructor|prototype)$/.test(a.key))
+        .filter(
+    // Breadcrumbs are their own validated field (breadcrumbs.ts), never a plain attribute.
+    (a) => a.key && a.key !== BREADCRUMBS_ATTRIBUTE && !/^(?:__proto__|constructor|prototype)$/.test(a.key))
         .map((a) => [a.key, decode(a.value)])));
 }

package/dist/error-fields.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 declare const REQUEST_ID_PATTERN: RegExp;
+export interface DeclaredErrorFields {
+    errorCode?: string;
+    why?: string;
+    fix?: string;
+    link?: string;
+    expected?: boolean;
+    requestId?: string;
+}
+type AttributeSource = Map<string, string> | Record<string, unknown> | null | 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 declare function declaredLink(value: unknown): string | undefined;
+export declare function validRequestId(value: unknown): string | 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 declare function liftErrorFields(...sources: AttributeSource[]): DeclaredErrorFields;
+export {};