@foam-ai/node-cliengo 0.1.0-alpha.6 → 0.1.0-alpha.9

package/dist/node-cliengo/src/http/express.d.ts

@@ -36,6 +36,27 @@
 import { type Tracer } from '@opentelemetry/api';
 import type { ExpressErrorHandler, ExpressRequestHandler } from '../types';
 export declare function createExpressMiddleware(tracer: Tracer): ExpressRequestHandler;
+/**
+ * Reads the trace context that was captured on the request at middleware time.
+ * Use this in pino-http's `customProps` to get trace IDs even after NR's
+ * transaction has ended:
+ *
+ *   pinoHttp({ customProps: (req) => getRequestTraceContext(req) })
+ */
+export declare function getRequestTraceContext(req: any): {
+    traceId: string;
+    spanId: string;
+    traceparent: string;
+};
+/**
+ * Returns pino-http options with customProps pre-wired to read the trace
+ * context stored on req by createExpressMiddleware(). Zero config for services:
+ *
+ *   app.use(pinoHttp({ logger, ...foam.createPinoHttpOptions() }));
+ */
+export declare function createPinoHttpOptions(): {
+    customProps: (req: any) => Record<string, string>;
+};
 export declare function createExpressErrorHandler(middlewareRef?: ExpressRequestHandler & {
     _markErrorHandler?: () => void;
 }): ExpressErrorHandler;

package/dist/node-cliengo/src/http/express.js

@@ -36,11 +36,14 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createExpressMiddleware = createExpressMiddleware;
+exports.getRequestTraceContext = getRequestTraceContext;
+exports.createPinoHttpOptions = createPinoHttpOptions;
 exports.createExpressErrorHandler = createExpressErrorHandler;
 const api_1 = require("@opentelemetry/api");
 const trace_bridge_1 = require("../trace-bridge");
 const request_context_1 = require("./request-context");
 const SPAN_KEY = Symbol.for('foam.shadow.span');
+const TRACE_CTX_KEY = Symbol.for('foam.trace.context');
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 function createExpressMiddleware(tracer) {
     let errorHandlerRegistered = false;
@@ -61,6 +64,7 @@ function createExpressMiddleware(tracer) {
             },
         });
         req[SPAN_KEY] = span;
