@schedulespark/observability 0.0.2-beta-1-0-0

package/dist/node/client.d.ts

@@ -0,0 +1,38 @@
+import type { MetricsApi } from "./metrics.js";
+import type { Transaction } from "./tracing.js";
+import type { NotificationChannel, SpikeMonitorOptions } from "../alerts/index.js";
+import type { BreadcrumbInput, CaptureInput, EventContext, EventLevel } from "../core/index.js";
+/**
+ * Options for initializing the Node observability client.
+ */
+export interface ObservabilityClientOptions {
+    connectionString: string;
+    schema?: string;
+    environment?: string;
+    release?: string;
+    project?: string;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+    beforeCapture?: (input: CaptureInput) => CaptureInput | null;
+    channels?: NotificationChannel[];
+    captureUncaughtExceptions?: boolean;
+    spikeMonitor?: Omit<SpikeMonitorOptions, "channels">;
+}
+/**
+ * The Node SDK's public capture API.
+ */
+export interface ObservabilityClient {
+    captureException: (error: unknown, context?: EventContext) => void;
+    captureMessage: (message: string, level?: EventLevel, context?: EventContext) => void;
+    addBreadcrumb: (breadcrumb: BreadcrumbInput) => void;
+    startTransaction: (name: string, tags?: Record<string, string>) => Transaction;
+    metrics: MetricsApi;
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+}
+/**
+ * Initializes the observability client. Returns immediately (storage connects and
+ * migrates in the background) so a slow or briefly unreachable database never delays
+ * host application startup; captures made before storage is ready are buffered.
+ */
+export declare function init(options: ObservabilityClientOptions): ObservabilityClient;

package/dist/node/client.js

