@cat-factory/observability-otel 0.2.10

package/dist/mapping.js

@@ -0,0 +1,304 @@
+// The SINGLE source of truth for how a cat-factory observability event becomes
+// OpenTelemetry telemetry. BOTH transports import from here — the workerd-safe fetch
+// exporter (`./index`) and the official-SDK exporter (`./node`) — so the attribute keys,
+// metric names/units, span shape, trace-id grouping and timestamps they emit are
+// identical by construction. `src/conformity.test.ts` feeds the same events through both
+// and asserts the emitted telemetry matches; this module is why that holds.
+//
+// Nothing here depends on `@opentelemetry/*` or on any runtime API beyond the `crypto`
+// global (present on both workerd and Node), so it stays importable from the fetch entry
+// that must not pull the Node-only SDK into the Worker bundle.
+/** Default OTLP resource `service.name`; overridable via `OTEL_SERVICE_NAME`. */
+export const DEFAULT_SERVICE_NAME = 'cat-factory';
+/** The instrumentation scope name stamped on every emitted span/metric. */
+export const SCOPE_NAME = '@cat-factory/observability-otel';
+/**
+ * Attribute keys, following the OpenTelemetry GenAI semantic conventions where they exist
+ * (`gen_ai.*`) plus a small `cat_factory.*` namespace for our own dimensions. Centralised
+ * so the two transports can never disagree on a key.
+ */
+export const ATTR = {
+    system: 'gen_ai.system',
+    requestModel: 'gen_ai.request.model',
+    inputTokens: 'gen_ai.usage.input_tokens',
+    outputTokens: 'gen_ai.usage.output_tokens',
+    finishReasons: 'gen_ai.response.finish_reasons',
+    tokenType: 'gen_ai.token.type',
+    workspaceId: 'cat_factory.workspace_id',
+    agentKind: 'cat_factory.agent_kind',
+    serviceName: 'service.name',
+};
+/** Metric names + units (OTel GenAI client metrics). */
+export const METRIC = {
+    tokenUsage: 'gen_ai.client.token.usage',
+    duration: 'gen_ai.client.operation.duration',
+};
+export const TOKEN_UNIT = '{token}';
+export const DURATION_UNIT = 's';
+/** Span event names carrying the prompt / completion bodies (only when recorded). */
+const EVENT = {
+    prompt: 'gen_ai.content.prompt',
+    completion: 'gen_ai.content.completion',
+};
+const EVENT_ATTR = {
+    prompt: 'gen_ai.prompt',
+    completion: 'gen_ai.completion',
+};
+/** Hex-encode `bytes` random bytes via the `crypto` global (both workerd and Node). */
+function randomHex(bytes) {
+    const arr = new Uint8Array(bytes);
+    crypto.getRandomValues(arr);
+    let out = '';
+    for (const b of arr)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/**
+ * Deterministic hex of `bytes` bytes from a string, so every call of a run derives the
+ * SAME trace id and the backend groups them into one trace — the fetch and SDK transports
+ * therefore agree without sharing state. FNV-1a, re-hashed with a counter salt to fill the
+ * width. Guaranteed non-zero (OTLP rejects an all-zero id).
+ */
+function hashHex(input, bytes) {
+    let out = '';
+    for (let i = 0; out.length < bytes * 2; i++) {
+        let h = 0x811c9dc5;
+        const salted = `${i}:${input}`;
+        for (let j = 0; j < salted.length; j++) {
+            h ^= salted.charCodeAt(j);
+            h = Math.imul(h, 0x01000193);
+        }
+        out += (h >>> 0).toString(16).padStart(8, '0');
+    }
+    out = out.slice(0, bytes * 2);
+    return /^0+$/.test(out) ? `${out.slice(0, -1)}1` : out;
+}
+export function randomTraceId() {
+    return randomHex(16);
+}
+export function randomSpanId() {
+    return randomHex(8);
+}
+/** The trace id a call belongs to: derived from its run, else a fresh standalone id. */
+function deriveTraceId(executionId) {
+    return executionId ? hashHex(executionId, 16) : randomTraceId();
+}
+/** Epoch ms → OTLP unix-nano string (string arithmetic avoids float precision loss). */
+export function toUnixNano(ms) {
+    return `${Math.round(ms)}000000`;
+}
+/**
+ * The LOW-cardinality dimensions safe to carry on a metric time series: provider, model,
+ * and agent kind are all bounded sets. Deliberately EXCLUDES the workspace id — it is
+ * unbounded (one value per tenant), so putting it on a metric would explode the backend's
+ * time-series cardinality (and cost). The workspace id belongs on spans, where high
+ * cardinality is expected; see {@link generationDimensions}.
+ */
+function metricDimensions(event) {
+    return {
+        [ATTR.system]: event.provider,
+        [ATTR.requestModel]: event.model,
+        [ATTR.agentKind]: event.agentKind,
+    };
+}
+/** The dimensions on a generation's SPAN: the metric dimensions plus the workspace id. */
+function generationDimensions(event) {
+    const attrs = metricDimensions(event);
+    if (event.workspaceId)
+        attrs[ATTR.workspaceId] = event.workspaceId;
+    return attrs;
+}
+/** Map one completed LLM call to a neutral span. */
+export function mapGeneration(event) {
+    const attributes = {
+        ...generationDimensions(event),
+        [ATTR.inputTokens]: event.promptTokens,
+        [ATTR.outputTokens]: event.completionTokens,
+    };
+    if (event.finishReason)
+        attributes[ATTR.finishReasons] = [event.finishReason];
+    const events = [];
+    // Bodies are present only when prompt recording is on (upstream blanks them otherwise),
+    // so an empty string means "not recorded" and is omitted — matching the Langfuse sink.
+    if (event.input) {
+        events.push({
+            name: EVENT.prompt,
+            timeMs: event.startedAt,
+            attributes: { [EVENT_ATTR.prompt]: event.input },
+        });
+    }
+    if (event.output) {
+        events.push({
+            name: EVENT.completion,
+            timeMs: event.endedAt,
+            attributes: { [EVENT_ATTR.completion]: event.output },
+        });
+    }
+    return {
+        traceId: deriveTraceId(event.executionId),
+        name: event.agentKind,
+        startTimeMs: event.startedAt,
+        endTimeMs: event.endedAt,
+        ok: event.ok,
+        ...(event.ok ? {} : { statusMessage: event.errorMessage ?? undefined }),
+        attributes,
+        events,
+    };
+}
+/** Map one completed LLM call to its token-usage + duration metrics. */
+export function mapGenerationMetrics(event) {
+    // Metrics use the low-cardinality dimensions only (no workspace id) — see metricDimensions.
+    const dims = metricDimensions(event);
+    return {
+        tokenUsage: [
+            { value: event.promptTokens, attributes: { ...dims, [ATTR.tokenType]: 'input' } },
+            { value: event.completionTokens, attributes: { ...dims, [ATTR.tokenType]: 'output' } },
+        ],
+        durationSeconds: Math.max(0, event.endedAt - event.startedAt) / 1000,
+        durationAttributes: dims,
+        startTimeMs: event.startedAt,
+        endTimeMs: event.endedAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// Platform-operator observability → OpenTelemetry metrics. The dual of the per-run
+// generation metrics above: where those describe ONE LLM call, these describe the
+// deployment's aggregate run health (outcomes, failure taxonomy, live/parked depth,
+// durations) over a trailing window, scoped to an account. A periodic sweep computes the
+// `PlatformObservability` projection and feeds it here; the fetch exporter (`./platform`)
+// encodes the result as OTLP GAUGE data points (point-in-time aggregates the OTel backend
+// itself trends over the series). Emitted here (not `./index`) so the mapping stays the
+// single source of truth for both signals.
+// ---------------------------------------------------------------------------
+/** Metric names for the deployment-level platform observability gauges. */
+export const PLATFORM_METRIC = {
+    /** Windowed run count, split by run status (done/failed/running/…). */
+    runs: 'cat_factory.platform.runs',
+    /** Windowed `done / (done + failed)` success ratio (0..1). */
+    runSuccessRate: 'cat_factory.platform.run_success_rate',
+    /** Windowed failed-run count, split by failure kind. */
+    runFailures: 'cat_factory.platform.run_failures',
+    /** Current live/parked run count (a snapshot, not windowed), split by lifecycle state. */
+    liveRuns: 'cat_factory.platform.live_runs',
+    /** Windowed wall-clock run duration (seconds), split by statistic (avg/min/max/pNN). */
+    runDuration: 'cat_factory.platform.run_duration',
+};
+/**
+ * Attribute keys for the platform metrics. `account_id` is the tenant scope (bounded — the
+ * billing entity, far fewer than workspaces, so safe on a metric time series, unlike the
+ * workspace id excluded from the per-call metrics); `window` labels the trailing aggregation
+ * window. The remaining keys are the bounded split dimensions of each gauge.
+ */
+export const PLATFORM_ATTR = {
+    accountId: 'cat_factory.account_id',
+    window: 'cat_factory.window',
+    runStatus: 'cat_factory.run_status',
+    runState: 'cat_factory.run_state',
+    failureKind: 'cat_factory.failure_kind',
+    durationStat: 'cat_factory.duration_stat',
+};
+/** Metric units: a dimensionless run count, a dimensionless ratio, and seconds. */
+export const RUN_UNIT = '{run}';
+export const RATIO_UNIT = '1';
+/**
+ * Map a {@link PlatformObservability} projection to the OpenTelemetry gauge metrics. All are
+ * point-in-time gauges (the OTel backend builds trends from the series over time), stamped
+ * with the projection's `generatedAt`. Every point carries the `account_id`; the windowed
+ * gauges additionally carry the `window` label. Null/absent aggregates (e.g. a success rate
+ * or percentiles with no terminal runs) are omitted rather than emitted as a misleading zero.
+ */
+export function mapPlatformMetrics(snapshot, dims) {
+    const base = { [PLATFORM_ATTR.accountId]: dims.accountId };
+    const windowed = { ...base, [PLATFORM_ATTR.window]: snapshot.window };
+    const gauges = [];
+    const o = snapshot.outcomes;
+    const runStatuses = [
+        ['done', o.done],
+        ['failed', o.failed],
+        ['running', o.running],
+        ['blocked', o.blocked],
+        ['paused', o.paused],
+        ['other', o.other],
+    ];
+    gauges.push({
+        name: PLATFORM_METRIC.runs,
+        unit: RUN_UNIT,
+        points: runStatuses.map(([status, value]) => ({
+            attributes: { ...windowed, [PLATFORM_ATTR.runStatus]: status },
+            value,
+            isInt: true,
+        })),
+    });
+    if (o.successRate !== null) {
+        gauges.push({
+            name: PLATFORM_METRIC.runSuccessRate,
+            unit: RATIO_UNIT,
+            points: [{ attributes: windowed, value: o.successRate, isInt: false }],
+        });
+    }
+    if (snapshot.failures.length > 0) {
+        gauges.push({
+            name: PLATFORM_METRIC.runFailures,
+            unit: RUN_UNIT,
+            points: snapshot.failures.map((f) => ({
+                attributes: { ...windowed, [PLATFORM_ATTR.failureKind]: f.kind },
+                value: f.count,
+                isInt: true,
+            })),
+        });
+    }
+    const live = snapshot.live;
+    gauges.push({
+        name: PLATFORM_METRIC.liveRuns,
+        unit: RUN_UNIT,
+        // Live/parked depth is a snapshot, NOT windowed — so these points carry no window label.
+        points: [
+            ['running', live.running],
+            ['blocked', live.blocked],
+            ['paused', live.paused],
+            ['pending', live.pending],
+        ].map(([state, value]) => ({
+            attributes: { ...base, [PLATFORM_ATTR.runState]: state },
+            value,
+            isInt: true,
+        })),
+    });
+    const d = snapshot.durations;
+    const durationStats = [
+        ['avg', d.avgMs],
+        ['min', d.minMs],
+        ['max', d.maxMs],
+        ['p50', d.p50Ms],
+        ['p90', d.p90Ms],
+        ['p99', d.p99Ms],
+    ];
+    const durationPoints = durationStats
+        .filter(([, ms]) => ms !== null)
+        .map(([stat, ms]) => ({
+        attributes: { ...windowed, [PLATFORM_ATTR.durationStat]: stat },
+        // OTel duration convention is seconds; the projection carries ms.
+        value: ms / 1000,
+        isInt: false,
+    }));
+    if (durationPoints.length > 0) {
+        gauges.push({ name: PLATFORM_METRIC.runDuration, unit: DURATION_UNIT, points: durationPoints });
+    }
+    return gauges;
+}
+/** Map one container tool call to a neutral span under its run's trace. */
+export function mapToolSpan(context, span) {
+    const attributes = { [ATTR.agentKind]: context.agentKind };
+    if (context.workspaceId)
+        attributes[ATTR.workspaceId] = context.workspaceId;
+    return {
+        // Tool spans only reach here with a non-null executionId (the sinks guard on it).
+        traceId: deriveTraceId(context.executionId),
+        name: span.tool,
+        startTimeMs: span.startedAt,
+        endTimeMs: span.endedAt,
+        ok: span.ok,
+        attributes,
+        events: [],
+    };
+}
+//# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"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"}

package/dist/node.d.ts

@@ -0,0 +1,39 @@
+import { type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { type MetricReader } from '@opentelemetry/sdk-metrics';
+import type { LlmGenerationEvent, LlmToolSpan, LlmToolSpanContext, LlmTraceSink } from '@cat-factory/kernel';
+import type { OtelLogger } from './index.js';
+export interface NodeOtelSinkConfig {
+    /** OTLP/HTTP base URL, e.g. `http://collector:4318` (the `/v1/*` paths are appended). */
+    endpoint: string;
+    /** Extra headers merged onto every OTLP request (auth tokens, tenant ids, …). */
+    headers?: Record<string, string>;
+    /** OTLP resource `service.name`; defaults to `cat-factory`. */
+    serviceName?: string;
+    /** Optional logger for swallowed errors. */
+    logger?: OtelLogger;
+    /** Test seam: override the span processor (e.g. a SimpleSpanProcessor over an in-memory exporter). */
+    spanProcessor?: SpanProcessor;
+    /** Test seam: override the metric reader (e.g. one over an InMemoryMetricExporter). */
+    metricReader?: MetricReader;
+}
+export declare class NodeOtelTraceSink implements LlmTraceSink {
+    private readonly tracerProvider;
+    private readonly meterProvider;
+    private readonly idGenerator;
+    private readonly logger?;
+    private readonly startSpanForRun;
+    private readonly tokenCounter;
+    private readonly durationHistogram;
+    constructor(config: NodeOtelSinkConfig);
+    recordGeneration(event: LlmGenerationEvent): void;
+    recordToolSpans(context: LlmToolSpanContext, spans: LlmToolSpan[]): void;
+    private emitSpan;
+    /** Flush any buffered spans/metrics (e.g. before shutdown). Best-effort. */
+    forceFlush(): Promise<void>;
+    /** Shut the providers down, flushing first. Wire into the facade's stop path. */
+    shutdown(): Promise<void>;
+    private warn;
+}
+/** Build an SDK-backed {@link NodeOtelTraceSink}. The Node/local facades' OTLP exporter. */
+export declare function createNodeOtelSink(config: NodeOtelSinkConfig): NodeOtelTraceSink;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,4BAA4B,CAAA;AAInC,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAe5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAe5C,MAAM,WAAW,kBAAkB;IACjC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,sGAAsG;IACtG,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,uFAAuF;IACvF,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B;AAmBD,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAMvB;IACT,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAW;IAE7C,YAAY,MAAM,EAAE,kBAAkB,EAyCrC;IAED,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAehD;IAED,eAAe,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CASvE;IAED,OAAO,CAAC,QAAQ;IAiBhB,4EAA4E;IACtE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAMhC;IAED,iFAAiF;IAC3E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9B;IAED,OAAO,CAAC,IAAI;CAMb;AAED,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,CAEhF"}

package/dist/node.js

@@ -0,0 +1,131 @@
+import { SpanKind, SpanStatusCode, } from '@opentelemetry/api';
+import { BatchSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { AggregationTemporality, MeterProvider, PeriodicExportingMetricReader, } from '@opentelemetry/sdk-metrics';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { ATTR, DEFAULT_SERVICE_NAME, DURATION_UNIT, METRIC, SCOPE_NAME, TOKEN_UNIT, mapGeneration, mapGenerationMetrics, mapToolSpan, randomSpanId, randomTraceId, } from './mapping.js';
+/**
+ * Forces the trace id of the next span so a run's calls share one trace. The SDK calls
+ * `generateTraceId()` synchronously while starting a ROOT span (our spans have no active
+ * parent), so we set {@link nextTraceId} immediately before `startSpan` and clear it after.
+ */
+class RunIdGenerator {
+    nextTraceId = null;
+    generateTraceId() {
+        return this.nextTraceId ?? randomTraceId();
+    }
+    generateSpanId() {
+        return randomSpanId();
+    }
+}
+export class NodeOtelTraceSink {
+    tracerProvider;
+    meterProvider;
+    idGenerator;
+    logger;
+    startSpanForRun;
+    tokenCounter;
+    durationHistogram;
+    constructor(config) {
+        const base = config.endpoint.replace(/\/+$/, '');
+        const headers = config.headers;
+        const resource = resourceFromAttributes({
+            [ATTR.serviceName]: config.serviceName || DEFAULT_SERVICE_NAME,
+        });
+        this.idGenerator = new RunIdGenerator();
+        this.logger = config.logger;
+        const spanProcessor = config.spanProcessor ??
+            new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces`, headers }));
+        this.tracerProvider = new NodeTracerProvider({
+            resource,
+            idGenerator: this.idGenerator,
+            spanProcessors: [spanProcessor],
+        });
+        const tracer = this.tracerProvider.getTracer(SCOPE_NAME);
+        this.startSpanForRun = (name, traceId, startTimeMs, kind, attributes) => {
+            this.idGenerator.nextTraceId = traceId;
+            try {
+                return tracer.startSpan(name, { kind, startTime: startTimeMs, attributes, root: true });
+            }
+            finally {
+                this.idGenerator.nextTraceId = null;
+            }
+        };
+        const metricReader = config.metricReader ??
+            new PeriodicExportingMetricReader({
+                exporter: new OTLPMetricExporter({
+                    url: `${base}/v1/metrics`,
+                    headers,
+                    temporalityPreference: AggregationTemporality.DELTA,
+                }),
+            });
+        this.meterProvider = new MeterProvider({ resource, readers: [metricReader] });
+        const meter = this.meterProvider.getMeter(SCOPE_NAME);
+        this.tokenCounter = meter.createCounter(METRIC.tokenUsage, { unit: TOKEN_UNIT });
+        this.durationHistogram = meter.createHistogram(METRIC.duration, { unit: DURATION_UNIT });
+    }
+    recordGeneration(event) {
+        try {
+            const mapped = mapGeneration(event);
+            this.emitSpan(mapped, SpanKind.CLIENT);
+            const metrics = mapGenerationMetrics(event);
+            for (const point of metrics.tokenUsage) {
+                this.tokenCounter.add(point.value, point.attributes);
+            }
+            this.durationHistogram.record(metrics.durationSeconds, metrics.durationAttributes);
+        }
+        catch (err) {
+            this.warn(err);
+        }
+    }
+    recordToolSpans(context, spans) {
+        if (!context.executionId || spans.length === 0)
+            return;
+        try {
+            for (const span of spans) {
+                this.emitSpan(mapToolSpan(context, span), SpanKind.INTERNAL);
+            }
+        }
+        catch (err) {
+            this.warn(err);
+        }
+    }
+    emitSpan(mapped, kind) {
+        const span = this.startSpanForRun(mapped.name, mapped.traceId, mapped.startTimeMs, kind, mapped.attributes);
+        for (const event of mapped.events) {
+            span.addEvent(event.name, event.attributes, event.timeMs);
+        }
+        if (!mapped.ok) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: mapped.statusMessage });
+        }
+        span.end(mapped.endTimeMs);
+    }
+    /** Flush any buffered spans/metrics (e.g. before shutdown). Best-effort. */
+    async forceFlush() {
+        try {
+            await Promise.all([this.tracerProvider.forceFlush(), this.meterProvider.forceFlush()]);
+        }
+        catch (err) {
+            this.warn(err);
+        }
+    }
+    /** Shut the providers down, flushing first. Wire into the facade's stop path. */
+    async shutdown() {
+        try {
+            await Promise.all([this.tracerProvider.shutdown(), this.meterProvider.shutdown()]);
+        }
+        catch (err) {
+            this.warn(err);
+        }
+    }
+    warn(err) {
+        this.logger?.warn({ scope: 'otel', err: err instanceof Error ? err.message : String(err) }, 'otel: failed to record telemetry');
+    }
+}
+/** Build an SDK-backed {@link NodeOtelTraceSink}. The Node/local facades' OTLP exporter. */
+export function createNodeOtelSink(config) {
+    return new NodeOtelTraceSink(config);
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}

package/dist/otlp.d.ts

@@ -0,0 +1,39 @@
+import type { AttributeMap } from './mapping.js';
+/** Minimal structured logger (pino-compatible); optional. */
+export interface OtlpLogger {
+    warn(obj: Record<string, unknown>, msg?: string): void;
+}
+/** An OTLP `AnyValue` in the JSON encoding (string / int / double / string list). */
+export type AnyValue = {
+    stringValue: string;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    arrayValue: {
+        values: AnyValue[];
+    };
+};
+/** An OTLP `KeyValue` pair (an attribute). */
+export interface KeyValue {
+    key: string;
+    value: AnyValue;
+}
+/** Encode a neutral attribute map as an OTLP `KeyValue[]`. */
+export declare function keyValues(attrs: AttributeMap): KeyValue[];
+/**
+ * POST an OTLP/JSON payload to `endpoint`, best-effort. Observability must never break the
+ * caller, so a non-2xx response or a transport error is only logged (never thrown) and the
+ * batch is dropped — the documented worst case. Bounded by {@link SEND_TIMEOUT_MS} so a
+ * hung collector can't dangle the caller's budget.
+ */
+export declare function postOtlp(opts: {
+    fetchImpl: typeof fetch;
+    endpoint: string;
+    headers: Record<string, string>;
+    payload: unknown;
+    logger?: OtlpLogger;
+    timeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=otlp.d.ts.map

package/dist/otlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp.d.ts","sourceRoot":"","sources":["../src/otlp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,cAAc,CAAA;AAWhE,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvD;AAED,qFAAqF;AACrF,MAAM,MAAM,QAAQ,GAChB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GACvB;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GACvB;IAAE,UAAU,EAAE;QAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAA;CAAE,CAAA;AAE1C,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,QAAQ,CAAA;CAChB;AAaD,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,QAAQ,EAAE,CAEzD;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,SAAS,EAAE,OAAO,KAAK,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBhB"}

package/dist/otlp.js

@@ -0,0 +1,46 @@
+// Shared OTLP/HTTP JSON encoding + transport helpers used by BOTH fetch-based exporters
+// in this package — the per-call LLM trace/metric exporter (`./index`) and the periodic
+// platform-metrics exporter (`./platform`). Kept here so the two never drift on how an
+// attribute value is encoded or how a batch is POSTed. Nothing here depends on
+// `@opentelemetry/*` (workerd-safe) or on any global beyond `fetch`/`AbortSignal`.
+/** Hard ceiling on a single OTLP POST, so a hung collector can't tie up the caller. */
+const SEND_TIMEOUT_MS = 10_000;
+/** Encode one neutral attribute value as an OTLP `AnyValue`. */
+function anyValue(value) {
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.map((v) => ({ stringValue: String(v) })) } };
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    }
+    return { stringValue: value };
+}
+/** Encode a neutral attribute map as an OTLP `KeyValue[]`. */
+export function keyValues(attrs) {
+    return Object.entries(attrs).map(([key, value]) => ({ key, value: anyValue(value) }));
+}
+/**
+ * POST an OTLP/JSON payload to `endpoint`, best-effort. Observability must never break the
+ * caller, so a non-2xx response or a transport error is only logged (never thrown) and the
+ * batch is dropped — the documented worst case. Bounded by {@link SEND_TIMEOUT_MS} so a
+ * hung collector can't dangle the caller's budget.
+ */
+export async function postOtlp(opts) {
+    try {
+        const res = await opts.fetchImpl(opts.endpoint, {
+            method: 'POST',
+            headers: opts.headers,
+            body: JSON.stringify(opts.payload),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? SEND_TIMEOUT_MS),
+        });
+        // OTLP/HTTP returns 200 on full success and may return 200 with a partial-success body;
+        // any non-2xx is a failure we only log — observability never breaks the caller.
+        if (!res.ok) {
+            opts.logger?.warn({ scope: 'otel', status: res.status }, 'otel: OTLP endpoint rejected batch');
+        }
+    }
+    catch (err) {
+        opts.logger?.warn({ scope: 'otel', err: err instanceof Error ? err.message : String(err) }, 'otel: failed to POST OTLP batch');
+    }
+}
+//# sourceMappingURL=otlp.js.map

package/dist/otlp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp.js","sourceRoot":"","sources":["../src/otlp.ts"],"names":[],"mappings":"AAEA,wFAAwF;AACxF,wFAAwF;AACxF,uFAAuF;AACvF,+EAA+E;AAC/E,mFAAmF;AAEnF,uFAAuF;AACvF,MAAM,eAAe,GAAG,MAAM,CAAA;AAoB9B,gEAAgE;AAChE,SAAS,QAAQ,CAAC,KAAqB;IACrC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAA;IACnF,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;IACvF,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;AAC/B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,SAAS,CAAC,KAAmB;IAC3C,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;AACvF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAO9B;IACC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC9C,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;YAClC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,IAAI,eAAe,CAAC;SAC/D,CAAC,CAAA;QACF,wFAAwF;QACxF,gFAAgF;QAChF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,oCAAoC,CAAC,CAAA;QAChG,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EACxE,iCAAiC,CAClC,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/platform.d.ts

@@ -0,0 +1,37 @@
+import type { PlatformObservability } from '@cat-factory/contracts';
+import { type OtlpLogger } from './otlp.js';
+export interface PlatformMetricsOtelExporterConfig {
+    /** OTLP/HTTP base URL, e.g. `http://collector:4318` (`/v1/metrics` is appended). */
+    endpoint: string;
+    /** Extra headers merged onto every request (auth tokens, tenant ids, …). */
+    headers?: Record<string, string>;
+    /** OTLP resource `service.name`; defaults to `cat-factory`. */
+    serviceName?: string;
+    /** Optional logger for swallowed errors. */
+    logger?: OtlpLogger;
+    /** Injectable fetch (tests); defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class PlatformMetricsOtelExporter {
+    private readonly metricsEndpoint;
+    private readonly headers;
+    private readonly serviceName;
+    private readonly logger?;
+    private readonly fetchImpl;
+    constructor(config: PlatformMetricsOtelExporterConfig);
+    private resourceAttributes;
+    /**
+     * Export one account's platform-observability snapshot as OTLP gauge metrics. Gauges are
+     * stamped with the snapshot's `generatedAt` (the clock the projection was computed at), so
+     * no wall-clock read is needed here. In practice a snapshot always yields the run-count and
+     * live-depth gauges (even all-zero — a zero-valued gauge is meaningful, not misleading), so
+     * a POST is always sent; the empty-batch guard below is defensive only, in case the mapping
+     * ever becomes fully conditional. Best-effort — see the file header.
+     */
+    export(snapshot: PlatformObservability, dims: {
+        accountId: string;
+    }): Promise<void>;
+}
+/** Build a fetch-based {@link PlatformMetricsOtelExporter}. The workerd-safe opt-in exporter. */
+export declare function createPlatformMetricsOtelExporter(config: PlatformMetricsOtelExporterConfig): PlatformMetricsOtelExporter;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AASnE,OAAO,EAAiB,KAAK,UAAU,EAAuB,MAAM,WAAW,CAAA;AAoB/E,MAAM,WAAW,iCAAiC;IAChD,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAiBD,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,YAAY,MAAM,EAAE,iCAAiC,EAOpD;IAED,OAAO,CAAC,kBAAkB;IAI1B;;;;;;;OAOG;IACG,MAAM,CAAC,QAAQ,EAAE,qBAAqB,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBxF;CACF;AAED,iGAAiG;AACjG,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,iCAAiC,GACxC,2BAA2B,CAE7B"}