@autter/otlp-ingester 1.4.0 → 1.5.0

package/dist/normalize-browser.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
+import { liftErrorFields } from "./error-fields.js";
+import { sanitizeRuntimeContext } from "./context.js";
 import { normalizeRoute } from "./fingerprint.js";
+import { scrubText } from "./redact.js";
 import { asSeverity, } from "./types.js";
 /**
  * The compact browser payload (`version: 1`) emitted by
@@ -34,6 +37,14 @@ const browserEventSchema = z.object({
     column: z.number().int().nonnegative().optional(),
     /** Path only; query strings are stripped defensively anyway. */
     route: z.string().max(1000).optional(),
+    /**
+     * Free-form, scrubbed context. runtime-browser ≥1.4.0 also sends the
+     * declared-error keys `autter.error.code|why|fix|link|expected` (from
+     * coded errors / `autterErrorFromResponse`) and `autter.request.id` (the
+     * `x-request-id` of a failed fetch/XHR). They are validated one by one
+     * in normalizeBrowserPayload — a malformed value is dropped on its own
+     * instead of rejecting the whole beacon.
+     */
     context: z.record(z.unknown()).optional(),
 });
 export const browserPayloadSchema = z.object({
@@ -42,6 +53,8 @@ export const browserPayloadSchema = z.object({
     service: z.string().min(1).max(200),
     environment: z.string().min(1).max(100),
     release: z.string().max(200).optional(),
+    /** @autter/runtime-browser version (1.4+); recorded for compatibility checks. */
+    sdk: z.string().regex(/^\d{1,6}\.\d{1,6}\.\d{1,6}[0-9A-Za-z.+-]{0,20}$/).optional().catch(undefined),
     events: z.array(browserEventSchema).max(50),
 });
 const TYPE_TO_ERROR_TYPE = {
@@ -53,25 +66,14 @@ const TYPE_TO_ERROR_TYPE = {
     csp_violation: "CspViolation",
 };
 // Content-level gate for the free-form `context` bag. The schema whitelist
-// above is structural; this masks obvious PII/secrets inside whatever a
-// (possibly outdated) SDK still sends: values under sensitive-looking keys
-// and email-shaped strings — mirroring redactAttributes() in
-// @autter/runtime-node and redactContext() in @autter/runtime-browser.
-const SENSITIVE_KEY_RE = /email|pass|token|secret|^auth([-_.]|$)|authorization|bearer|cookie|credential|api[-_.]?key|ssn|cvv|card([-_. ]?(number|num|no))?$/i;
-const EMAIL_VALUE_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+// above is structural; this masks secrets/PII inside whatever a (possibly
+// outdated) SDK still sends — sensitive keys and secret-shaped values at any
+// depth, via the same sanitiser as OTLP attributes. Message, stack, and route
+// are scrubbed centrally before fingerprinting (server.ts fingerprintAll).
+const EMAIL_VALUE_RE = /[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}/gi;
 const REDACTED = "[redacted]";
 function scrubContext(context) {
-    const out = {};
-    for (const [key, value] of Object.entries(context)) {
-        if (value === undefined || value === null)
-            continue;
-        out[key] = SENSITIVE_KEY_RE.test(key)
-            ? REDACTED
-            : typeof value === "string"
-                ? value.replace(EMAIL_VALUE_RE, REDACTED)
-                : value;
-    }
-    return out;
+    return sanitizeRuntimeContext(Object.fromEntries(Object.entries(context).filter(([, value]) => value !== undefined && value !== null)));
 }
 /** Default severity per event type when the SDK doesn't say. */
 const TYPE_TO_SEVERITY = {
@@ -86,6 +88,7 @@ export function normalizeBrowserPayload(payload) {
     const occurrences = [];
     const rollups = new Map();
     function bumpRollup(route, occurredAt, counts) {
+        route = scrubText(route);
         const bucketAt = new Date(Math.floor(occurredAt.getTime() / 60_000) * 60_000);
         const key = `${route} ${bucketAt.getTime()}`;
         const existing = rollups.get(key);
@@ -125,7 +128,7 @@ export function normalizeBrowserPayload(payload) {
             const name = event.name === "browser.longtask" ? "browser.longtask"
                 : `browser.resource:${normalizeRoute((event.name ?? "").replace(/^browser\.resource:/, "").split("?")[0].replace(EMAIL_VALUE_RE, REDACTED))}`;
             bumpRollup(name, occurredAt, { requestCount: 1 });
-            const point = rollups.get(`${name} ${Math.floor(occurredAt.getTime() / 60_000) * 60_000}`);
+            const point = rollups.get(`${scrubText(name)} ${Math.floor(occurredAt.getTime() / 60_000) * 60_000}`);
             if (point)
                 point.durationSumMs += event.durationMs ?? 0;
             continue;
@@ -162,6 +165,7 @@ export function normalizeBrowserPayload(payload) {
                 ...(event.context ? { context: scrubContext(event.context) } : {}),
             },
             occurredAt,
+            ...liftErrorFields(event.context),
         });
     }
     return { occurrences, metricPoints: [...rollups.values()] };

package/dist/normalize-otlp.js

@@ -1,8 +1,10 @@
 import { decodeOtlpAttributes, sanitizeRuntimeContext } from "./context.js";
+import { liftErrorFields, validRequestId } from "./error-fields.js";
+import { scrubText } from "./redact.js";
 import { normalizeRoute } from "./fingerprint.js";
 import { extractLlmCall } from "./llm.js";
 import { asSeverity, } from "./types.js";
-const EMAIL_VALUE_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+const EMAIL_VALUE_RE = /[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}/gi;
 function attrMap(attributes) {
     const map = new Map();
     for (const attr of attributes ?? []) {
@@ -127,7 +129,7 @@ export function normalizeTraces(request) {
                     traceId: span.traceId ?? "",
                     spanId: span.spanId ?? "",
                     parentSpanId: span.parentSpanId ?? null,
-                    name: span.name ?? "unnamed",
+                    name: scrubText(span.name ?? "unnamed").slice(0, 1000),
                     kind,
                     status: isError ? "error" : "ok",
                     route: route ? normalizeRoute(route) : null,
@@ -167,6 +169,9 @@ export function normalizeTraces(request) {
                         attributes: sanitizeRuntimeContext({ ...decodeOtlpAttributes(span.attributes), ...decodeOtlpAttributes(event.attributes),
                             ...(handled ? { "autter.handled": true, "autter.sampled": eventAttrs.get("autter.sampled") === "true" } : {}) }),
                         occurredAt: nanosToDate(event.timeUnixNano ?? span.startTimeUnixNano),
+                        // Event attributes first: one span can carry several
+                        // exceptions, each with its own code.
+                        ...liftErrorFields(eventAttrs, attrs),
                     });
                 }
                 const failedOutcomes = (span.events ?? []).filter((event) => {
@@ -187,6 +192,7 @@ export function normalizeTraces(request) {
                         traceId: span.traceId ?? null, sessionId: null,
                         attributes: sanitizeRuntimeContext({ ...decodeOtlpAttributes(span.attributes), ...decodeOtlpAttributes(event.attributes) }),
                         occurredAt: nanosToDate(event.timeUnixNano ?? span.startTimeUnixNano),
+                        ...liftErrorFields(outcome, attrs),
                     });
                 }
                 if (exceptionEvents.length === 0 && failedOutcomes.length === 0 && isError) {
@@ -209,6 +215,7 @@ export function normalizeTraces(request) {
                         sessionId: null,
                         attributes: decodeOtlpAttributes(span.attributes),
                         occurredAt: startedAt,
+                        ...liftErrorFields(attrs),
                     });
                 }
                 // LLM provider calls (GenAI semconv, Vercel AI SDK telemetry,
@@ -305,6 +312,11 @@ function inheritHttpFromParent(occurrences, occurrenceSpanIds, spans) {
             continue;
         if (!occurrence.route && http.route)
             occurrence.route = http.route;
+        // Request ids live on the request (server) span; child error spans
+        // from captureException inherit it so the issue links to the request.
+        const requestId = validRequestId(http.attributes?.["autter.request.id"]);
+        if (!occurrence.requestId && requestId)
+            occurrence.requestId = requestId;
         const method = methodFromSpan(http);
         if (!occurrence.method && method)
             occurrence.method = method;

package/dist/redact.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Server-side secret/PII scrubbing — the ingester's second line of defence.
+ *
+ * The SDKs scrub before anything leaves the customer's process, but the
+ * ingester also accepts older SDK versions and arbitrary third-party OTLP
+ * senders (any OTel SDK in any language) that scrub nothing. Everything this
+ * module touches is written to ClickHouse and forwarded to the sink webhook,
+ * which is where error context is later read for LLM-generated fixes — so
+ * scrubbing here, before storage, covers every downstream consumer.
+ *
+ * Same patterns as redactText() in @autter/runtime-node; parity is enforced
+ * by the shared test-vectors/redaction.json.
+ */
+import type { RuntimeOccurrenceInput } from "./types.js";
+/** Keys whose values are masked wholesale (tested case-insensitively). */
+export declare const SENSITIVE_KEY_RE: RegExp;
+/**
+ * Deployment-specific patterns on top of the built-ins (env
+ * AUTTER_REDACT_VALUE_PATTERNS / AUTTER_REDACT_KEY_PATTERNS, JSON arrays of
+ * regex sources). Server-side scrubbing has no off switch: it is the
+ * backstop for senders that don't scrub.
+ */
+export declare function configureRedaction(options: {
+    redactValuePatterns?: string[];
+    redactKeyPatterns?: string[];
+}): void;
+export declare function isSensitiveKey(key: string): boolean;
+export declare function scrubText(value: string): string;
+/** Nullable convenience for optional columns. */
+export declare function scrubOptional(value: string | null): string | null;
+/** Scrub the free-text fields of an occurrence (message, stack, route,
+ * error type). Returns a copy. */
+export declare function scrubOccurrence(occurrence: RuntimeOccurrenceInput): RuntimeOccurrenceInput;

package/dist/redact.js

@@ -0,0 +1,96 @@
+/**
+ * Server-side secret/PII scrubbing — the ingester's second line of defence.
+ *
+ * The SDKs scrub before anything leaves the customer's process, but the
+ * ingester also accepts older SDK versions and arbitrary third-party OTLP
+ * senders (any OTel SDK in any language) that scrub nothing. Everything this
+ * module touches is written to ClickHouse and forwarded to the sink webhook,
+ * which is where error context is later read for LLM-generated fixes — so
+ * scrubbing here, before storage, covers every downstream consumer.
+ *
+ * Same patterns as redactText() in @autter/runtime-node; parity is enforced
+ * by the shared test-vectors/redaction.json.
+ */
+const MASK = "[redacted]";
+const PRIVATE_KEY_BLOCK_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g;
+const PREFIXED_SECRET_RE = /\b(?:sk-[A-Za-z0-9_-]{20,}|(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{10,}|whsec_[A-Za-z0-9]{10,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AIza[A-Za-z0-9_-]{30,}|(?:AKIA|ASIA)[0-9A-Z]{16}|npm_[A-Za-z0-9]{36}|autter_(?:rt|pat)_[A-Za-z0-9_-]{10,}|SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,})/g;
+// Lookbehind, not \b: a \b start at every "eyJ" after a "-" made this
+// quadratic ("eyJ-" x 16k took 3.4 s per string).
+const JWT_RE = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g;
+const AUTH_SCHEME_RE = /\b(?:bearer\s+[A-Za-z0-9._~+/=-]{10,}|basic\s+(?=[A-Za-z0-9+/]*[0-9+/=])[A-Za-z0-9+/]{8,}={0,2})/gi;
+const HEADER_VALUE_RE = /((?:^|[^\w-])(?:proxy-)?(?:authorization|(?:set-)?cookie)["']?\s*[:=]\s*["']?)[^"'\r\n]+/gim;
+const SECRET_ASSIGNMENT_RE = /(password|passwd|pwd|passphrase|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|credential|signature|session[_-]?id|sessionid|ssn)(["']?\s*[:=]\s*)("[^"\r\n]*"|'[^'\r\n]*'|[^\s"'&,;)}\]\[<>]+)/gi;
+const URL_CREDENTIALS_RE = /\b([a-z][a-z0-9+.-]{0,31}:\/\/)(?:[^\s/:@"'<>]*:[^\s/"'<>]*|[^\s/:@"'<>]{16,})@/gi;
+const CARD_RE = /\b(?:4\d{3}|5[1-5]\d{2}|2[2-7]\d{2}|3[47]\d{2}|6(?:011|5\d{2}))(?:[ -]?\d){9,15}\b/g;
+const EMAIL_RE = /[A-Z0-9._%+-]{1,64}@[A-Z0-9.-]{1,253}\.[A-Z]{2,63}/gi;
+/** Keys whose values are masked wholesale (tested case-insensitively). */
+export const SENSITIVE_KEY_RE = /password|passwd|passphrase|(^|[._-])pwd$|secret|token|credential|authori[sz]ation|^auth(-|_|$)|bearer|cookie|e-?mail|phone|(^|[^a-z])ssn($|[^a-z])|cvv|card[._-]?number|connection[._-]?string|(^|[._-])dsn$|(api|access|private|client|signing|encryption)[._-]?key|apikey|(^|[._-])session$|^(j|php)?sess(ion)?id$|^sid$|connect\.sid|request[._-]?body|response[._-]?body|headers|url[._-]?query/i;
+let extraValuePatterns = [];
+let extraKeyPatterns = [];
+/**
+ * Deployment-specific patterns on top of the built-ins (env
+ * AUTTER_REDACT_VALUE_PATTERNS / AUTTER_REDACT_KEY_PATTERNS, JSON arrays of
+ * regex sources). Server-side scrubbing has no off switch: it is the
+ * backstop for senders that don't scrub.
+ */
+export function configureRedaction(options) {
+    extraValuePatterns = (options.redactValuePatterns ?? []).map((source) => new RegExp(source, "gi"));
+    extraKeyPatterns = (options.redactKeyPatterns ?? []).map((source) => new RegExp(source, "i"));
+}
+export function isSensitiveKey(key) {
+    return SENSITIVE_KEY_RE.test(key) || extraKeyPatterns.some((re) => re.test(key));
+}
+function luhnValid(candidate) {
+    const digits = candidate.replace(/\D/g, "");
+    if (digits.length < 13 || digits.length > 19)
+        return false;
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = digits.charCodeAt(digits.length - 1 - i) - 48;
+        if (i % 2 === 1) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return sum % 10 === 0;
+}
+/** Scrub secrets/PII embedded in one string; the rest of it survives. */
+/** Longest string scanned (same cap as the Node SDK). Callers that store
+ * less cut first; anything longer is truncated rather than stored unscanned. */
+const MAX_SCRUB_CHARS = 64 * 1024;
+export function scrubText(value) {
+    if (typeof value !== "string" || value === "")
+        return value;
+    let out = (value.length > MAX_SCRUB_CHARS ? value.slice(0, MAX_SCRUB_CHARS) : value)
+        .replace(PRIVATE_KEY_BLOCK_RE, MASK)
+        .replace(PREFIXED_SECRET_RE, MASK)
+        .replace(JWT_RE, MASK)
+        .replace(AUTH_SCHEME_RE, MASK)
+        .replace(HEADER_VALUE_RE, (_m, head) => head + MASK)
+        .replace(SECRET_ASSIGNMENT_RE, (_m, key, sep, val) => key + sep + (val[0] === '"' || val[0] === "'" ? val[0] + MASK + val[0] : MASK))
+        .replace(URL_CREDENTIALS_RE, (_m, scheme) => `${scheme}${MASK}@`)
+        .replace(CARD_RE, (m) => (luhnValid(m) ? MASK : m))
+        .replace(EMAIL_RE, MASK);
+    for (const re of extraValuePatterns) {
+        re.lastIndex = 0;
+        out = out.replace(re, MASK);
+    }
+    return out;
+}
+/** Nullable convenience for optional columns. */
+export function scrubOptional(value) {
+    return value === null ? null : scrubText(value);
+}
+/** Scrub the free-text fields of an occurrence (message, stack, route,
+ * error type). Returns a copy. */
+export function scrubOccurrence(occurrence) {
+    return {
+        ...occurrence,
+        errorType: scrubText(occurrence.errorType),
+        message: scrubText(occurrence.message),
+        stack: scrubOptional(occurrence.stack),
+        route: scrubOptional(occurrence.route),
+    };
+}

package/dist/sdk-versions.d.ts

@@ -0,0 +1,58 @@
+import type { IngestContext } from "./types.js";
+/** This ingester's own version (package.json — present in the npm package
+ * and the Docker image). */
+export declare function ingesterVersion(): string;
+export interface SdkSighting {
+    service: string;
+    environment: string;
+    sdkName: string;
+    sdkVersion: string;
+    sdkLanguage: string;
+}
+interface KeyValue {
+    key?: string;
+    value?: {
+        stringValue?: string;
+    };
+}
+interface ResourceHolder {
+    resource?: {
+        attributes?: KeyValue[];
+    };
+}
+export interface OtlpResourceRequest {
+    resourceSpans?: ResourceHolder[];
+    resourceMetrics?: ResourceHolder[];
+    resourceLogs?: ResourceHolder[];
+}
+/** SDK identity per OTLP resource. Reads only a handful of resource keys. */
+export declare function sdkSightingsFromOtlp(request: OtlpResourceRequest | null | undefined): SdkSighting[];
+export declare const BROWSER_SDK_NAME = "@autter/runtime-browser";
+export interface SdkVersionRow extends SdkSighting {
+    ingesterVersion: string;
+    seenAt: Date;
+}
+export interface SdkVersionTrackerOptions {
+    /** Re-write an unchanged sighting at most this often. Default 1 h. */
+    refreshMs?: number;
+    /** Dedupe map bound; cleared (not grown) past this. Default 10 000. */
+    maxKeys?: number;
+    now?: () => number;
+    onError?: (err: unknown) => void;
+}
+export declare class SdkVersionTracker {
+    private readonly write;
+    private readonly lastWritten;
+    private readonly refreshMs;
+    private readonly maxKeys;
+    private readonly now;
+    private readonly onError;
+    private lastErrorLog;
+    constructor(write: (ctx: IngestContext, rows: SdkVersionRow[]) => Promise<void>, options?: SdkVersionTrackerOptions);
+    /** Fire-and-forget. Returns the write promise (resolved) for tests. */
+    observe(ctx: IngestContext, sightings: SdkSighting[]): Promise<void>;
+}
+export declare function sdkVersionTableDDL(db: string, ttlDays?: number): string;
+/** One row per ingester version (latest report wins); not tenant data. */
+export declare function ingesterInfoTableDDL(db: string): string;
+export {};

package/dist/sdk-versions.js

@@ -0,0 +1,167 @@
+import { createRequire } from "node:module";
+/**
+ * Which SDK (name + version) each service sends with, recorded cheaply so the
+ * Autter dashboard and `/v1/compat` consumers can spot version mismatches.
+ *
+ * Sources, in priority order:
+ * - OTLP resource `telemetry.distro.name` / `telemetry.distro.version` — set
+ *   by `@autter/runtime-node` and `@autter/runtime-next` (OTel semconv for
+ *   SDK distributions);
+ * - otherwise `telemetry.sdk.language` / `telemetry.sdk.version` — any plain
+ *   OpenTelemetry SDK (Python, Go, Java, …), recorded as
+ *   `opentelemetry-<language>`;
+ * - browser payloads: the `sdk` field sent by `@autter/runtime-browser`.
+ *
+ * Writes are deduplicated in memory: one row per (tenant, service,
+ * environment, sdk, version) per `refreshMs`, bounded map, fire-and-forget —
+ * a failed write is logged and never fails ingest.
+ */
+let cachedVersion = null;
+/** This ingester's own version (package.json — present in the npm package
+ * and the Docker image). */
+export function ingesterVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const pkg = createRequire(import.meta.url)("../package.json");
+        cachedVersion = typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+const CLEAN = /^[\w.@/+:-]{1,100}$/;
+function clean(value, max = 100) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim().slice(0, max);
+    return CLEAN.test(trimmed) ? trimmed : "";
+}
+/** SDK identity per OTLP resource. Reads only a handful of resource keys. */
+export function sdkSightingsFromOtlp(request) {
+    if (!request || typeof request !== "object")
+        return [];
+    const holders = [
+        ...(Array.isArray(request.resourceSpans) ? request.resourceSpans : []),
+        ...(Array.isArray(request.resourceMetrics) ? request.resourceMetrics : []),
+        ...(Array.isArray(request.resourceLogs) ? request.resourceLogs : []),
+    ].slice(0, 64);
+    const out = [];
+    for (const holder of holders) {
+        const attrs = holder?.resource?.attributes;
+        if (!Array.isArray(attrs))
+            continue;
+        const get = {};
+        for (const attr of attrs.slice(0, 256)) {
+            const key = attr?.key;
+            const value = attr?.value?.stringValue;
+            if (typeof key === "string" && typeof value === "string" && key.length < 64)
+                get[key] = value;
+        }
+        const service = clean(get["service.name"], 200);
+        if (!service)
+            continue;
+        const language = clean(get["telemetry.sdk.language"]);
+        let sdkName = clean(get["telemetry.distro.name"]);
+        let sdkVersion = clean(get["telemetry.distro.version"]);
+        if (!sdkName || !sdkVersion) {
+            sdkVersion = clean(get["telemetry.sdk.version"]);
+            sdkName = sdkVersion ? `opentelemetry-${language || "unknown"}` : "";
+        }
+        if (!sdkName || !sdkVersion)
+            continue;
+        out.push({
+            service,
+            environment: clean(get["deployment.environment.name"]) ||
+                clean(get["deployment.environment"]) ||
+                "production",
+            sdkName,
+            sdkVersion,
+            sdkLanguage: language,
+        });
+    }
+    return out;
+}
+export const BROWSER_SDK_NAME = "@autter/runtime-browser";
+export class SdkVersionTracker {
+    write;
+    lastWritten = new Map();
+    refreshMs;
+    maxKeys;
+    now;
+    onError;
+    lastErrorLog = 0;
+    constructor(write, options = {}) {
+        this.write = write;
+        this.refreshMs = options.refreshMs ?? 60 * 60 * 1000;
+        this.maxKeys = options.maxKeys ?? 10_000;
+        this.now = options.now ?? Date.now;
+        this.onError =
+            options.onError ??
+                ((err) => {
+                    // One line per minute at most: a missing table on a broken schema
+                    // must not flood the logs on every ingest request.
+                    if (this.now() - this.lastErrorLog < 60_000)
+                        return;
+                    this.lastErrorLog = this.now();
+                    console.warn("sdk version tracking write failed:", err?.message ?? err);
+                });
+    }
+    /** Fire-and-forget. Returns the write promise (resolved) for tests. */
+    observe(ctx, sightings) {
+        if (!sightings.length)
+            return Promise.resolve();
+        const now = this.now();
+        const rows = [];
+        const keys = [];
+        for (const sighting of sightings) {
+            const key = [
+                ctx.orgId,
+                ctx.repositoryId,
+                sighting.service,
+                sighting.environment,
+                sighting.sdkName,
+                sighting.sdkVersion,
+            ].join("\u0000");
+            const last = this.lastWritten.get(key);
+            if (last !== undefined && now - last < this.refreshMs)
+                continue;
+            if (keys.includes(key))
+                continue;
+            keys.push(key);
+            rows.push({ ...sighting, ingesterVersion: ingesterVersion(), seenAt: new Date(now) });
+        }
+        if (!rows.length)
+            return Promise.resolve();
+        if (this.lastWritten.size + keys.length > this.maxKeys)
+            this.lastWritten.clear();
+        for (const key of keys)
+            this.lastWritten.set(key, now);
+        return this.write(ctx, rows).catch((err) => {
+            // Let the next request retry instead of waiting out refreshMs.
+            for (const key of keys)
+                this.lastWritten.delete(key);
+            this.onError(err);
+        });
+    }
+}
+export function sdkVersionTableDDL(db, ttlDays = 90) {
+    return `CREATE TABLE IF NOT EXISTS ${db}.runtime_sdk_versions (
+		org_id String, repository_id String, service LowCardinality(String),
+		environment LowCardinality(String), sdk_name LowCardinality(String),
+		sdk_version String, sdk_language LowCardinality(String) DEFAULT '',
+		ingester_version String DEFAULT '', last_seen DateTime('UTC')
+	) ENGINE = ReplacingMergeTree(last_seen)
+	ORDER BY (org_id, repository_id, service, environment, sdk_name, sdk_version)
+	TTL last_seen + INTERVAL ${ttlDays} DAY`;
+}
+/** One row per ingester version (latest report wins); not tenant data. */
+export function ingesterInfoTableDDL(db) {
+    return `CREATE TABLE IF NOT EXISTS ${db}.runtime_ingester_info (
+		ingester_version String, schema_level String DEFAULT '',
+		report String DEFAULT '{}' CODEC(ZSTD(1)), reported_at DateTime('UTC')
+	) ENGINE = ReplacingMergeTree(reported_at)
+	ORDER BY ingester_version
+	TTL reported_at + INTERVAL 90 DAY`;
+}

package/dist/server.d.ts

@@ -7,5 +7,8 @@ export interface IngesterApp {
     store: ClickHouseStore;
     /** Present when AUTTER_SINK_URL is configured. */
     sink: SinkForwarder | null;
+    /** Record this ingester's version + schema level in ClickHouse (for the
+     * Autter dashboard). Called after the boot schema warm-up; throttled. */
+    reportIngesterInfo: () => Promise<void>;
 }
 export declare function createIngesterApp(config: IngesterConfig): IngesterApp;