@foam-ai/node-cliengo 0.1.0-alpha.1

package/dist/node-cliengo/src/init.js

@@ -0,0 +1,348 @@
+"use strict";
+/**
+ * Main entry point — init() creates the OtelBridge singleton for a service.
+ *
+ * Why this file exists:
+ *   Orchestrates all three OTel signals (traces, logs, metrics) into a single
+ *   init() call that returns an OtelBridge object. Services call init() once at
+ *   startup and use the returned bridge for everything else. The bridge is
+ *   designed to coexist with New Relic APM without touching NR's globals.
+ *
+ * Two-gate system:
+ *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert bridge.
+ *      Every API exists but does nothing — zero overhead, zero network, zero risk.
+ *      This is the master emergency shutoff.
+ *   2. Production gate (NODE_ENV): exporters are only attached when NODE_ENV is
+ *      "production" (or forceExport is true). In dev/test, the bridge is fully
+ *      functional (trace propagation, log enrichment work) but nothing is sent
+ *      to Foam. Developers without FOAM_OTEL_TOKEN get no crashes.
+ *
+ * Edge cases covered:
+ *   - Double init(): logs a warning, returns the existing bridge (singleton
+ *     per service name). Prevents duplicate providers/processors/handlers.
+ *   - Token undefined in dev: silently accepted — no OTLP export anyway.
+ *   - Token undefined in prod: logs warning, disables exporters. All other
+ *     features (trace propagation, log enrichment, NR bridging) still work.
+ *   - Token undefined + forceExport: throws (fail-fast — you asked to force
+ *     export but provided no credentials).
+ *   - Auto-shutdown (SIGTERM/SIGINT): flushes all providers with 5s timeout,
+ *     then calls process.exit(0). Without the explicit exit, registering
+ *     process.on('SIGTERM') replaces Node's default terminate behavior — services
+ *     without their own handler (gpt-intentions, cb-proxy) would hang forever.
+ *   - Manual shutdown: services with ordered cleanup (hsm-backend, kori, combee)
+ *     pass autoShutdown: false and call bridge.shutdown() in their own handler.
+ *   - shutdown() is idempotent — safe to call multiple times.
+ *   - Process exception handlers use process.on() (not .once()) so they don't
+ *     replace NR's or Winston's existing handlers. All handlers fire independently.
+ *   - uncaughtException handler flushes via shutdown() — best effort to get the
+ *     fatal log to Foam before the process dies. Never calls process.exit().
+ *   - Winston auto-wiring: init({ winston: baseLogger }) calls logger.add() for
+ *     the OTLP transport and rewrites logger.format to prepend trace enrichment.
+ *     Both work post-construction. Avoids circular deps (main.ts imports logger,
+ *     not the other way around).
+ *   - First-export health check: monkey-patches the BatchSpanProcessor's exporter
+ *     to log success/failure on the first OTLP export. Non-critical — wrapped in
+ *     try/catch, uses internal OTel SDK APIs that may change.
+ *   - Non-global providers: BasicTracerProvider, LoggerProvider, MeterProvider
+ *     are NEVER registered globally (.register() never called). NR owns the
+ *     global registrations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const api_logs_1 = require("@opentelemetry/api-logs");
+const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
+const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const resources_1 = require("@opentelemetry/resources");
+const sdk_logs_1 = require("@opentelemetry/sdk-logs");
+const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const node_stream_1 = require("node:stream");
+const constants_1 = require("./constants");
+const express_1 = require("./http/express");
+const fastify_1 = require("./http/fastify");
+const job_1 = require("./job");
+const pino_destination_1 = require("./logs/pino-destination");
+const pino_mixin_1 = require("./logs/pino-mixin");
+const winston_format_1 = require("./logs/winston-format");
+const winston_transport_1 = require("./logs/winston-transport");
+const instruments_1 = require("./metrics/instruments");
+const nr_1 = require("./nr");
+const sns_1 = require("./sns");
+const sqs_1 = require("./sqs");
+const trace_bridge_1 = require("./trace-bridge");
+const bridges = new Map();
+function createInertBridge(serviceName) {
+    const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
+    const traceProvider = new sdk_trace_base_1.BasicTracerProvider({ resource });
+    const loggerProvider = new sdk_logs_1.LoggerProvider({ resource });
+    const meterProvider = new sdk_metrics_1.MeterProvider({ resource });
+    const tracer = traceProvider.getTracer(serviceName);
+    const meter = meterProvider.getMeter(serviceName);
+    const metrics = (0, instruments_1.createBridgeMetrics)(meterProvider, serviceName);
+    return {
+        tracer,
+        meter,
+        logger: loggerProvider,
+        traceProvider,
+        meterProvider,
+        loggerProvider,
+        metrics,
+        getTraceContext: () => ({ traceId: '', spanId: '', traceparent: '' }),
+        createExpressMiddleware: () => (_req, _res, next) => next(),
+        createExpressErrorHandler: () => (_err, _req, _res, next) => next(_err),
+        createFastifyPlugin: () => async () => { },
+        createWinstonFormat: () => ({
+            transform: (info) => info,
+        }),
+        createWinstonTransport: () => ({}),
+        createPinoMixin: () => () => ({}),
+        createPinoDestination: () => new node_stream_1.Writable({
+            write: (_c, _e, cb) => cb(),
+        }),
+        buildTraceparent: () => undefined,
+        injectSnsAttributes: (attrs) => attrs,
+        injectJobData: (data) => data,
+        wrapSqsConsumer: async (_t, _s, _m, fn) => fn(),
+        wrapJobConsumer: async (_t, _s, _j, fn) => fn(),
+        extractParentContext: () => {
+            const { ROOT_CONTEXT } = require('@opentelemetry/api');
+            return ROOT_CONTEXT;
+        },
+        shutdown: async () => { },
+    };
+}
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */
+function init(serviceName, token, options = {}) {
+    const existing = bridges.get(serviceName);
+    if (existing) {
+        // eslint-disable-next-line no-console
+        console.warn(`[foam] init() already called for "${serviceName}" — returning existing bridge`);
+        return existing;
+    }
+    // Kill switch
+    const isEnabled = (options.enabled ??
+        ((process.env.FOAM_OTEL_ENABLED ?? 'true').toLowerCase() === 'true')) === true;
+    if (!isEnabled) {
+        const bridge = createInertBridge(serviceName);
+        bridges.set(serviceName, bridge);
+        return bridge;
+    }
+    // Resolve NR
+    (0, nr_1.resolveNewRelic)(options.newrelic);
+    // Production gate
+    const isProduction = process.env.NODE_ENV === 'production';
+    const shouldExport = isProduction || (options.forceExport === true);
+    // Token validation
+    if (shouldExport && !token) {
+        if (options.forceExport) {
+            throw new Error('[foam] forceExport is true but no FOAM_OTEL_TOKEN provided — cannot export telemetry');
+        }
+        // eslint-disable-next-line no-console
+        console.warn('[foam] no FOAM_OTEL_TOKEN — OTLP export disabled');
+    }
+    const hasToken = Boolean(token);
+    const canExport = shouldExport && hasToken;
+    const endpoint = options.endpoint ?? constants_1.FOAM_OTEL_ENDPOINT;
+    const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
+    const authHeaders = token
+        ? { Authorization: `Bearer ${token}` }
+        : {};
+    // --- Traces ---
+    const spanProcessors = [];
+    if (canExport && (options.enableTraces !== false)) {
+        const traceExporter = new exporter_trace_otlp_http_1.OTLPTraceExporter({
+            url: `${endpoint}/v1/traces`,
+            headers: authHeaders,
+        });
+        spanProcessors.push(new sdk_trace_base_1.BatchSpanProcessor(traceExporter));
+    }
+    const traceProvider = new sdk_trace_base_1.BasicTracerProvider({
+        resource,
+        spanProcessors,
+    });
+    // --- Logs ---
+    const logProcessors = [];
+    if (canExport && (options.enableLogs !== false)) {
+        const logExporter = new exporter_logs_otlp_http_1.OTLPLogExporter({
+            url: `${endpoint}/v1/logs`,
+            headers: authHeaders,
+        });
+        logProcessors.push(new sdk_logs_1.BatchLogRecordProcessor(logExporter));
+    }
+    const loggerProvider = new sdk_logs_1.LoggerProvider({
+        resource,
+        processors: logProcessors,
+    });
+    // --- Metrics ---
+    const readers = [];
+    if (canExport && (options.enableMetrics !== false)) {
+        const metricExporter = new exporter_metrics_otlp_http_1.OTLPMetricExporter({
+            url: `${endpoint}/v1/metrics`,
+            headers: authHeaders,
+        });
+        const exportIntervalMs = parseInt(process.env.OTEL_METRICS_EXPORT_INTERVAL_MS ?? '60000', 10);
+        readers.push(new sdk_metrics_1.PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            exportIntervalMillis: exportIntervalMs,
+        }));
+    }
+    const meterProvider = new sdk_metrics_1.MeterProvider({
+        resource,
+        readers,
+    });
+    const tracer = traceProvider.getTracer(serviceName);
+    const meter = meterProvider.getMeter(serviceName);
+    const metrics = (0, instruments_1.createBridgeMetrics)(meterProvider, serviceName);
+    let _isShutdown = false;
+    const shutdown = async () => {
+        if (_isShutdown) {
+            return;
+        }
+        _isShutdown = true;
+        const timeout = new Promise((resolve) => setTimeout(resolve, constants_1.SHUTDOWN_TIMEOUT_MS));
+        const flush = Promise.allSettled([
+            traceProvider.shutdown(),
+            loggerProvider.shutdown(),
+            meterProvider.shutdown(),
+        ]);
+        await Promise.race([flush, timeout]);
+    };
+    // Auto-shutdown on SIGTERM/SIGINT
+    if (options.autoShutdown !== false) {
+        const handler = async () => {
+            await shutdown();
+            process.exit(0);
+        };
+        process.on('SIGTERM', () => void handler());
+        process.on('SIGINT', () => void handler());
+    }
+    // Process-level exception capture
+    const otelLogger = loggerProvider.getLogger(serviceName);
+    process.on('uncaughtException', (err) => {
+        try {
+            otelLogger.emit({
+                body: err.message,
+                severityNumber: api_logs_1.SeverityNumber.FATAL,
+                severityText: 'FATAL',
+                attributes: {
+                    'exception.type': err.constructor.name,
+                    'exception.message': err.message,
+                    'exception.stacktrace': err.stack ?? '',
+                    'process.event': 'uncaughtException',
+                },
+            });
+            void shutdown();
+        }
+        catch {
+            /* best effort */
+        }
+    });
+    process.on('unhandledRejection', (reason) => {
+        try {
+            const err = reason instanceof Error ? reason : new Error(String(reason));
+            otelLogger.emit({
+                body: err.message,
+                severityNumber: api_logs_1.SeverityNumber.ERROR,
+                severityText: 'ERROR',
+                attributes: {
+                    'exception.type': err.constructor.name,
+                    'exception.message': err.message,
+                    'exception.stacktrace': err.stack ?? '',
+                    'process.event': 'unhandledRejection',
+                },
+            });
+        }
+        catch {
+            /* best effort */
+        }
+    });
+    // Winston auto-wiring
+    if (options.winston) {
+        const winstonLogger = options.winston;
+        try {
+            const transport = (0, winston_transport_1.createWinstonTransport)(loggerProvider, serviceName);
+            if (typeof winstonLogger.add === 'function') {
+                winstonLogger.add(transport);
+            }
+            const format = (0, winston_format_1.createWinstonFormat)();
+            if (winstonLogger.format) {
+                const originalFormat = winstonLogger.format;
+                winstonLogger.format = {
+                    transform: (info) => {
+                        const enriched = format.transform(info);
+                        if (typeof originalFormat.transform === 'function') {
+                            return originalFormat.transform(enriched);
+                        }
+                        return enriched;
+                    },
+                };
+            }
+        }
+        catch {
+            /* non-critical */
+        }
+    }
+    // First-export health check
+    if (canExport && spanProcessors.length > 0) {
+        let firstExportLogged = false;
+        try {
+            const proc = spanProcessors[0];
+            const exporter = proc._exporter;
+            if (exporter && typeof exporter.send === 'function') {
+                const origSend = exporter.send;
+                exporter.send = function (...args) {
+                    const cb = args[args.length - 1];
+                    if (typeof cb === 'function') {
+                        args[args.length - 1] = (result) => {
+                            if (!firstExportLogged) {
+                                firstExportLogged = true;
+                                if (result?.error) {
+                                    // eslint-disable-next-line no-console
+                                    console.warn(`[foam] OTLP export failed: ${String(result.error)} — check FOAM_OTEL_TOKEN and endpoint`);
+                                }
+                                else {
+                                    // eslint-disable-next-line no-console
+                                    console.info('[foam] first OTLP export succeeded — traces flowing to Foam');
+                                }
+                            }
+                            return cb(result);
+                        };
+                    }
+                    return origSend.apply(this, args);
+                };
+            }
+        }
+        catch {
+            /* non-critical */
+        }
+    }
+    const expressMiddleware = (0, express_1.createExpressMiddleware)(tracer);
+    const bridge = {
+        tracer,
+        meter,
+        logger: loggerProvider,
+        traceProvider,
+        meterProvider,
+        loggerProvider,
+        metrics,
+        getTraceContext: trace_bridge_1.getTraceContext,
+        createExpressMiddleware: () => expressMiddleware,
+        createExpressErrorHandler: () => (0, express_1.createExpressErrorHandler)(expressMiddleware),
+        createFastifyPlugin: () => (0, fastify_1.createFastifyPlugin)(tracer),
+        createWinstonFormat: () => (0, winston_format_1.createWinstonFormat)(),
+        createWinstonTransport: () => (0, winston_transport_1.createWinstonTransport)(loggerProvider, serviceName),
+        createPinoMixin: () => (0, pino_mixin_1.createPinoMixin)(),
+        createPinoDestination: () => (0, pino_destination_1.createPinoDestination)(loggerProvider, serviceName),
+        buildTraceparent: trace_bridge_1.buildTraceparent,
+        injectSnsAttributes: sns_1.injectSnsAttributes,
+        injectJobData: job_1.injectJobData,
+        wrapSqsConsumer: (t, s, m, fn) => (0, sqs_1.wrapSqsConsumer)(t, s, m, fn, metrics),
+        wrapJobConsumer: (t, s, j, fn) => (0, job_1.wrapJobConsumer)(t, s, j, fn, metrics),
+        extractParentContext: trace_bridge_1.extractParentContext,
+        shutdown,
+    };
+    bridges.set(serviceName, bridge);
+    return bridge;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */

package/dist/node-cliengo/src/job.d.ts

@@ -0,0 +1,31 @@
+/**
+ * BullMQ / Bull job data injection and consumer wrapper.
+ *
+ * Why this file exists:
+ *   Provides two functions for queue-based trace propagation:
+ *   - injectJobData(): adds a `traceparent` field to job data before enqueueing.
+ *     Works identically with both BullMQ and Bull because both expose job.data
+ *     as a plain object. Used by gpt-intentions (BullMQ), hsm-backend (BullMQ),
+ *     and cb-proxy (Bull).
+ *   - wrapJobConsumer(): wraps the job processing function in an OTel span and
+ *     NR background transaction, extracting traceparent from job.data. Used by
+ *     hsm-backend (BullMQ worker) and cb-proxy (Bull processor).
+ *
+ * Edge cases covered:
+ *   - No active NR transaction when injecting (producer side): buildTraceparent
+ *     returns undefined, original data returned unchanged — no traceparent key.
+ *   - Job data already has traceparent: overwritten with current value (spread).
+ *   - Job data has no traceparent (consumer side, Phase 1): creates a fresh
+ *     trace — no parent context, no error.
+ *   - fn() throws: exception recorded on span, error metrics incremented, error
+ *     re-thrown so BullMQ/Bull retry logic (attempts, backoff, DLQ) is unaffected.
+ *   - NR not loaded: skips startBackgroundTransaction, calls execute() directly.
+ *   - Non-Error thrown (e.g. string): wrapped in new Error(String(err)) for
+ *     consistent exception recording.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import type { BridgeMetrics } from './types';
+export declare function injectJobData<T extends Record<string, unknown>>(data: T): T & {
+    traceparent?: string;
+};
+export declare function wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>, metrics?: BridgeMetrics): Promise<void>;

package/dist/node-cliengo/src/job.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * BullMQ / Bull job data injection and consumer wrapper.
+ *
+ * Why this file exists:
+ *   Provides two functions for queue-based trace propagation:
+ *   - injectJobData(): adds a `traceparent` field to job data before enqueueing.
+ *     Works identically with both BullMQ and Bull because both expose job.data
+ *     as a plain object. Used by gpt-intentions (BullMQ), hsm-backend (BullMQ),
+ *     and cb-proxy (Bull).
+ *   - wrapJobConsumer(): wraps the job processing function in an OTel span and
+ *     NR background transaction, extracting traceparent from job.data. Used by
+ *     hsm-backend (BullMQ worker) and cb-proxy (Bull processor).
+ *
+ * Edge cases covered:
+ *   - No active NR transaction when injecting (producer side): buildTraceparent
+ *     returns undefined, original data returned unchanged — no traceparent key.
+ *   - Job data already has traceparent: overwritten with current value (spread).
+ *   - Job data has no traceparent (consumer side, Phase 1): creates a fresh
+ *     trace — no parent context, no error.
+ *   - fn() throws: exception recorded on span, error metrics incremented, error
+ *     re-thrown so BullMQ/Bull retry logic (attempts, backoff, DLQ) is unaffected.
+ *   - NR not loaded: skips startBackgroundTransaction, calls execute() directly.
+ *   - Non-Error thrown (e.g. string): wrapped in new Error(String(err)) for
+ *     consistent exception recording.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectJobData = injectJobData;
+exports.wrapJobConsumer = wrapJobConsumer;
+const api_1 = require("@opentelemetry/api");
+const nr_1 = require("./nr");
+const trace_bridge_1 = require("./trace-bridge");
+function injectJobData(data) {
+    const tp = (0, trace_bridge_1.buildTraceparent)();
+    if (!tp) {
+        return data;
+    }
+    return { ...data, traceparent: tp };
+}
+async function wrapJobConsumer(tracer, spanName, jobData, fn, metrics) {
+    const nr = (0, nr_1.getNr)();
+    const traceparent = jobData.traceparent ?? '';
+    const parentCtx = traceparent ? (0, trace_bridge_1.extractParentContext)(traceparent) : undefined;
+    const headers = {};
+    if (traceparent) {
+        headers.traceparent = traceparent;
+    }
+    const execute = async () => {
+        nr.acceptDistributedTraceHeaders?.('Queue', headers);
+        const span = tracer.startSpan(spanName, {
+            attributes: { 'messaging.system': 'bullmq', 'messaging.operation': 'process' },
+        }, parentCtx);
+        const start = Date.now();
+        try {
+            await fn();
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            metrics?.messagesProcessed.add(1, { queue: spanName, status: 'success' });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+            span.recordException({
+                name: error.constructor.name,
+                message: error.message,
+                stack: error.stack,
+            });
+            metrics?.messageProcessingErrors.add(1, {
+                queue: spanName,
+                'error.type': error.constructor.name,
+            });
+            metrics?.messagesProcessed.add(1, { queue: spanName, status: 'error' });
+            throw err;
+        }
+        finally {
+            const duration = Date.now() - start;
+            metrics?.messageProcessingDuration.record(duration, { queue: spanName });
+            span.end();
+        }
+    };
+    if (nr.startBackgroundTransaction) {
+        await nr.startBackgroundTransaction(spanName, 'QueueConsumer', execute);
+    }
+    else {
+        await execute();
+    }
+}

package/dist/node-cliengo/src/logs/pino-destination.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pino writable destination that delivers every JSON log line to Foam via the
+ * OTLP logs pipeline (non-global LoggerProvider → BatchLogRecordProcessor →
+ * OTLPLogExporter).
+ *
+ * Why this file exists:
+ *   Pino's destination stream is immutable after construction — there's no
+ *   `logger.addDestination()` API like Winston's `logger.add()`. Services must
+ *   create the logger with `pino.multistream()` from the start, sending to both
+ *   stdout (NR) and this destination (Foam).
+ *
+ * Used by kori (via Fastify) and cb-proxy (via pino + pino-http).
+ *
+ * Edge cases covered:
+ *   - Non-JSON lines (e.g. pino-pretty colored output in development): silently
+ *     skipped. The check is `trimmed.startsWith('{')` — fast rejection of
+ *     pretty-printed or binary lines. No crash, no error.
+ *   - Malformed JSON (truncated log line, encoding issue): JSON.parse catch
+ *     silently skips the line. Never crashes.
+ *   - Pino level mapping: 10→TRACE, 20→DEBUG, 30→INFO, 40→WARN, 50→ERROR,
+ *     60→FATAL. Unknown numeric levels default to INFO.
+ *   - Pino uses `msg` for the message field (not `message` like Winston). We
+ *     check both for compatibility with custom Pino configs.
+ *   - Internal Pino fields (pid, hostname, time) are excluded from attributes
+ *     to avoid noise. All other fields are forwarded.
+ *   - Callback always called — never blocks the Pino stream pipeline.
+ *   - Buffer chunks: converted to string before parsing (handles both Buffer
+ *     and string inputs from Node streams).
+ */
+import type { LoggerProvider } from '@opentelemetry/sdk-logs';
+export declare function createPinoDestination(loggerProvider: LoggerProvider, serviceName: string): NodeJS.WritableStream;