@@ -0,0 +1,191 @@
+import { createNotifier, startSpikeMonitor } from "../alerts/index.js";
+import { captureInputSchema, createBreadcrumbBuffer, DEFAULT_PROJECT_ID } from "../core/index.js";
+import { closeStorage, initStorage, recordMetricPoint, recordSpan } from "../storage/index.js";
+import { exceptionToInput, messageToInput } from "./exception.js";
+import { createMetricsApi } from "./metrics.js";
+import { createCaptureQueue } from "./queue.js";
+import { redactSecrets } from "./redact.js";
+import { createTracer } from "./tracing.js";
+const DEFAULT_FLUSH_INTERVAL_MS = 2000;
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+/**
+ * Initializes the observability client. Returns immediately (storage connects and
+ * migrates in the background) so a slow or briefly unreachable database never delays
+ * host application startup; captures made before storage is ready are buffered.
+ */
+export function init(options) {
+    let handle;
+    let spikeMonitor;
+    const notifier = createNotifier(options.channels ?? []);
+    const ready = initStorage({ connectionString: options.connectionString, schema: options.schema })
+        .then((initialized) => {
+        handle = initialized;
+        if (options.spikeMonitor) {
+            spikeMonitor = startSpikeMonitor(initialized, { ...options.spikeMonitor, channels: options.channels ?? [] });
+        }
+    })
+        .catch((error) => {
+        console.error("[observability] failed to initialize storage", error);
+    });
+    const flushDeps = { notifier, projectId: options.project ?? DEFAULT_PROJECT_ID };
+    const { queue, spanQueue, metricQueue } = createQueues(options, ready, () => handle, flushDeps);
+    const tracer = createTracer(spanQueue);
+    const breadcrumbs = createBreadcrumbBuffer();
+    const capture = (input) => {
+        enqueueValidated(queue, applyDefaults({ ...input, breadcrumbs: breadcrumbs.snapshot() }, options), options.beforeCapture);
+    };
+    const client = {
+        captureException(error, context) {
+            capture(exceptionToInput(error, mergeContext(context, options)));
+        },
+        captureMessage(message, level = "info", context) {
+            capture(messageToInput(message, level, mergeContext(context, options)));
+        },
+        addBreadcrumb(breadcrumb) {
+            breadcrumbs.add({ ...breadcrumb, data: breadcrumb.data ? redactSecrets(breadcrumb.data) : undefined });
+        },
+        startTransaction: tracer.startTransaction,
+        metrics: createMetricsApi(metricQueue),
+        async flush() {
+            await Promise.all([queue.flush(), spanQueue.flush(), metricQueue.flush()]);
+        },
+        async close() {
+            spikeMonitor?.stop();
+            await Promise.all([queue.close(), spanQueue.close(), metricQueue.close()]);
+            await ready;
+            if (handle) {
+                await closeStorage(handle);
+            }
+        }
+    };
+    if (options.captureUncaughtExceptions) {
+        registerProcessCrashHandlers(client);
+    }
+    return client;
+}
+const CRASH_FLUSH_TIMEOUT_MS = 2000;
+/**
+ * Reports crashes that would otherwise never reach the SDK: an uncaught exception or
+ * unhandled rejection anywhere in the process, not just inside an instrumented
+ * request. Node stops terminating the process on its own once a listener is attached,
+ * so an uncaught exception is captured, given a bounded window to flush, and then the
+ * process is exited — preserving Node's normal crash-on-uncaught-exception behavior
+ * instead of leaving the process running in a possibly-corrupted state.
+ */
+function registerProcessCrashHandlers(client) {
+    process.on("uncaughtException", (error) => {
+        client.captureException(error);
+        void Promise.race([client.close(), delay(CRASH_FLUSH_TIMEOUT_MS)]).finally(() => {
+            process.exit(1);
+        });
+    });
+    process.on("unhandledRejection", (reason) => {
+        client.captureException(reason);
+    });
+}
+/**
+ * Resolves after `ms` milliseconds.
+ */
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Creates the three capture queues `init()` needs (events, spans, metrics), each
+ * flushed on the same interval/size limits — extracted out of `init()` itself to
+ * keep that function's complexity down.
+ */
+function createQueues(options, ready, getHandle, flushDeps) {
+    const flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    const maxQueueSize = options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+    return {
+        queue: createCaptureQueue({
+            flushIntervalMs,
+            maxQueueSize,
+            onFlush: (batch) => flushBatch(batch, ready, getHandle, flushDeps)
+        }),
+        spanQueue: createCaptureQueue({
+            flushIntervalMs,
+            maxQueueSize,
+            onFlush: (batch) => flushSpanBatch(batch, ready, getHandle)
+        }),
+        metricQueue: createCaptureQueue({
+            flushIntervalMs,
+            maxQueueSize,
+            onFlush: (batch) => flushMetricBatch(batch, ready, getHandle, flushDeps.projectId)
+        })
+    };
+}
+/**
+ * Waits for storage to be ready, then persists a batch of buffered captures, notifying
+ * any configured alert channels about newly created issues along the way.
+ */
+async function flushBatch(batch, ready, getHandle, deps) {
+    await ready;
+    const handle = getHandle();
+    if (!handle) {
+        return;
+    }
+    for (const input of batch) {
+        await deps.notifier.recordEvent(handle, input, deps.projectId);
+    }
+}
+/**
+ * Waits for storage to be ready, then persists a batch of finished transactions/spans.
+ */
+async function flushSpanBatch(batch, ready, getHandle) {
+    await ready;
+    const handle = getHandle();
+    if (!handle) {
+        return;
+    }
+    for (const span of batch) {
+        await recordSpan(handle, span);
+    }
+}
+/**
+ * Waits for storage to be ready, then persists a batch of queued metric points.
+ */
+async function flushMetricBatch(batch, ready, getHandle, projectId) {
+    await ready;
+    const handle = getHandle();
+    if (!handle) {
+        return;
+    }
+    for (const point of batch) {
+        await recordMetricPoint(handle, point, projectId);
+    }
+}
+/**
+ * Fills in `environment`/`release` on a context object from client defaults when the
+ * caller didn't set them explicitly.
+ */
+function mergeContext(context, options) {
+    return {
+        ...context,
+        environment: context?.environment ?? options.environment,
+        release: context?.release ?? options.release
+    };
+}
+/**
+ * Applies client-level defaults to a capture input's context.
+ */
+function applyDefaults(input, options) {
+    return { ...input, context: mergeContext(input.context, options) };
+}
+/**
+ * Validates a capture input against the wire schema, runs it through the caller's
+ * `beforeCapture` hook if provided, and enqueues it unless either step drops it.
+ */
+function enqueueValidated(queue, input, beforeCapture) {
+    const parsed = captureInputSchema.safeParse(input);
+    if (!parsed.success) {
+        console.error("[observability] dropped invalid capture", parsed.error.message);
+        return;
+    }
+    const filtered = beforeCapture ? beforeCapture(parsed.data) : parsed.data;
+    if (filtered) {
+        queue.enqueue(filtered);
+    }
+}

