@autter/otlp-ingester 1.6.1 → 1.8.0

package/dist/ingest-drops.d.ts

@@ -0,0 +1,308 @@
+import type { IngestContext } from "./types.js";
+/**
+ * What the ingester refused or dropped, per tenant, per minute, by route and
+ * reason (EI-27): `runtime_ingest_drops` in ClickHouse, so the Autter
+ * dashboard can say why a repository's telemetry is missing instead of
+ * showing nothing.
+ *
+ * Four kinds of loss:
+ * - `rejected`: the whole request got a non-2xx answer and nothing from it
+ *   was stored (bad key, wrong key type, rate limit, invalid or oversized
+ *   payload, unsupported media type, storage down). 429 and 503 are retried
+ *   by OTLP exporters, so those records usually arrive later; the others
+ *   are not retried.
+ * - `dropped`: the request was accepted but some of its records were not
+ *   stored (spans past the per-request limit, cumulative HTTP histograms,
+ *   invalid browser events, …). OTLP answers carry them in `partialSuccess`.
+ * - `truncated`: records were stored with some attribute values cut or left
+ *   out by the attribute bounds; `records` counts the values cut.
+ * - `unforwarded`: stored in ClickHouse, but the sink webhook gave up on
+ *   the batch; the consumer recovers it by replaying ClickHouse.
+ *
+ * Counting never slows or fails ingest: `record()` is a synchronous map
+ * update, rows are written in batches every few seconds, a failed write is
+ * logged and dropped (never retried), and the buffer is bounded.
+ */
+export type DropKind = "rejected" | "dropped" | "truncated" | "unforwarded";
+/** Every reason, its kind, and (for rejections) the HTTP status it answers with. */
+export declare const DROP_REASONS: {
+    /** No key in `Authorization`, `x-autter-key` or `?key=`. */
+    readonly missing_key: {
+        readonly kind: "rejected";
+        readonly status: 401;
+    };
+    /** Not a configured key, and the validator did not accept it (revoked, mistyped, another repository's deployment). */
+    readonly unknown_key: {
+        readonly kind: "rejected";
+        readonly status: 401;
+    };
+    /** The key validator could not answer (unreachable, timeout, 5xx) and nothing was cached. */
+    readonly key_unverified: {
+        readonly kind: "rejected";
+        readonly status: 401;
+    };
+    /** An upload key (`autter_rtu_…`) on a telemetry route. */
+    readonly upload_key_not_allowed: {
+        readonly kind: "rejected";
+        readonly status: 403;
+    };
+    /** A client key (`autter_rtc_…`) on an OTLP or source map route. */
+    readonly client_key_not_allowed: {
+        readonly kind: "rejected";
+        readonly status: 403;
+    };
+    /** A client key sent from an origin missing from its allow-list. */
+    readonly origin_not_allowed: {
+        readonly kind: "rejected";
+        readonly status: 403;
+    };
+    /** A key whose scope this ingester does not know (never yielded by KeyResolver). */
+    readonly key_scope_not_allowed: {
+        readonly kind: "rejected";
+        readonly status: 403;
+    };
+    readonly rate_limited: {
+        readonly kind: "rejected";
+        readonly status: 429;
+    };
+    /** Malformed JSON or protobuf, a schema failure, or values the normaliser can't read. */
+    readonly invalid_payload: {
+        readonly kind: "rejected";
+        readonly status: 400;
+    };
+    /** The client went away before its body arrived. */
+    readonly request_aborted: {
+        readonly kind: "rejected";
+        readonly status: 400;
+    };
+    /** Body over MAX_BODY_BYTES (after gzip is inflated), or a source map over 32 MiB. */
+    readonly payload_too_large: {
+        readonly kind: "rejected";
+        readonly status: 413;
+    };
+    /** A content type or content encoding (zstd, br) the route does not take. */
+    readonly unsupported_media_type: {
+        readonly kind: "rejected";
+        readonly status: 415;
+    };
+    /** POST to a path the ingester does not serve (route "other"). */
+    readonly unknown_route: {
+        readonly kind: "rejected";
+        readonly status: 404;
+    };
+    readonly internal_error: {
+        readonly kind: "rejected";
+        readonly status: 500;
+    };
+    /** A ClickHouse write failed; exporters retry. */
+    readonly storage_unavailable: {
+        readonly kind: "rejected";
+        readonly status: 503;
+    };
+    /** Spans past the per-request limit (5000). */
+    readonly spans_over_limit: {
+        readonly kind: "dropped";
+    };
+    /** Log records past the per-request limit (2000). */
+    readonly log_records_over_limit: {
+        readonly kind: "dropped";
+    };
+    /** Data points of cumulative `http.server.duration` / `http.server.request.duration` histograms (only delta is summable). */
+    readonly cumulative_histogram: {
+        readonly kind: "dropped";
+    };
+    /** Memory/GC data points with a value, timestamp or unit out of range, or without service.name / service.instance.id. */
+    readonly memory_point_invalid: {
+        readonly kind: "dropped";
+    };
+    /** Memory/GC data points past 5000 in one request. */
+    readonly memory_points_over_limit: {
+        readonly kind: "dropped";
+    };
+    /** Browser events that failed validation (unknown type, bad timestamp, oversized field). */
+    readonly invalid_event: {
+        readonly kind: "dropped";
+    };
+    /** Browser events past 50 in one payload. */
+    readonly events_over_limit: {
+        readonly kind: "dropped";
+    };
+    /** Profile samples past the first 1000. */
+    readonly profile_samples_over_limit: {
+        readonly kind: "dropped";
+    };
+    readonly attributes_truncated: {
+        readonly kind: "truncated";
+    };
+    /** The sink retry buffer overflowed, or one batch was bigger than all of it. */
+    readonly sink_overflow: {
+        readonly kind: "unforwarded";
+    };
+    /** The sink consumer answered a permanent 4xx. */
+    readonly sink_rejected: {
+        readonly kind: "unforwarded";
+    };
+    /** SINK_MAX_ATTEMPTS deliveries failed. */
+    readonly sink_gave_up: {
+        readonly kind: "unforwarded";
+    };
+};
+export type DropReason = keyof typeof DROP_REASONS;
+/** Routes counted by name; anything else is "other". `sink` is the webhook. */
+export declare const DROP_ROUTES: readonly ["/v1/traces", "/v1/logs", "/v1/metrics", "/v1/browser", "/v1/profiles", "/v1/platform-events", "/v1/sourcemaps", "/v1/sourcemaps/check"];
+export type DropRoute = (typeof DROP_ROUTES)[number] | "other" | "sink";
+/** The route column for a request path (Express matches case-insensitively and ignores a trailing slash). */
+export declare function dropRoute(path: string): DropRoute;
+/** The HTTP status a reason is recorded with. `sink` has none (0). */
+export declare function dropStatus(reason: DropReason, route: DropRoute): number;
+/**
+ * sha256 (hex) of a key that did not resolve, when it has an Autter key
+ * prefix; "" otherwise. Autter stores the same hash for every key it issues
+ * (revoked ones included), so the platform can tell a repository that a
+ * revoked or rotated key is still sending, while the ingester never learns
+ * whose key it was. Anything without the prefix (another vendor's token, a
+ * password in the wrong field) is never hashed or stored.
+ */
+export declare function autterKeyHash(key: string): string;
+/**
+ * Count the length-delimited fields at a nested path of field numbers
+ * (one set per level) without decoding the message: tags are read and
+ * everything else is skipped by length. O(body size); null when the bytes
+ * are not a well-formed message.
+ */
+export declare function countProtoPath(buf: Uint8Array, path: readonly (readonly number[])[]): number | null;
+/**
+ * Records (spans, log records, data points, browser events) in a request
+ * body that was refused, where they can be known: 0 for a body never read
+ * (413, a bad encoding) or not understood. Profiles count samples, which a
+ * refused profile never had decoded, so 0; a source map upload or platform
+ * event is one record; a source map check carries none.
+ */
+export declare function recordsInBody(route: DropRoute, body: unknown, protobuf: boolean): number;
+/** Spans in an OTLP traces request (JSON-shaped, as decoded). */
+export declare function spansInRequest(request: unknown): number;
+/** Data points in an OTLP metrics request (JSON-shaped, as decoded). */
+export declare function dataPointsInRequest(request: unknown): number;
+/**
+ * Data points of cumulative HTTP server duration histograms: the request
+ * rollups (normalizeMetrics) and the latency table (normalizeLatencyHistograms)
+ * both skip them, since cumulative points repeat lifetime totals on every
+ * export. Mirrors normalizeMetrics' check; keep the two in step.
+ */
+export declare function cumulativeHttpHistogramPoints(request: unknown): number;
+/** What an accepted OTLP request did not store, for its `partial_success`. */
+export interface PartialSuccess {
+    /** rejected_spans / rejected_log_records / rejected_data_points. */
+    rejected: number;
+    errorMessage: string;
+}
+/** Merge per-reason rejections into one partial success; null when nothing was rejected. */
+export declare function partialSuccess(parts: Array<{
+    rejected: number;
+    message: string;
+}>): PartialSuccess | null;
+export declare const PARTIAL_MESSAGES: {
+    readonly spans: (rejected: number, limit: number) => string;
+    readonly logRecords: (rejected: number, limit: number) => string;
+    readonly cumulative: (rejected: number) => string;
+    readonly memoryInvalid: (rejected: number) => string;
+    readonly memoryOverLimit: (rejected: number, limit: number) => string;
+};
+/** A drop as recorded by the request path. */
+export interface IngestDrop {
+    /** Who sent it; null when the key did not resolve (or there was none). */
+    tenant: Pick<IngestContext, "orgId" | "repositoryId"> | null;
+    route: DropRoute;
+    reason: DropReason;
+    /** Requests (or sink batches); default 1. */
+    requests?: number;
+    /** Records lost (values cut, for `attributes_truncated`); default 0. */
+    records?: number;
+    /** The response status, when it differs from the reason's own. */
+    status?: number;
+    /** Null tenant only: autterKeyHash() of the key that did not resolve. */
+    keyHash?: string;
+}
+/** One `runtime_ingest_drops` row: a tenant, minute, route and reason. */
+export interface IngestDropRow {
+    orgId: string;
+    repositoryId: string;
+    minute: Date;
+    route: DropRoute;
+    reason: DropReason;
+    kind: DropKind;
+    status: number;
+    keyHash: string;
+    requests: number;
+    records: number;
+}
+export interface IngestDropCounterOptions {
+    /** How often buffered rows are written. Default 5 s. */
+    flushIntervalMs?: number;
+    /** Distinct rows buffered between writes; past it, new rows are not counted (and logged). Default 10 000. */
+    maxRows?: number;
+    /** Distinct key hashes buffered between writes; past it, a new one is counted with no hash. Default 1000. */
+    maxKeyHashes?: number;
+    /** A write that has not settled after this long counts as failed, so counting goes on. Default 30 s. */
+    writeTimeoutMs?: number;
+    /** False when there is no ClickHouse: nothing is buffered. */
+    enabled?: boolean;
+    now?: () => number;
+    log?: (message: string) => void;
+}
+export interface IngestDropCounterStats {
+    /** Rows waiting for the next write. */
+    buffered: number;
+    /** Rows written since start. */
+    written: number;
+    /** Writes that failed (their rows were dropped). */
+    failedWrites: number;
+    /** Rows dropped with a failed write. */
+    discardedRows: number;
+    /** Requests not counted because the buffer was full. */
+    overflowRequests: number;
+}
+export declare class IngestDropCounter {
+    private readonly write;
+    private rows;
+    private keyHashes;
+    private overflowRequests;
+    private overflowSinceLog;
+    private inFlight;
+    private timer;
+    private written;
+    private failedWrites;
+    private discardedRows;
+    private lastErrorLog;
+    private readonly flushIntervalMs;
+    private readonly maxRows;
+    private readonly maxKeyHashes;
+    private readonly writeTimeoutMs;
+    private readonly enabled;
+    private readonly now;
+    private readonly log;
+    constructor(write: (rows: IngestDropRow[]) => Promise<void>, options?: IngestDropCounterOptions);
+    /** Count a drop. Synchronous and O(1); never throws. */
+    record(drop: IngestDrop): void;
+    /** Write buffered rows every flushIntervalMs (unref'd: never keeps the process alive). */
+    start(): void;
+    /** Stop the timer and write what is buffered (shutdown). */
+    stop(): Promise<void>;
+    /**
+     * Write the buffered rows once. One write at a time: while one is in
+     * flight, rows keep accumulating (bounded) for the next. A failed or
+     * stalled write is logged and its rows dropped, never retried. Never
+     * rejects.
+     */
+    flush(): Promise<void>;
+    stats(): IngestDropCounterStats;
+}
+/**
+ * Migration 0018 / baseline. A SummingMergeTree: readers `sum(requests)`,
+ * `sum(records)` and GROUP BY, since rows of one key collapse at merge time,
+ * eventually. `org_id = '' AND repository_id = ''` is the null tenant: keys
+ * that did not resolve (401), with `key_hash` set for Autter-format keys.
+ * `status` is the HTTP status answered (2xx for drops inside accepted
+ * requests, 0 for the sink).
+ */
+export declare function ingestDropsTableDDL(db: string): string;