+        req[TRACE_CTX_KEY] = { traceId, spanId };
         const startTime = Date.now();
         const onFinish = () => {
             try {
@@ -99,6 +103,36 @@ function createExpressMiddleware(tracer) {
     middleware._markErrorHandler = markErrorHandlerRegistered;
     return middleware;
 }
+/**
+ * Reads the trace context that was captured on the request at middleware time.
+ * Use this in pino-http's `customProps` to get trace IDs even after NR's
+ * transaction has ended:
+ *
+ *   pinoHttp({ customProps: (req) => getRequestTraceContext(req) })
+ */
+function getRequestTraceContext(req) {
+    try {
+        const ctx = req[TRACE_CTX_KEY];
+        const traceId = ctx?.traceId ?? '';
+        const spanId = ctx?.spanId ?? '';
+        const traceparent = traceId && spanId ? `00-${traceId}-${spanId}-01` : '';
+        return { traceId, spanId, traceparent };
+    }
+    catch {
+        return { traceId: '', spanId: '', traceparent: '' };
+    }
+}
+/**
+ * Returns pino-http options with customProps pre-wired to read the trace
+ * context stored on req by createExpressMiddleware(). Zero config for services:
+ *
+ *   app.use(pinoHttp({ logger, ...foam.createPinoHttpOptions() }));
+ */
+function createPinoHttpOptions() {
+    return {
+        customProps: (req) => getRequestTraceContext(req),
+    };
+}
 function createExpressErrorHandler(middlewareRef) {
     middlewareRef?._markErrorHandler?.();
     return (err, req, _res, next) => {

package/dist/node-cliengo/src/http/fastify.d.ts

@@ -25,4 +25,14 @@
  */
 import { type Tracer } from '@opentelemetry/api';
 import type { FastifyPluginAsync } from '../types';
+/**
+ * Reads the trace context that was captured on the request at hook time.
+ * Use this in Fastify's logger mixin or serializers to get trace IDs even
+ * after NR's transaction has ended.
+ */
+export declare function getRequestTraceContext(request: any): {
+    traceId: string;
+    spanId: string;
+    traceparent: string;
+};
 export declare function createFastifyPlugin(tracer: Tracer): FastifyPluginAsync;

package/dist/node-cliengo/src/http/fastify.js

@@ -25,12 +25,31 @@
  *   - done() always called even if our code throws — Fastify hook contract.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRequestTraceContext = getRequestTraceContext;
 exports.createFastifyPlugin = createFastifyPlugin;
 const api_1 = require("@opentelemetry/api");
 const trace_bridge_1 = require("../trace-bridge");
 const request_context_1 = require("./request-context");
 const SPAN_KEY = Symbol.for('foam.shadow.span');
 const START_KEY = Symbol.for('foam.shadow.start');
+const TRACE_CTX_KEY = Symbol.for('foam.trace.context');
+/**
+ * Reads the trace context that was captured on the request at hook time.
+ * Use this in Fastify's logger mixin or serializers to get trace IDs even
+ * after NR's transaction has ended.
+ */
+function getRequestTraceContext(request) {
+    try {
+        const ctx = request[TRACE_CTX_KEY];
+        const traceId = ctx?.traceId ?? '';
+        const spanId = ctx?.spanId ?? '';
+        const traceparent = traceId && spanId ? `00-${traceId}-${spanId}-01` : '';
+        return { traceId, spanId, traceparent };
+    }
+    catch {
+        return { traceId: '', spanId: '', traceparent: '' };
+    }
+}
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 function createFastifyPlugin(tracer) {
     return async (fastify) => {
@@ -49,6 +68,7 @@ function createFastifyPlugin(tracer) {
                 });
                 request[SPAN_KEY] = span;
                 request[START_KEY] = Date.now();
+                request[TRACE_CTX_KEY] = { traceId, spanId };
             }
             catch {
                 /* never crash */

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

@@ -18,8 +18,8 @@ export { buildTraceparent, extractParentContext, getTraceContext } from './trace
 export { injectSnsAttributes } from './sns';
 export { injectJobData, wrapJobConsumer } from './job';
 export { wrapSqsConsumer } from './sqs';
-export { createExpressMiddleware, createExpressErrorHandler } from './http/express';
-export { createFastifyPlugin } from './http/fastify';
+export { createExpressMiddleware, createExpressErrorHandler, getRequestTraceContext, createPinoHttpOptions } from './http/express';
+export { createFastifyPlugin, getRequestTraceContext as getFastifyRequestTraceContext } from './http/fastify';
 export { createWinstonFormat } from './logs/winston-format';
 export { createPinoMixin } from './logs/pino-mixin';
 export { FOAM_OTEL_ENDPOINT } from './constants';

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

@@ -15,7 +15,7 @@
  *   access to the foam instance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FOAM_OTEL_ENDPOINT = exports.createPinoMixin = exports.createWinstonFormat = exports.createFastifyPlugin = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.init = void 0;
+exports.FOAM_OTEL_ENDPOINT = exports.createPinoMixin = exports.createWinstonFormat = exports.getFastifyRequestTraceContext = exports.createFastifyPlugin = exports.createPinoHttpOptions = exports.getRequestTraceContext = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.init = void 0;
 var init_1 = require("./init");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
 var trace_bridge_1 = require("./trace-bridge");
@@ -32,8 +32,11 @@ Object.defineProperty(exports, "wrapSqsConsumer", { enumerable: true, get: funct
 var express_1 = require("./http/express");
 Object.defineProperty(exports, "createExpressMiddleware", { enumerable: true, get: function () { return express_1.createExpressMiddleware; } });
 Object.defineProperty(exports, "createExpressErrorHandler", { enumerable: true, get: function () { return express_1.createExpressErrorHandler; } });
+Object.defineProperty(exports, "getRequestTraceContext", { enumerable: true, get: function () { return express_1.getRequestTraceContext; } });
+Object.defineProperty(exports, "createPinoHttpOptions", { enumerable: true, get: function () { return express_1.createPinoHttpOptions; } });
 var fastify_1 = require("./http/fastify");
 Object.defineProperty(exports, "createFastifyPlugin", { enumerable: true, get: function () { return fastify_1.createFastifyPlugin; } });
+Object.defineProperty(exports, "getFastifyRequestTraceContext", { enumerable: true, get: function () { return fastify_1.getRequestTraceContext; } });
 var winston_format_1 = require("./logs/winston-format");
 Object.defineProperty(exports, "createWinstonFormat", { enumerable: true, get: function () { return winston_format_1.createWinstonFormat; } });
 var pino_mixin_1 = require("./logs/pino-mixin");

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

@@ -100,6 +100,7 @@ function createInertInstance(serviceName) {
         }),
         createWinstonTransport: () => ({}),
         createPinoMixin: () => () => ({}),
+        createPinoHttpOptions: () => ({ customProps: () => ({}) }),
         createPinoDestination: () => new node_stream_1.Writable({
             write: (_c, _e, cb) => cb(),
         }),
@@ -339,6 +340,7 @@ function init(serviceName, token, options = {}) {
         createWinstonFormat: () => (0, winston_format_1.createWinstonFormat)(),
         createWinstonTransport: () => (0, winston_transport_1.createWinstonTransport)(loggerProvider, serviceName),
         createPinoMixin: () => (0, pino_mixin_1.createPinoMixin)(),
+        createPinoHttpOptions: () => (0, express_1.createPinoHttpOptions)(),
         createPinoDestination: () => (0, pino_destination_1.createPinoDestination)(loggerProvider, serviceName),
         buildTraceparent: trace_bridge_1.buildTraceparent,
         injectSnsAttributes: sns_1.injectSnsAttributes,

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

@@ -35,6 +35,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPinoDestination = createPinoDestination;
+const api_1 = require("@opentelemetry/api");
 const api_logs_1 = require("@opentelemetry/api-logs");
 const node_stream_1 = require("node:stream");
 const PINO_LEVEL_MAP = {
@@ -95,11 +96,24 @@ function createPinoDestination(loggerProvider, serviceName) {
                         }
                     }
                 }
+                // Build an OTel Context carrying the SpanContext so the SDK stamps the
+                // native traceId/spanId fields on the exported OTLP LogRecord. Without
+                // this, backends can't correlate logs to traces.
+                let logContext;
+                if (traceId && spanId) {
+                    logContext = api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, {
+                        traceId,
+                        spanId,
+                        traceFlags: 1,
+                        isRemote: true,
+                    });
+                }
                 otelLogger.emit({
                     body: msg,
                     severityNumber: severity,
                     severityText,
                     attributes,
+                    ...(logContext && { context: logContext }),
                 });
             }
             catch {

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

@@ -11,10 +11,11 @@
  * 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.
+ *   - NR not loaded or no active transaction: returns {} so it doesn't
+ *     overwrite valid trace context injected by pino-http's customProps
+ *     (Pino serializes mixin fields after customProps — duplicate keys
+ *     in JSON take the last value).
+ *   - getTraceContext throws: catch returns {}. 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.

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

@@ -12,10 +12,11 @@
  * 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.
+ *   - NR not loaded or no active transaction: returns {} so it doesn't
+ *     overwrite valid trace context injected by pino-http's customProps
+ *     (Pino serializes mixin fields after customProps — duplicate keys
+ *     in JSON take the last value).
+ *   - getTraceContext throws: catch returns {}. 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.
@@ -27,6 +28,9 @@ function createPinoMixin() {
     return () => {
         try {
             const ctx = (0, trace_bridge_1.getTraceContext)();
+            if (!ctx.traceId) {
+                return {};
+            }
             return {
                 traceId: ctx.traceId,
                 spanId: ctx.spanId,
@@ -34,7 +38,7 @@ function createPinoMixin() {
             };
         }
         catch {
-            return { traceId: '', spanId: '', traceparent: '' };
+            return {};
         }
     };
 }

package/dist/node-cliengo/src/trace-bridge.d.ts

@@ -7,35 +7,37 @@
  *   propagation works whether NR is installed, partially loaded, or completely
  *   removed.
  *
- * Resolution order (buildTraceparent / getTraceContext):
- *   1. NR's getTraceMetadata() — if NR is loaded and has an active transaction
- *   2. OTel's active span context — if our own tracer has an active span
- *   3. Generate fresh traceId (16 bytes) + spanId (8 bytes) — always has context
+ * Two resolution modes:
+ *   resolveActiveTraceIds() — NR → OTel active span → empty strings.
+ *     Used by getTraceContext() (log enrichment) and createPinoMixin().
+ *     Never generates IDs — returns empty when no real source exists, so
+ *     it doesn't overwrite valid IDs injected by pino-http's customProps.
  *
- * Functions:
- *   - buildTraceparent(): always returns a W3C traceparent string — from NR,
- *     OTel, or freshly generated. Used by producers to inject into SNS
- *     attributes or BullMQ/Bull job data.
- *   - extractParentContext(): parses a traceparent string into an OTel Context
- *     with a remote SpanContext. Used by consumers to link their OTel spans
- *     back to the producer's trace. Returns ROOT_CONTEXT on malformed input.
- *   - getTraceContext(): returns { traceId, spanId, traceparent } for log
- *     enrichment. Called lazily at log-write time (not at format creation time)
- *     so the trace context is always current.
+ *   buildTraceparent() — NR → OTel active span → generate fresh IDs.
+ *     Used by producers (injectSnsAttributes, injectJobData) and the
+ *     Express/Fastify middleware at request start. Always returns a
+ *     traceparent so every message/request gets trace context.
  *
  * Edge cases covered:
- *   - NR not loaded: falls back to OTel active span, then to generated IDs.
- *   - NR loaded but no active transaction: same fallback chain.
- *   - NR removed entirely: OTel active span or generated IDs. Always works.
- *   - Malformed traceparent (wrong number of parts, wrong hex lengths):
- *     extractParentContext returns ROOT_CONTEXT — consumer creates a fresh
- *     trace instead of crashing.
- *   - Flags field always set to 01 (sampled) on buildTraceparent because we
- *     want all async boundary crossings traced.
+ *   - NR's getTraceMetadata() can throw TypeError when the transaction is
+ *     null (pino-http fires after NR ends the transaction). Guarded with
+ *     try/catch.
+ *   - Malformed traceparent: extractParentContext returns ROOT_CONTEXT.
+ *   - Flags always 01 (sampled) on buildTraceparent.
  */
 import { type Context } from '@opentelemetry/api';
 import type { TraceContext } from './types';
+/**
+ * Always returns a traceparent — from NR, OTel active span, or freshly
+ * generated. Used by producers to inject into SNS attributes / job data,
+ * and by the Express/Fastify middleware at request start.
+ */
 export declare function buildTraceparent(): string;
 export declare function extractParentContext(traceparent: string): Context;
+/**
+ * Returns trace context from active sources only (NR or OTel active span).
+ * Returns empty strings when neither is active — never generates fresh IDs.
+ * Used for log enrichment where fake IDs would create false correlations.
+ */
 export declare function getTraceContext(): TraceContext;
 export declare function getActiveContext(): Context;

package/dist/node-cliengo/src/trace-bridge.js

@@ -8,31 +8,23 @@
  *   propagation works whether NR is installed, partially loaded, or completely
  *   removed.
  *
- * Resolution order (buildTraceparent / getTraceContext):
- *   1. NR's getTraceMetadata() — if NR is loaded and has an active transaction
- *   2. OTel's active span context — if our own tracer has an active span
- *   3. Generate fresh traceId (16 bytes) + spanId (8 bytes) — always has context
+ * Two resolution modes:
+ *   resolveActiveTraceIds() — NR → OTel active span → empty strings.
+ *     Used by getTraceContext() (log enrichment) and createPinoMixin().
+ *     Never generates IDs — returns empty when no real source exists, so
+ *     it doesn't overwrite valid IDs injected by pino-http's customProps.
  *
- * Functions:
- *   - buildTraceparent(): always returns a W3C traceparent string — from NR,
- *     OTel, or freshly generated. Used by producers to inject into SNS
- *     attributes or BullMQ/Bull job data.
- *   - extractParentContext(): parses a traceparent string into an OTel Context
- *     with a remote SpanContext. Used by consumers to link their OTel spans
- *     back to the producer's trace. Returns ROOT_CONTEXT on malformed input.
- *   - getTraceContext(): returns { traceId, spanId, traceparent } for log
- *     enrichment. Called lazily at log-write time (not at format creation time)
- *     so the trace context is always current.
+ *   buildTraceparent() — NR → OTel active span → generate fresh IDs.
+ *     Used by producers (injectSnsAttributes, injectJobData) and the
+ *     Express/Fastify middleware at request start. Always returns a
+ *     traceparent so every message/request gets trace context.
  *
  * Edge cases covered:
- *   - NR not loaded: falls back to OTel active span, then to generated IDs.
- *   - NR loaded but no active transaction: same fallback chain.
- *   - NR removed entirely: OTel active span or generated IDs. Always works.
- *   - Malformed traceparent (wrong number of parts, wrong hex lengths):
- *     extractParentContext returns ROOT_CONTEXT — consumer creates a fresh
- *     trace instead of crashing.
- *   - Flags field always set to 01 (sampled) on buildTraceparent because we
- *     want all async boundary crossings traced.
+ *   - NR's getTraceMetadata() can throw TypeError when the transaction is
+ *     null (pino-http fires after NR ends the transaction). Guarded with
+ *     try/catch.
+ *   - Malformed traceparent: extractParentContext returns ROOT_CONTEXT.
+ *   - Flags always 01 (sampled) on buildTraceparent.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildTraceparent = buildTraceparent;
@@ -48,14 +40,22 @@ function generateTraceId() {
 function generateSpanId() {
     return (0, node_crypto_1.randomBytes)(8).toString('hex');
 }
-function resolveTraceIds() {
-    // 1. Try NR
-    const nr = (0, nr_1.getNr)();
-    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
-    if (meta.traceId && meta.spanId) {
-        return { traceId: meta.traceId, spanId: meta.spanId };
+/**
+ * Resolves trace IDs from active sources only (NR or OTel active span).
+ * Returns empty strings when neither source has an active trace — never
+ * generates fresh IDs.
+ */
+function resolveActiveTraceIds() {
+    try {
+        const nr = (0, nr_1.getNr)();
+        const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
+        if (meta.traceId && meta.spanId) {
+            return { traceId: meta.traceId, spanId: meta.spanId };
+        }
+    }
+    catch {
+        // NR transaction is null or getTraceMetadata threw
     }
-    // 2. Fall back to OTel's own active span
     const activeSpan = api_1.trace.getActiveSpan();
     if (activeSpan) {
         const sc = activeSpan.spanContext();
@@ -63,12 +63,19 @@ function resolveTraceIds() {
             return { traceId: sc.traceId, spanId: sc.spanId };
         }
     }
-    // 3. Generate our own — ensures trace context is always available
-    return { traceId: generateTraceId(), spanId: generateSpanId() };
+    return { traceId: '', spanId: '' };
 }
+/**
+ * Always returns a traceparent — from NR, OTel active span, or freshly
+ * generated. Used by producers to inject into SNS attributes / job data,
+ * and by the Express/Fastify middleware at request start.
+ */
 function buildTraceparent() {
-    const { traceId, spanId } = resolveTraceIds();
-    return `00-${traceId}-${spanId}-01`;
+    const { traceId, spanId } = resolveActiveTraceIds();
+    if (traceId && spanId) {
+        return `00-${traceId}-${spanId}-01`;
+    }
+    return `00-${generateTraceId()}-${generateSpanId()}-01`;
 }
 function extractParentContext(traceparent) {
     const parts = traceparent.split('-');
@@ -88,8 +95,13 @@ function extractParentContext(traceparent) {
     };
     return api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, spanContext);
 }
+/**
+ * Returns trace context from active sources only (NR or OTel active span).
+ * Returns empty strings when neither is active — never generates fresh IDs.
+ * Used for log enrichment where fake IDs would create false correlations.
+ */
 function getTraceContext() {
-    const { traceId, spanId } = resolveTraceIds();
+    const { traceId, spanId } = resolveActiveTraceIds();
     const traceparent = traceId && spanId ? `00-${traceId}-${spanId}-01` : '';
     return { traceId, spanId, traceparent };
 }

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

@@ -61,6 +61,9 @@ export interface FoamInstance {
     createWinstonFormat(): WinstonFormat;
     createWinstonTransport(): WinstonTransport;
     createPinoMixin(): () => Record<string, string>;
+    createPinoHttpOptions(): {
+        customProps: (req: any) => Record<string, string>;
+    };
     createPinoDestination(): NodeJS.WritableStream;
     buildTraceparent(): string;
     injectSnsAttributes(attrs: Record<string, SnsMessageAttributeValue>): Record<string, SnsMessageAttributeValue>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node-cliengo",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.9",
   "description": "Unified observability (traces, logs, metrics) for Cliengo Node.js services, connecting New Relic APM with Foam's OTel collector.",
   "main": "dist/node-cliengo/src/index.js",
   "types": "dist/node-cliengo/src/index.d.ts",