package/dist/node/exception.d.ts

@@ -0,0 +1,15 @@
+import type { CaptureInput, EventContext, EventLevel } from "../core/index.js";
+/**
+ * Normalizes any thrown value into an `Error` instance so callers can always read a
+ * `message`/`stack`, even for thrown strings or non-Error objects.
+ */
+export declare function toError(value: unknown): Error;
+/**
+ * Builds a capture payload from a thrown value and optional context, redacting
+ * likely-secret fields from the context before it's queued.
+ */
+export declare function exceptionToInput(error: unknown, context?: EventContext): CaptureInput;
+/**
+ * Builds a capture payload for a plain message (no exception involved).
+ */
+export declare function messageToInput(message: string, level: EventLevel, context?: EventContext): CaptureInput;

package/dist/node/exception.js

@@ -0,0 +1,33 @@
+import { redactSecrets } from "./redact.js";
+const DEFAULT_ERROR_MESSAGE = "Unknown error";
+/**
+ * Normalizes any thrown value into an `Error` instance so callers can always read a
+ * `message`/`stack`, even for thrown strings or non-Error objects.
+ */
+export function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Builds a capture payload from a thrown value and optional context, redacting
+ * likely-secret fields from the context before it's queued.
+ */
+export function exceptionToInput(error, context) {
+    const normalized = toError(error);
+    return {
+        level: "error",
+        message: normalized.message || DEFAULT_ERROR_MESSAGE,
+        errorType: normalized.name,
+        stackTrace: normalized.stack,
+        context: context ? redactSecrets(context) : undefined
+    };
+}
+/**
+ * Builds a capture payload for a plain message (no exception involved).
+ */
+export function messageToInput(message, level, context) {
+    return {
+        level,
+        message,
+        context: context ? redactSecrets(context) : undefined
+    };
+}

package/dist/node/fastify.d.ts

@@ -0,0 +1,7 @@
+import type { ObservabilityClient } from "./client.js";
+import type { FastifyInstance } from "fastify";
+/**
+ * Registers a Fastify `onError` hook that reports every request-lifecycle error to
+ * the observability client with method/route/status context attached.
+ */
+export declare function captureFastifyErrors(app: FastifyInstance, client: ObservabilityClient): void;

package/dist/node/fastify.js

@@ -0,0 +1,20 @@
+/**
+ * Registers a Fastify `onError` hook that reports every request-lifecycle error to
+ * the observability client with method/route/status context attached.
+ */
+export function captureFastifyErrors(app, client) {
+    app.addHook("onError", (request, reply, error, done) => {
+        client.captureException(error, requestContext(request, reply.statusCode));
+        done();
+    });
+}
+/**
+ * Builds event context from a Fastify request/response pair.
+ */
+function requestContext(request, statusCode) {
+    return {
+        method: request.method,
+        route: request.url,
+        statusCode
+    };
+}

package/dist/node/index.d.ts

@@ -0,0 +1,11 @@
+export { captureFastifyErrors } from "./fastify.js";
+export { init } from "./client.js";
+export { createPinoLogStream } from "./logs.js";
+export type { PinoLogStreamOptions } from "./logs.js";
+export type { MetricsApi } from "./metrics.js";
+export { instrumentPrismaClient } from "./prisma.js";
+export type { InstrumentPrismaClientOptions } from "./prisma.js";
+export { redactSecrets } from "./redact.js";
+export type { ObservabilityClient, ObservabilityClientOptions } from "./client.js";
+export type { Breadcrumb, BreadcrumbInput, LogEntry, LogLevel, MetricKind } from "../core/index.js";
+export type { Span, Transaction } from "./tracing.js";

package/dist/node/index.js

@@ -0,0 +1,5 @@
+export { captureFastifyErrors } from "./fastify.js";
+export { init } from "./client.js";
+export { createPinoLogStream } from "./logs.js";
+export { instrumentPrismaClient } from "./prisma.js";
+export { redactSecrets } from "./redact.js";

package/dist/node/logs.d.ts

