@foam-ai/node-cliengo 0.1.0-alpha.2 → 0.1.0-alpha.20

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

@@ -2,38 +2,42 @@
  * W3C trace context utilities for New Relic and OpenTelemetry interop.
  *
  * Why this file exists:
- *   NR owns the active trace (it creates transactions via http monkey-patching),
- *   but our OTel spans need to share the same traceId so Foam and NR traces
- *   correlate. This module reads NR's trace metadata and converts it to/from
- *   W3C traceparent format (`00-{traceId}-{spanId}-{flags}`).
+ *   Reads trace context from two sources (NR first, then OTel's own active
+ *   span) and converts it to/from W3C traceparent format. This means trace
+ *   propagation works whether NR is installed, partially loaded, or completely
+ *   removed.
  *
- * Functions:
- *   - buildTraceparent(): reads NR's active traceId/spanId, returns a W3C
- *     traceparent string. Used by producers to inject into SNS attributes or
- *     BullMQ/Bull job data. Returns undefined when NR is not loaded or no
- *     active transaction exists.
- *   - 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.
+ * 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.
+ *
+ *   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: getTraceMetadata() returns undefined — we default to
- *     empty strings, buildTraceparent returns undefined, getTraceContext
- *     returns empty strings. No crash.
- *   - NR loaded but no active transaction: traceId/spanId are empty strings.
- *     buildTraceparent returns undefined. Consumers create a fresh trace.
- *   - 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';
-export declare function buildTraceparent(): string | undefined;
+/**
+ * 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

@@ -3,50 +3,79 @@
  * W3C trace context utilities for New Relic and OpenTelemetry interop.
  *
  * Why this file exists:
- *   NR owns the active trace (it creates transactions via http monkey-patching),
- *   but our OTel spans need to share the same traceId so Foam and NR traces
- *   correlate. This module reads NR's trace metadata and converts it to/from
- *   W3C traceparent format (`00-{traceId}-{spanId}-{flags}`).
+ *   Reads trace context from two sources (NR first, then OTel's own active
+ *   span) and converts it to/from W3C traceparent format. This means trace
+ *   propagation works whether NR is installed, partially loaded, or completely
+ *   removed.
  *
- * Functions:
- *   - buildTraceparent(): reads NR's active traceId/spanId, returns a W3C
- *     traceparent string. Used by producers to inject into SNS attributes or
- *     BullMQ/Bull job data. Returns undefined when NR is not loaded or no
- *     active transaction exists.
- *   - 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.
+ * 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.
+ *
+ *   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: getTraceMetadata() returns undefined — we default to
- *     empty strings, buildTraceparent returns undefined, getTraceContext
- *     returns empty strings. No crash.
- *   - NR loaded but no active transaction: traceId/spanId are empty strings.
- *     buildTraceparent returns undefined. Consumers create a fresh trace.
- *   - 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;
 exports.extractParentContext = extractParentContext;
 exports.getTraceContext = getTraceContext;
 exports.getActiveContext = getActiveContext;
+const node_crypto_1 = require("node:crypto");
 const api_1 = require("@opentelemetry/api");
 const nr_1 = require("./nr");
+function generateTraceId() {
+    return (0, node_crypto_1.randomBytes)(16).toString('hex');
+}
+function generateSpanId() {
+    return (0, node_crypto_1.randomBytes)(8).toString('hex');
+}
+/**
+ * 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
+    }
+    const activeSpan = api_1.trace.getActiveSpan();
+    if (activeSpan) {
+        const sc = activeSpan.spanContext();
+        if (sc.traceId && sc.spanId) {
+            return { traceId: sc.traceId, spanId: sc.spanId };
+        }
+    }
+    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 nr = (0, nr_1.getNr)();
-    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
-    const { traceId, spanId } = meta;
-    if (!traceId || !spanId) {
-        return undefined;
+    const { traceId, spanId } = resolveActiveTraceIds();
+    if (traceId && spanId) {
+        return `00-${traceId}-${spanId}-01`;
     }
-    return `00-${traceId}-${spanId}-01`;
+    return `00-${generateTraceId()}-${generateSpanId()}-01`;
 }
 function extractParentContext(traceparent) {
     const parts = traceparent.split('-');
@@ -66,11 +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 nr = (0, nr_1.getNr)();
-    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
-    const traceId = meta.traceId ?? '';
-    const spanId = meta.spanId ?? '';
+    const { traceId, spanId } = resolveActiveTraceIds();
     const traceparent = traceId && spanId ? `00-${traceId}-${spanId}-01` : '';
     return { traceId, spanId, traceparent };
 }

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

@@ -27,12 +27,12 @@ import type { MeterProvider } from '@opentelemetry/sdk-metrics';
 import type { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
 export interface InitOptions {
     enabled?: boolean;
+    token?: string;
     newrelic?: NewRelicAgent;
     winston?: WinstonLogger;
     enableTraces?: boolean;
     enableLogs?: boolean;
     enableMetrics?: boolean;
-    endpoint?: string;
     forceExport?: boolean;
     autoShutdown?: boolean;
 }
@@ -49,7 +49,6 @@ export interface FoamMetrics {
 export interface FoamInstance {
     tracer: Tracer;
     meter: Meter;
-    logger: LoggerProvider;
     traceProvider: BasicTracerProvider;
     meterProvider: MeterProvider;
     loggerProvider: LoggerProvider;
@@ -61,14 +60,48 @@ export interface FoamInstance {
     createWinstonFormat(): WinstonFormat;
     createWinstonTransport(): WinstonTransport;
     createPinoMixin(): () => Record<string, string>;
+    createPinoHttpOptions(): {
+        customProps: (req: any) => Record<string, string>;
+    };
     createPinoDestination(): NodeJS.WritableStream;
-    buildTraceparent(): string | undefined;
+    /**
+     * Creates a Pino logger with trace-context mixin and OTLP destination pre-wired.
+     * Pass `streams` to replace the default stdout output (e.g., for pino-pretty):
+     *
+     *   foam.createPinoLogger({ streams: [{ stream: pinoPretty() }] })
+     *
+     * The OTLP destination is always appended automatically.
+     */
+    createPinoLogger(options?: Record<string, any>): any;
+    createPinoHttpConfig(opts?: {
+        logger?: any;
+    }): Record<string, any>;
+    /**
+     * Returns a Pino config object for Fastify's `logger` constructor option.
+     * Fastify constructs its own Pino instance from this, so request.log gets
+     * child loggers with request context automatically.
+     *
+     *   Fastify({ logger: foam.createFastifyLoggerConfig({ level: 'info' }) })
+     *
+     * Pass `streams` to replace stdout (e.g., pino-pretty in dev):
+     *
+     *   foam.createFastifyLoggerConfig({
+     *     level: 'debug',
+     *     streams: [{ stream: pinoPretty() }],
+     *   })
+     */
+    createFastifyLoggerConfig(opts?: Record<string, any>): Record<string, any>;
+    buildTraceparent(): string;
     injectSnsAttributes(attrs: Record<string, SnsMessageAttributeValue>): Record<string, SnsMessageAttributeValue>;
     injectJobData<T extends Record<string, unknown>>(data: T): T & {
-        traceparent?: string;
+        traceparent: string;
     };