package/dist/node-cliengo/src/logs/pino-destination.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Pino writable destination that delivers every JSON log line to Foam via the
+ * OTLP logs pipeline (non-global LoggerProvider → BatchLogRecordProcessor →
+ * OTLPLogExporter).
+ *
+ * Why this file exists:
+ *   Pino's destination stream is immutable after construction — there's no
+ *   `logger.addDestination()` API like Winston's `logger.add()`. Services must
+ *   create the logger with `pino.multistream()` from the start, sending to both
+ *   stdout (NR) and this destination (Foam).
+ *
+ * Used by kori (via Fastify) and cb-proxy (via pino + pino-http).
+ *
+ * Edge cases covered:
+ *   - Non-JSON lines (e.g. pino-pretty colored output in development): silently
+ *     skipped. The check is `trimmed.startsWith('{')` — fast rejection of
+ *     pretty-printed or binary lines. No crash, no error.
+ *   - Malformed JSON (truncated log line, encoding issue): JSON.parse catch
+ *     silently skips the line. Never crashes.
+ *   - Pino level mapping: 10→TRACE, 20→DEBUG, 30→INFO, 40→WARN, 50→ERROR,
+ *     60→FATAL. Unknown numeric levels default to INFO.
+ *   - Pino uses `msg` for the message field (not `message` like Winston). We
+ *     check both for compatibility with custom Pino configs.
+ *   - Internal Pino fields (pid, hostname, time) are excluded from attributes
+ *     to avoid noise. All other fields are forwarded.
+ *   - Callback always called — never blocks the Pino stream pipeline.
+ *   - Buffer chunks: converted to string before parsing (handles both Buffer
+ *     and string inputs from Node streams).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPinoDestination = createPinoDestination;
+const api_logs_1 = require("@opentelemetry/api-logs");
+const node_stream_1 = require("node:stream");
+const trace_bridge_1 = require("../trace-bridge");
+const PINO_LEVEL_MAP = {
+    10: api_logs_1.SeverityNumber.TRACE,
+    20: api_logs_1.SeverityNumber.DEBUG,
+    30: api_logs_1.SeverityNumber.INFO,
+    40: api_logs_1.SeverityNumber.WARN,
+    50: api_logs_1.SeverityNumber.ERROR,
+    60: api_logs_1.SeverityNumber.FATAL,
+};
+const PINO_LEVEL_TEXT = {
+    10: 'TRACE',
+    20: 'DEBUG',
+    30: 'INFO',
+    40: 'WARN',
+    50: 'ERROR',
+    60: 'FATAL',
+};
+function createPinoDestination(loggerProvider, serviceName) {
+    const otelLogger = loggerProvider.getLogger(serviceName);
+    return new node_stream_1.Writable({
+        write(chunk, _encoding, callback) {
+            try {
+                const line = typeof chunk === 'string' ? chunk : chunk.toString();
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('{')) {
+                    // Non-JSON line (e.g. pino-pretty output) — silently skip
+                    callback();
+                    return;
+                }
+                const parsed = JSON.parse(trimmed);
+                const level = typeof parsed.level === 'number' ? parsed.level : 30;
+                const msg = parsed.msg ?? parsed.message ?? '';
+                const severity = PINO_LEVEL_MAP[level] ?? api_logs_1.SeverityNumber.INFO;
+                const severityText = PINO_LEVEL_TEXT[level] ?? 'INFO';
+                const ctx = (0, trace_bridge_1.getTraceContext)();
+                const attributes = {};
+                if (ctx.traceId) {
+                    attributes['trace.id'] = ctx.traceId;
+                }
+                if (ctx.spanId) {
+                    attributes['span.id'] = ctx.spanId;
+                }
+                for (const [key, val] of Object.entries(parsed)) {
+                    if (key !== 'level' && key !== 'msg' && key !== 'message' && key !== 'time' && key !== 'pid' && key !== 'hostname') {
+                        try {
+                            attributes[key] = typeof val === 'string' ? val : JSON.stringify(val);
+                        }
+                        catch {
+                            /* skip */
+                        }
+                    }
+                }
+                otelLogger.emit({
+                    body: msg,
+                    severityNumber: severity,
+                    severityText,
+                    attributes,
+                });
+            }
+            catch {
+                // Malformed JSON or unexpected structure — silently skip
+            }
+            callback();
+        },
+    });
+}

