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

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

@@ -48,6 +48,15 @@ export declare function getRequestTraceContext(req: any): {
     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

@@ -37,6 +37,7 @@
 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");
@@ -121,6 +122,17 @@ function getRequestTraceContext(req) {
         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/index.d.ts

@@ -18,7 +18,7 @@ export { buildTraceparent, extractParentContext, getTraceContext } from './trace
 export { injectSnsAttributes } from './sns';
 export { injectJobData, wrapJobConsumer } from './job';
 export { wrapSqsConsumer } from './sqs';
-export { createExpressMiddleware, createExpressErrorHandler, getRequestTraceContext } from './http/express';
+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';

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.getFastifyRequestTraceContext = exports.createFastifyPlugin = exports.getRequestTraceContext = 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");
@@ -33,6 +33,7 @@ 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; } });

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-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,10 +40,12 @@ function generateTraceId() {
 function generateSpanId() {
     return (0, node_crypto_1.randomBytes)(8).toString('hex');
 }
-function resolveTraceIds() {
-    // 1. Try NR (guarded — getTraceMetadata() can throw if the underlying
-    //    transaction is null, which happens when pino-http logs fire after
-    //    NR's transaction has ended)
+/**
+ * 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: '' };
@@ -60,9 +54,8 @@ function resolveTraceIds() {
         }
     }
     catch {
-        // NR transaction is null or getTraceMetadata threw — fall through
+        // 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();
@@ -70,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('-');
@@ -95,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.7",
+  "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",