@@ -0,0 +1,23 @@
+import { Writable } from "node:stream";
+import type { LogLevel } from "../core/index.js";
+import type { StorageHandle } from "../storage/index.js";
+/**
+ * Options for `createPinoLogStream`.
+ */
+export interface PinoLogStreamOptions {
+    /** Only lines at/above this level are forwarded (default `"warn"`). */
+    minLevel?: LogLevel;
+    projectId?: string;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+}
+/**
+ * Creates a `Writable` usable as pino's destination (`pino(opts, stream)`) that
+ * forwards log lines at/above `minLevel` into observability storage, batched and
+ * flushed the same non-blocking way every other capture path in this package is.
+ * Deliberately a plain stream rather than a worker-thread `pino.transport()` — the
+ * queue itself is already async/non-blocking, so a synchronous destination is
+ * simpler to build, test, and reason about without losing the "never block the host"
+ * guarantee.
+ */
+export declare function createPinoLogStream(handle: StorageHandle, options?: PinoLogStreamOptions): Writable;

package/dist/node/logs.js

@@ -0,0 +1,90 @@
+import { Writable } from "node:stream";
+import { recordLog } from "../storage/index.js";
+import { createCaptureQueue } from "./queue.js";
+const DEFAULT_FLUSH_INTERVAL_MS = 2000;
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+const DEFAULT_MIN_LEVEL = "warn";
+const PINO_LEVEL_LABELS = {
+    10: "trace",
+    20: "debug",
+    30: "info",
+    40: "warn",
+    50: "error",
+    60: "fatal"
+};
+const LOG_LEVEL_RANK = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60
+};
+/**
+ * Creates a `Writable` usable as pino's destination (`pino(opts, stream)`) that
+ * forwards log lines at/above `minLevel` into observability storage, batched and
+ * flushed the same non-blocking way every other capture path in this package is.
+ * Deliberately a plain stream rather than a worker-thread `pino.transport()` — the
+ * queue itself is already async/non-blocking, so a synchronous destination is
+ * simpler to build, test, and reason about without losing the "never block the host"
+ * guarantee.
+ */
+export function createPinoLogStream(handle, options = {}) {
+    const minRank = LOG_LEVEL_RANK[options.minLevel ?? DEFAULT_MIN_LEVEL];
+    const queue = createCaptureQueue({
+        flushIntervalMs: options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+        maxQueueSize: options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
+        onFlush: (batch) => flushLogBatch(handle, batch, options.projectId)
+    });
+    return new Writable({
+        write(chunk, _encoding, callback) {
+            for (const line of chunk.toString("utf8").split("\n")) {
+                const entry = line.trim().length > 0 ? parsePinoLine(line, minRank) : undefined;
+                if (entry) {
+                    queue.enqueue(entry);
+                }
+            }
+            callback();
+        },
+        // Flushes any buffered log lines when the stream is ended (e.g. at process
+        // shutdown) rather than waiting for the next interval tick — mirrors
+        // `ObservabilityClient.close()`'s flush-on-close behavior for the same reason.
+        final(callback) {
+            queue.close().then(() => {
+                callback();
+            }, (error) => {
+                callback(error instanceof Error ? error : new Error(String(error)));
+            });
+        }
+    });
+}
+/**
+ * Persists a batch of parsed log lines.
+ */
+async function flushLogBatch(handle, batch, projectId) {
+    for (const entry of batch) {
+        await recordLog(handle, entry, projectId);
+    }
+}
+/**
+ * Parses one pino NDJSON line into a `PendingLogEntry`, or `undefined` if it's below
+ * `minRank`, malformed, or otherwise unusable.
+ */
+function parsePinoLine(line, minRank) {
+    try {
+        const parsed = JSON.parse(line);
+        const rank = typeof parsed.level === "number" ? parsed.level : undefined;
+        if (rank === undefined || rank < minRank) {
+            return undefined;
+        }
+        const { level: _level, msg: _msg, time: _time, pid: _pid, hostname: _hostname, ...context } = parsed;
+        return {
+            level: PINO_LEVEL_LABELS[rank] ?? "info",
+            message: typeof parsed.msg === "string" ? parsed.msg : line,
+            context
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/node/metrics.d.ts

@@ -0,0 +1,27 @@
+import type { CaptureQueue } from "./queue.js";
+import type { MetricKind } from "../core/index.js";
+/**
+ * A metric point queued for storage — the same shape `storage/metrics-ingest.ts`'s
+ * `recordMetricPoint` accepts, before it generates an `id`/`recordedAt`.
+ */
+export interface PendingMetricPoint {
+    name: string;
+    kind: MetricKind;
+    value: number;
+    tags?: Record<string, string>;
+}
+/**
+ * StatsD-shaped metrics API, exposed as `client.metrics` on the Node SDK. Tags
+ * directly multiply row count — keep them to bounded-cardinality dimensions (e.g.
+ * `route`, `statusCode`), not free-form values like a user ID.
+ */
+export interface MetricsApi {
+    increment: (name: string, value?: number, tags?: Record<string, string>) => void;
+    gauge: (name: string, value: number, tags?: Record<string, string>) => void;
+    histogram: (name: string, value: number, tags?: Record<string, string>) => void;
+}
+/**
+ * Builds the `client.metrics` API bound to a capture queue, batched and flushed the
+ * same non-blocking way every other capture path in this package is.
+ */
+export declare function createMetricsApi(queue: CaptureQueue<PendingMetricPoint>): MetricsApi;

package/dist/node/metrics.js

@@ -0,0 +1,18 @@
+const DEFAULT_INCREMENT_VALUE = 1;
+/**
+ * Builds the `client.metrics` API bound to a capture queue, batched and flushed the
+ * same non-blocking way every other capture path in this package is.
+ */
+export function createMetricsApi(queue) {
+    return {
+        increment(name, value = DEFAULT_INCREMENT_VALUE, tags) {
+            queue.enqueue({ name, kind: "counter", value, tags });
+        },
+        gauge(name, value, tags) {
+            queue.enqueue({ name, kind: "gauge", value, tags });
+        },
+        histogram(name, value, tags) {
+            queue.enqueue({ name, kind: "histogram", value, tags });
+        }
+    };
+}

package/dist/node/prisma.d.ts

@@ -0,0 +1,63 @@
+import type { Transaction } from "./tracing.js";
+import type { BreadcrumbInput } from "../core/index.js";
+/**
+ * The minimal shape of a Prisma `query` client extension's `$allOperations` callback
+ * — duck-typed rather than imported from `@prisma/client`, since that's an optional
+ * peer dependency this package shouldn't need at compile time to build.
+ */
+interface AllOperationsParams {
+    model?: string;
+    operation: string;
+    args: unknown;
+    query: (args: unknown) => Promise<unknown>;
+}
+/**
+ * The minimal shape of a Prisma client this function needs: something extensible via
+ * `$extends`.
+ */
+interface ExtensibleClient {
+    $extends: (extension: {
+        query: {
+            $allModels: {
+                $allOperations: (params: AllOperationsParams) => Promise<unknown>;
+            };
+        };
+    }) => unknown;
+}
+/**
+ * Options for `instrumentPrismaClient`.
+ */
+export interface InstrumentPrismaClientOptions {
+    /**
+     * Returns the transaction to attach query spans to, or `undefined` if none is
+     * active. There's no `AsyncLocalStorage`-based context propagation in this package
+     * (a materially bigger, separately-scoped change touching every request boundary),
+     * so the caller is responsible for tracking "the active transaction" itself —
+     * spans are only recorded for queries issued while a transaction is supplied here.
+     */
+    getActiveTransaction?: () => Transaction | undefined;
+    /**
+     * Called with a `"db"` breadcrumb for every query, regardless of whether a
+     * transaction is active — the highest-value part of this feature, since it gives
+     * every captured exception "last N queries before this error" for free even
+     * without tracing wired up.
+     */
+    addBreadcrumb?: (breadcrumb: BreadcrumbInput) => void;
+    /**
+     * Query spans are only recorded when the query fails or takes at least this long
+     * (default 100ms) — breadcrumbs are recorded for every query regardless, but
+     * flooding the transactions view with thousands of fast `SELECT` spans isn't
+     * useful. Set to `0` to record every query as a span.
+     */
+    slowQueryThresholdMs?: number;
+}
+/**
+ * Wraps a Prisma client with a `$extends` query extension that times every query,
+ * recording a `"db"` breadcrumb for each one and (when a transaction is supplied via
+ * `getActiveTransaction`) a child span for slow or failed queries. Returns a new
+ * client — Prisma extensions can't mutate a client in place — so callers must use the
+ * returned value, not the original `prisma`. Never a dependency between `packages/db`
+ * and this package in either direction: the consuming app calls this itself.
+ */
+export declare function instrumentPrismaClient<T extends ExtensibleClient>(prisma: T, options?: InstrumentPrismaClientOptions): ReturnType<T["$extends"]>;
+export {};

package/dist/node/prisma.js

@@ -0,0 +1,53 @@
+const DEFAULT_SLOW_QUERY_THRESHOLD_MS = 100;
+/**
+ * Wraps a Prisma client with a `$extends` query extension that times every query,
+ * recording a `"db"` breadcrumb for each one and (when a transaction is supplied via
+ * `getActiveTransaction`) a child span for slow or failed queries. Returns a new
+ * client — Prisma extensions can't mutate a client in place — so callers must use the
+ * returned value, not the original `prisma`. Never a dependency between `packages/db`
+ * and this package in either direction: the consuming app calls this itself.
+ */
+export function instrumentPrismaClient(prisma, options = {}) {
+    const threshold = options.slowQueryThresholdMs ?? DEFAULT_SLOW_QUERY_THRESHOLD_MS;
+    return prisma.$extends({
+        query: {
+            $allModels: {
+                $allOperations: (params) => runInstrumentedQuery(params, options, threshold)
+            }
+        }
+    });
+}
+/**
+ * Runs a single Prisma query, timing it and reporting a breadcrumb/span as configured.
+ */
+async function runInstrumentedQuery(params, options, slowQueryThresholdMs) {
+    const name = `prisma.${params.model ?? "raw"}.${params.operation}`;
+    const start = Date.now();
+    try {
+        const result = await params.query(params.args);
+        reportQuery(options, { name, status: "ok", durationMs: Date.now() - start }, slowQueryThresholdMs);
+        return result;
+    }
+    catch (error) {
+        reportQuery(options, { name, status: "error", durationMs: Date.now() - start }, slowQueryThresholdMs);
+        throw error;
+    }
+}
+/**
+ * Records the breadcrumb (always) and span (when a transaction is active and either
+ * the query failed or was at/above the slow-query threshold) for one finished query.
+ */
+function reportQuery(options, outcome, slowQueryThresholdMs) {
+    const { name, status, durationMs } = outcome;
+    options.addBreadcrumb?.({
+        category: "db",
+        message: name,
+        level: status === "error" ? "error" : "info",
+        data: { durationMs }
+    });
+    if (status === "ok" && durationMs < slowQueryThresholdMs) {
+        return;
+    }
+    const transaction = options.getActiveTransaction?.();
+    transaction?.startSpan(name).finish(status);
+}

package/dist/node/queue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration for a bounded, batched queue.
+ */
+export interface CaptureQueueOptions<T> {
+    flushIntervalMs: number;
+    maxQueueSize: number;
+    onFlush: (batch: T[]) => Promise<void>;
+}
+/**
+ * A fire-and-forget queue: `enqueue` never blocks or throws, batches are flushed on a
+ * timer, and a storage failure is logged rather than propagated into the host app.
+ * Generic over item type so both event captures and finished spans can share one
+ * implementation.
+ */
+export interface CaptureQueue<T> {
+    enqueue: (item: T) => void;
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+}
+/**
+ * Creates a queue that buffers items in memory and flushes them in batches, dropping
+ * the oldest buffered item when full so a slow or unreachable database can never
+ * cause unbounded memory growth in the host process.
+ */
+export declare function createCaptureQueue<T>(options: CaptureQueueOptions<T>): CaptureQueue<T>;

package/dist/node/queue.js

@@ -0,0 +1,42 @@
+/**
+ * Creates a queue that buffers items in memory and flushes them in batches, dropping
+ * the oldest buffered item when full so a slow or unreachable database can never
+ * cause unbounded memory growth in the host process.
+ */
+export function createCaptureQueue(options) {
+    const buffer = [];
+    let flushing = false;
+    const flush = async () => {
+        if (flushing || buffer.length === 0) {
+            return;
+        }
+        flushing = true;
+        const batch = buffer.splice(0, buffer.length);
+        try {
+            await options.onFlush(batch);
+        }
+        catch (error) {
+            console.error("[observability] failed to flush queued items", error);
+        }
+        finally {
+            flushing = false;
+        }
+    };
+    const timer = setInterval(() => {
+        void flush();
+    }, options.flushIntervalMs);
+    timer.unref();
+    return {
+        enqueue(item) {
+            if (buffer.length >= options.maxQueueSize) {
+                buffer.shift();
+            }
+            buffer.push(item);
+        },
+        flush,
+        async close() {
+            clearInterval(timer);
+            await flush();
+        }
+    };
+}