package/dist/node-cliengo/src/logs/pino-mixin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pino mixin for trace context enrichment.
+ *
+ * Why this file exists:
+ *   Pino's `mixin` option is a function called on every log that returns extra
+ *   fields to merge into the log entry. This mixin injects { traceId, spanId,
+ *   traceparent } into every Pino log line so NR's stdout-based log forwarding
+ *   can correlate logs with traces. Like the Winston format, it does NOT send
+ *   logs anywhere — that's the destination's job.
+ *
+ * Used by kori (Fastify built-in Pino) and cb-proxy (Pino + pino-http).
+ *
+ * Edge cases covered:
+ *   - NR not loaded or no active transaction: returns { traceId: '', spanId: '',
+ *     traceparent: '' }. Consistent schema — log parsers always see the fields.
+ *   - getTraceContext throws: catch returns the same empty-string object.
+ *     Never crashes logging.
+ *   - Lazy evaluation: the mixin is called at log-write time, not at Pino
+ *     construction time, so trace context is always current.
+ *   - Works with pino-pretty in development — fields appear in pretty output.
+ */
+export declare function createPinoMixin(): () => Record<string, string>;

package/dist/node-cliengo/src/logs/pino-mixin.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Pino mixin for trace context enrichment.
+ *
+ * Why this file exists:
+ *   Pino's `mixin` option is a function called on every log that returns extra
+ *   fields to merge into the log entry. This mixin injects { traceId, spanId,
+ *   traceparent } into every Pino log line so NR's stdout-based log forwarding
+ *   can correlate logs with traces. Like the Winston format, it does NOT send
+ *   logs anywhere — that's the destination's job.
+ *
+ * Used by kori (Fastify built-in Pino) and cb-proxy (Pino + pino-http).
+ *
+ * Edge cases covered:
+ *   - NR not loaded or no active transaction: returns { traceId: '', spanId: '',
+ *     traceparent: '' }. Consistent schema — log parsers always see the fields.
+ *   - getTraceContext throws: catch returns the same empty-string object.
+ *     Never crashes logging.
+ *   - Lazy evaluation: the mixin is called at log-write time, not at Pino
+ *     construction time, so trace context is always current.
+ *   - Works with pino-pretty in development — fields appear in pretty output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPinoMixin = createPinoMixin;
+const trace_bridge_1 = require("../trace-bridge");
+function createPinoMixin() {
+    return () => {
+        try {
+            const ctx = (0, trace_bridge_1.getTraceContext)();
+            return {
+                traceId: ctx.traceId,
+                spanId: ctx.spanId,
+                traceparent: ctx.traceparent,
+            };
+        }
+        catch {
+            return { traceId: '', spanId: '', traceparent: '' };
+        }
+    };
+}