+    /** @deprecated Pass (spanName, msg, fn) — the tracer arg is no longer needed. */
     wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>): Promise<void>;
+    wrapSqsConsumer(spanName: string, msg: SqsMessage, fn: () => Promise<void>): Promise<void>;
+    /** @deprecated Pass (spanName, jobData, fn) — the tracer arg is no longer needed. */
     wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>): Promise<void>;
+    wrapJobConsumer(spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>): Promise<void>;
     extractParentContext(traceparent: string): Context;
     shutdown(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foam-ai/node-cliengo",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.20",
   "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",
@@ -20,8 +20,8 @@
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
     "newrelic": ">=12.0.0",
-    "winston": "^3.0.0",
-    "pino": "^8.0.0 || ^9.0.0"
+    "pino": "^8.0.0 || ^9.0.0",
+    "winston": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "newrelic": {
@@ -35,18 +35,20 @@
     }
   },
   "dependencies": {
-    "@opentelemetry/sdk-trace-base": "^2.0.0",
-    "@opentelemetry/sdk-logs": "^0.203.0",
-    "@opentelemetry/sdk-metrics": "^2.0.1",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
+    "@opentelemetry/api-logs": "^0.203.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.203.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.201.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
     "@opentelemetry/resources": "^2.0.1",
-    "@opentelemetry/api-logs": "^0.203.0"
+    "@opentelemetry/sdk-logs": "^0.203.0",
+    "@opentelemetry/sdk-metrics": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@types/node": "^20.11.0",
     "typescript": "^6.0.2",
-    "@types/node": "^20.11.0"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=18"