@autter/otlp-ingester 1.7.0 → 1.8.0

package/dist/request-spans.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which request each span of an export batch belongs to, so the span-fed
+ * usage rollups (`runtime_metrics_1m`) count one request once.
+ *
+ * A framework that opens its own SERVER span under the HTTP
+ * instrumentation's gives one request two server spans: Next.js's
+ * `BaseServer.handleRequest` span is a child of the HTTP server span, and
+ * some NestJS and Fastify setups and gRPC gateways serving RPCs in-process do
+ * the same. Each server span used to add a request, its latency and its error
+ * to the rollups, so every traced request of such an app counted twice.
+ *
+ * The request is the OUTERMOST server span. Walking up from a span through
+ * the parent links present in the batch, its request is the highest SERVER
+ * span reached. The walk stops:
+ *   - at a parent that is not in the batch: the span's own chain ends there,
+ *     so a server span whose parent is missing is a request of its own, as
+ *     before. When an exporter's timer splits one request's spans across two
+ *     batches, the nested server span therefore counts in its batch and the
+ *     outer one in the other; a batch cannot tell a parent exported elsewhere
+ *     from a remote caller;
+ *   - at a parent in another process (service, environment, release and
+ *     `service.instance.id`): one process serves one request;
+ *   - where a SERVER or CONSUMER span's parent is a CLIENT or PRODUCER span:
+ *     that edge is a call over the wire, a request of its own even when a
+ *     service calls itself.
+ */
+export interface RequestSpanLink {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    /** Lower-case OTel span kind: "server", "client", "internal", … */
+    kind: string;
+    /** The process the span was recorded in; spans of different processes
+     * are never one request. */
+    process: string;
+}
+export interface RequestMembership {
+    /** Per span: the batch index of its request's (outermost) server span,
+     * or -1 when no server span is on its chain. */
+    requestOf: number[];
+    /** Per span: how many parent links the walk followed above it (0 at the
+     * top of its chain). Nested spans are deeper than their request span. */
+    depth: number[];
+}
+export declare function requestMembership(spans: RequestSpanLink[]): RequestMembership;

package/dist/request-spans.js

@@ -0,0 +1,91 @@
+/**
+ * Which request each span of an export batch belongs to, so the span-fed
+ * usage rollups (`runtime_metrics_1m`) count one request once.
+ *
+ * A framework that opens its own SERVER span under the HTTP
+ * instrumentation's gives one request two server spans: Next.js's
+ * `BaseServer.handleRequest` span is a child of the HTTP server span, and
+ * some NestJS and Fastify setups and gRPC gateways serving RPCs in-process do
+ * the same. Each server span used to add a request, its latency and its error
+ * to the rollups, so every traced request of such an app counted twice.
+ *
+ * The request is the OUTERMOST server span. Walking up from a span through
+ * the parent links present in the batch, its request is the highest SERVER
+ * span reached. The walk stops:
+ *   - at a parent that is not in the batch: the span's own chain ends there,
+ *     so a server span whose parent is missing is a request of its own, as
+ *     before. When an exporter's timer splits one request's spans across two
+ *     batches, the nested server span therefore counts in its batch and the
+ *     outer one in the other; a batch cannot tell a parent exported elsewhere
+ *     from a remote caller;
+ *   - at a parent in another process (service, environment, release and
+ *     `service.instance.id`): one process serves one request;
+ *   - where a SERVER or CONSUMER span's parent is a CLIENT or PRODUCER span:
+ *     that edge is a call over the wire, a request of its own even when a
+ *     service calls itself.
+ */
+const UNSET = -2;
+function isRemoteCallEdge(child, parent) {
+    return (child === "server" || child === "consumer") && (parent === "client" || parent === "producer");
+}
+export function requestMembership(spans) {
+    const byKey = new Map();
+    spans.forEach((span, i) => {
+        if (!span.traceId || !span.spanId)
+            return;
+        const key = `${span.traceId}\u0000${span.spanId}`;
+        if (!byKey.has(key))
+            byKey.set(key, i);
+    });
+    /** The parent the walk may step to, or -1. */
+    const parentOf = (i) => {
+        const span = spans[i];
+        if (!span.traceId || !span.parentSpanId)
+            return -1;
+        const p = byKey.get(`${span.traceId}\u0000${span.parentSpanId}`);
+        if (p === undefined || p === i)
+            return -1;
+        const parent = spans[p];
+        if (parent.process !== span.process)
+            return -1;
+        if (isRemoteCallEdge(span.kind, parent.kind))
+            return -1;
+        return p;
+    };
+    const requestOf = new Array(spans.length).fill(UNSET);
+    const depth = new Array(spans.length).fill(0);
+    for (let start = 0; start < spans.length; start++) {
+        if (requestOf[start] !== UNSET)
+            continue;
+        // Walk up until a resolved span, the top of the chain, or a cycle
+        // (malformed parent links).
+        const path = [];
+        const onPath = new Set();
+        let above = -1;
+        let aboveDepth = -1;
+        let cur = start;
+        for (;;) {
+            path.push(cur);
+            onPath.add(cur);
+            const p = parentOf(cur);
+            if (p < 0 || onPath.has(p))
+                break;
+            if (requestOf[p] !== UNSET) {
+                above = requestOf[p];
+                aboveDepth = depth[p];
+                break;
+            }
+            cur = p;
+        }
+        // Resolve top-down: the outermost server span wins.
+        for (let k = path.length - 1; k >= 0; k--) {
+            const node = path[k];
+            if (above === -1 && spans[node].kind === "server")
+                above = node;
+            aboveDepth += 1;
+            requestOf[node] = above;
+            depth[node] = aboveDepth;
+        }
+    }
+    return { requestOf, depth };
+}

package/dist/sdk-versions.d.ts

@@ -8,7 +8,31 @@ export interface SdkSighting {
     sdkName: string;
     sdkVersion: string;
     sdkLanguage: string;
+    /** How it arrived (telemetryVia); '' when unknown. */
+    via: TelemetryVia;
 }
+/**
+ * How telemetry reached the ingester:
+ * - `collector`: forwarded by an OpenTelemetry Collector or a similar agent —
+ *   its User-Agent says so (any collector distribution: "OpenTelemetry
+ *   Collector Contrib/0.120.0 (linux/amd64)", ADOT's "AWS OTel Collector",
+ *   `otelcol-*` builds, Grafana Alloy / Agent, Fluent Bit, Vector), or the
+ *   resource's `telemetry.distro.name` is an otelcol build (the Autter
+ *   collector config inserts `otelcol-contrib` for senders that set none);
+ * - `direct`: an SDK exporter sent it itself (the `OTel-OTLP-Exporter-<lang>`
+ *   or Go `OTel Go OTLP …` User-Agent, or an Autter SDK's distro without a
+ *   collector User-Agent); browser events sent with a client key;
+ * - `relay`: browser events forwarded with a server key (the Autter relay);
+ * - '': nothing tells (another User-Agent, or none).
+ */
+export type TelemetryVia = "collector" | "direct" | "relay" | "";
+export declare function telemetryVia(input: {
+    userAgent?: string | null;
+    /** The resource's `telemetry.distro.name`, when it has one. */
+    distroName?: string | null;
+    /** The browser route: decided by the key (client key = the browser itself). */
+    browserKeyScope?: "server" | "client" | "upload" | null;
+}): TelemetryVia;
 interface KeyValue {
     key?: string;
     value?: {
@@ -25,8 +49,15 @@ export interface OtlpResourceRequest {
     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[];
+/**
+ * SDK identity per OTLP resource. Reads only a handful of resource keys.
+ * A resource with no SDK identity that came through a collector is still
+ * a sighting (empty name and version, `via: "collector"`), so a service fed
+ * by a collector receiver with no SDK (Prometheus, file logs) is seen too.
+ */
+export declare function sdkSightingsFromOtlp(request: OtlpResourceRequest | null | undefined, transport?: {
+    userAgent?: string | null;
+}): SdkSighting[];
 export declare const BROWSER_SDK_NAME = "@autter/runtime-browser";
 export interface SdkVersionRow extends SdkSighting {
     ingesterVersion: string;
@@ -52,6 +83,12 @@ export declare class SdkVersionTracker {
     /** Fire-and-forget. Returns the write promise (resolved) for tests. */
     observe(ctx: IngestContext, sightings: SdkSighting[]): Promise<void>;
 }
+/**
+ * Migration 0019 column — shared with the baseline DDL. Not in the sorting
+ * key (that can't change on a deployed table): a service+SDK+version row
+ * says how it arrived most recently.
+ */
+export declare const SDK_VERSION_VIA_COLUMN = "via LowCardinality(String) DEFAULT ''";
 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;

package/dist/sdk-versions.js

@@ -12,9 +12,16 @@ import { createRequire } from "node:module";
  *   `opentelemetry-<language>`;
  * - browser payloads: the `sdk` field sent by `@autter/runtime-browser`.
  *
+ * And how the telemetry arrived (`via`, 1.8.0): `collector` when an
+ * OpenTelemetry Collector (or a similar agent) forwarded it, `direct` when
+ * an SDK exporter sent it straight to the ingester, `relay` for browser
+ * payloads forwarded by a server-side relay; '' when it can't be told. So
+ * an Autter SDK behind a collector keeps its own name and is still seen as
+ * collector-fed. See `telemetryVia`.
+ *
  * 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.
+ * environment, sdk, version, via) 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
@@ -31,6 +38,20 @@ export function ingesterVersion() {
     }
     return cachedVersion;
 }
+const COLLECTOR_AGENT_RE = /(?:open[ -]?telemetry|\botel)[ -]?collector|^otelcol|^(?:grafana[ -])?alloy\/|grafana[ -]?agent|^fluent[ -]?bit|^vector\//i;
+const COLLECTOR_DISTRO_RE = /^otelcol(?:\b|[-_])|opentelemetry[-_ ]collector/i;
+const SDK_EXPORTER_AGENT_RE = /^OTel[- ]OTLP[- ]Exporter|^OTel \w+ OTLP/i;
+export function telemetryVia(input) {
+    const agent = (input.userAgent ?? "").trim().slice(0, 300);
+    const distro = (input.distroName ?? "").trim();
+    if (COLLECTOR_AGENT_RE.test(agent) || COLLECTOR_DISTRO_RE.test(distro))
+        return "collector";
+    if (input.browserKeyScope)
+        return input.browserKeyScope === "client" ? "direct" : "relay";
+    if (SDK_EXPORTER_AGENT_RE.test(agent) || distro.startsWith("@autter/"))
+        return "direct";
+    return "";
+}
 const CLEAN = /^[\w.@/+:-]{1,100}$/;
 function clean(value, max = 100) {
     if (typeof value !== "string")
@@ -38,8 +59,13 @@ function clean(value, max = 100) {
     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) {
+/**
+ * SDK identity per OTLP resource. Reads only a handful of resource keys.
+ * A resource with no SDK identity that came through a collector is still
+ * a sighting (empty name and version, `via: "collector"`), so a service fed
+ * by a collector receiver with no SDK (Prometheus, file logs) is seen too.
+ */
+export function sdkSightingsFromOtlp(request, transport = {}) {
     if (!request || typeof request !== "object")
         return [];
     const holders = [
@@ -63,14 +89,20 @@ export function sdkSightingsFromOtlp(request) {
         if (!service)
             continue;
         const language = clean(get["telemetry.sdk.language"]);
-        let sdkName = clean(get["telemetry.distro.name"]);
+        const distroName = clean(get["telemetry.distro.name"]);
+        let sdkName = distroName;
         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;
+        const via = telemetryVia({ userAgent: transport.userAgent, distroName });
+        if (!sdkName || !sdkVersion) {
+            if (via !== "collector")
+                continue;
+            sdkName = "";
+            sdkVersion = "";
+        }
         out.push({
             service,
             environment: clean(get["deployment.environment.name"]) ||
@@ -79,6 +111,7 @@ export function sdkSightingsFromOtlp(request) {
             sdkName,
             sdkVersion,
             sdkLanguage: language,
+            via,
         });
     }
     return out;
@@ -123,6 +156,7 @@ export class SdkVersionTracker {
                 sighting.environment,
                 sighting.sdkName,
                 sighting.sdkVersion,
+                sighting.via,
             ].join("\u0000");
             const last = this.lastWritten.get(key);
             if (last !== undefined && now - last < this.refreshMs)
@@ -146,12 +180,19 @@ export class SdkVersionTracker {
         });
     }
 }
+/**
+ * Migration 0019 column — shared with the baseline DDL. Not in the sorting
+ * key (that can't change on a deployed table): a service+SDK+version row
+ * says how it arrived most recently.
+ */
+export const SDK_VERSION_VIA_COLUMN = "via LowCardinality(String) DEFAULT ''";
 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')
+		ingester_version String DEFAULT '', last_seen DateTime('UTC'),
+		${SDK_VERSION_VIA_COLUMN}
 	) ENGINE = ReplacingMergeTree(last_seen)
 	ORDER BY (org_id, repository_id, service, environment, sdk_name, sdk_version)
 	TTL last_seen + INTERVAL ${ttlDays} DAY`;

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { type Express } from "express";
+import { IngestDropCounter } from "./ingest-drops.js";
 import { ClickHouseStore } from "./clickhouse.js";
 import type { IngesterConfig } from "./config.js";
 import { SinkForwarder } from "./sink.js";
@@ -10,6 +11,8 @@ export interface IngesterApp {
     /** Record this ingester's version + schema level in ClickHouse (for the
      * Autter dashboard). Called after the boot schema warm-up; throttled. */
     reportIngesterInfo: () => Promise<void>;
+    /** Rejection and drop counts per tenant (runtime_ingest_drops); `stop()` writes what is buffered. */
+    drops: IngestDropCounter;
 }
 /** The only routes an upload key (`autter_rtu_…`, scope "upload") may call. */
 export declare const UPLOAD_KEY_ROUTES: readonly ["/v1/sourcemaps", "/v1/sourcemaps/check"];