@senzops/apm-node 1.1.15 → 1.1.17

package/src/core/client.ts

@@ -1,6 +1,6 @@
 import { Transport } from './transport';
 import { Context } from './context';
-import { SenzorOptions, ActiveTrace, TaskRun } from './types';
+import { SenzorOptions, ActiveTrace, TaskRun, SenzorLog } from './types';
 import { randomUUID } from 'crypto';
 import { instrumentHttp, instrumentFetch } from '../instrumentation/http';
 import { instrumentMongo } from '../instrumentation/mongo';
@@ -8,6 +8,22 @@ import { instrumentPg } from '../instrumentation/pg';
 import { instrumentBullMQ } from '../instrumentation/bullmq';
 import { instrumentNodeCron } from '../instrumentation/cron';
 import { SDK_META } from '../utils/sdkMeta';
+import { parseTraceparent } from '../utils/traceContext';
+
+const generateW3CTraceId = () => randomUUID().replace(/-/g, '');
+
+// Memory-safe JSON stringifier to handle cyclical objects 
+// (like Express 'req' objects) passed into console.log
+const safeStringify = (obj: any): string => {
+  const cache = new Set();
+  return JSON.stringify(obj, (key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (cache.has(value)) return '[Circular]';
+      cache.add(value);
+    }
+    return value;
+  });
+};
 
 export class SenzorClient {
   private transport: Transport | null = null;
@@ -27,21 +43,101 @@ export class SenzorClient {
 
     if (!this.isInstrumented) {
       this.setupGlobalErrorHandlers();
+      this.setupLogInterception(); // Fire up Auto Log Instrumentation
 
       try { instrumentHttp(endpoint, debug); } catch (e) { }
       try { instrumentFetch(endpoint, debug); } catch (e) { }
       try { instrumentMongo(debug); } catch (e) { }
       try { instrumentPg(); } catch (e) { }
 
-      // Task Integrations (NEW)
+      // Task Integrations 
       try { instrumentBullMQ(this, debug); } catch (e) { }
       try { instrumentNodeCron(this, debug); } catch (e) { }
 
       this.isInstrumented = true;
-      if (debug) console.log('[Senzor] Auto-instrumentation & Error Tracking enabled');
+      if (debug) console.log('[Senzor] Auto-instrumentation enabled');
     }
   }
 
+  // --- Enterprise Auto-Log Interception ---
+  private setupLogInterception() {
+    if (this.options?.autoLogs === false) return; // Opt-out check
+
+    const levels = ['log', 'info', 'warn', 'error', 'debug'] as const;
+    const originalConsole = {
+      log: console.log,
+      info: console.info,
+      warn: console.warn,
+      error: console.error,
+      debug: console.debug
+    };
+
+    let isIntercepting = false; // Lock to prevent SDK internal logs from looping infinitely
+
+    levels.forEach(level => {
+      console[level] = (...args: any[]) => {
+        // Always execute original console so user's terminal isn't broken
+        originalConsole[level].apply(console, args);
+
+        if (isIntercepting || !this.transport) return;
+        isIntercepting = true;
+
+        try {
+          let message = '';
+          let attributes: Record<string, any> = {};
+
+          args.forEach(arg => {
+            if (typeof arg === 'string') {
+              message += (message ? ' ' : '') + arg;
+            } else if (arg instanceof Error) {
+              message += (message ? ' ' : '') + arg.message;
+              attributes.errorStack = arg.stack;
+              attributes.errorName = arg.name;
+            } else if (typeof arg === 'object' && arg !== null) {
+              try {
+                // New Relic Style Destructuring: Merge all object keys into `attributes`
+                const parsed = JSON.parse(safeStringify(arg));
+                attributes = { ...attributes, ...parsed };
+              } catch (e) {
+                attributes.unparseableObject = true;
+              }
+            } else {
+              message += (message ? ' ' : '') + String(arg);
+            }
+          });
+
+          // Fallback if the user purely logged an object without text e.g., console.log({ user: 123 })
+          if (!message && Object.keys(attributes).length > 0) {
+            message = 'Object Log';
+          }
+
+          // Attach to Active Context seamlessly (Works for BOTH APM and Tasks!)
+          const currentTrace = Context.current();
+          const logType = currentTrace?.contextType === 'task' ? 'task' : 'apm';
+
+          const logPayload: SenzorLog = {
+            message: message || 'Empty log',
+            level: level === 'log' ? 'info' : level, // Map generic log -> info
+            attributes,
+            timestamp: new Date().toISOString()
+          };
+
+          // Attach the specific contextual ID
+          if (currentTrace) {
+            if (logType === 'task') logPayload.runId = currentTrace.id;
+            else logPayload.traceId = currentTrace.id;
+          }
+
+          this.transport.addLog(logPayload, logType);
+        } catch (e) {
+          // Absolute failure isolation. Never crash host app during logging.
+        } finally {
+          isIntercepting = false; // Release lock
+        }
+      };
+    });
+  }
+
   private setupGlobalErrorHandlers() {
     if ((process as any).__senzorGlobalHandlersInstalled) {
       return;
@@ -94,21 +190,14 @@ export class SenzorClient {
         }
         const enrichedMeta = {
           ...meta,
-          runtime: {
-            name: 'node',
-            version: process.version
-          },
+          runtime: { name: 'node', version: process.version },
           process: getProcessContext(),
           memory: getMemoryContext(),
-          sdk: {
-            name: SDK_META.name,
-            version: SDK_META.version
-          }
+          sdk: { name: SDK_META.name, version: SDK_META.version }
         };
 
         this.captureError(parsedError, enrichedMeta);
       } catch (internalFailure) {
-        // NEVER allow SDK to crash host app
         try {
           if (this.options?.debug) {
             console.error('[Senzor] Error handler failure:', internalFailure);
@@ -117,76 +206,21 @@ export class SenzorClient {
       }
     };
 
-    process.on('uncaughtExceptionMonitor', (error) => {
-      safeCapture(error, {
-        type: 'uncaughtExceptionMonitor',
-        severity: 'fatal'
-      });
-    });
-
-    process.on('uncaughtException', (error) => {
-      safeCapture(error, {
-        type: 'uncaughtException',
-        severity: 'fatal'
-      });
-    });
-
-    process.on('unhandledRejection', (reason) => {
-      safeCapture(reason, {
-        type: 'unhandledRejection',
-        severity: 'error'
-      });
-    });
-
-    process.on('warning', (warning) => {
-      safeCapture(warning, {
-        type: 'processWarning',
-        severity: 'warning'
-      });
-    });
-
-    process.on('multipleResolves', (type, promise, reason) => {
-      safeCapture(reason || new Error('Multiple promise resolves'), {
-        type: 'multipleResolves',
-        resolveType: type,
-        severity: 'warning'
-      });
-    });
-
-    process.on('rejectionHandled', (promise) => {
-      if (this.options?.debug) {
-        try {
-          console.warn('[Senzor] rejectionHandled event detected');
-        } catch { }
-      }
-    });
-
-    process.on('SIGTERM', () => {
-      safeCapture(
-        new Error('Process received SIGTERM'),
-        {
-          type: 'processSignal',
-          signal: 'SIGTERM'
-        }
-      );
-    });
-
-    process.on('SIGINT', () => {
-      safeCapture(
-        new Error('Process received SIGINT'),
-        {
-          type: 'processSignal',
-          signal: 'SIGINT'
-        }
-      );
-    });
+    process.on('uncaughtExceptionMonitor', (error) => safeCapture(error, { type: 'uncaughtExceptionMonitor', severity: 'fatal' }));
+    process.on('uncaughtException', (error) => safeCapture(error, { type: 'uncaughtException', severity: 'fatal' }));
+    process.on('unhandledRejection', (reason) => safeCapture(reason, { type: 'unhandledRejection', severity: 'error' }));
+    process.on('warning', (warning) => safeCapture(warning, { type: 'processWarning', severity: 'warning' }));
+    process.on('multipleResolves', (type, promise, reason) => safeCapture(reason || new Error('Multiple promise resolves'), { type: 'multipleResolves', resolveType: type, severity: 'warning' }));
+    process.on('rejectionHandled', (promise) => { if (this.options?.debug) { try { console.warn('[Senzor] rejectionHandled event detected'); } catch { } } });
+    process.on('SIGTERM', () => safeCapture(new Error('Process received SIGTERM'), { type: 'processSignal', signal: 'SIGTERM' }));
+    process.on('SIGINT', () => safeCapture(new Error('Process received SIGINT'), { type: 'processSignal', signal: 'SIGINT' }));
   }
 
   public startTrace<T>(data: Partial<ActiveTrace['data']> & { headers?: any }, next: () => T): T {
     if (!this.transport) return next();
 
-    let parentTraceId = undefined;
-    let parentSpanId = undefined;
+    let inheritedTraceId: string | undefined = undefined;
+    let inheritedParentSpanId: string | undefined = undefined;
 
     if (data.headers) {
       const getHeader = (key: string) => {
@@ -195,22 +229,27 @@ export class SenzorClient {
         return undefined;
       };
 
-      parentTraceId = getHeader('x-senzor-trace-id');
-      parentSpanId = getHeader('x-senzor-parent-span-id');
-
-      if (Array.isArray(parentTraceId)) parentTraceId = parentTraceId[0];
-      if (Array.isArray(parentSpanId)) parentSpanId = parentSpanId[0];
+      const traceparent = getHeader('traceparent');
+      const parsedContext = parseTraceparent(traceparent);
+
+      if (parsedContext) {
+        inheritedTraceId = parsedContext.traceId;
+        inheritedParentSpanId = parsedContext.parentSpanId;
+      } else {
+        const rawTrace = getHeader('x-senzor-trace-id');
+        const rawSpan = getHeader('x-senzor-parent-span-id');
+        inheritedTraceId = Array.isArray(rawTrace) ? rawTrace[0] : rawTrace;
+        inheritedParentSpanId = Array.isArray(rawSpan) ? rawSpan[0] : rawSpan;
+      }
     }
 
+    const activeTraceId = inheritedTraceId || generateW3CTraceId();
+
     const trace: ActiveTrace = {
-      id: randomUUID(),
-      contextType: 'apm', // Ensure we distinguish APM traces from Background Tasks
+      id: activeTraceId,
+      contextType: 'apm',
       startTime: performance.now(),
-      data: {
-        ...data,
-        parentTraceId,
-        parentSpanId
-      },
+      data: { ...data, parentTraceId: inheritedTraceId, parentSpanId: inheritedParentSpanId },
       spans: []
     };
 
@@ -240,7 +279,6 @@ export class SenzorClient {
     const currentContext = Context.current();
     const triggerTraceId = currentContext?.contextType === 'apm' ? currentContext.id : undefined;
 
-    // Snapshot system resources before execution
     const startMemory = process.memoryUsage ? process.memoryUsage().heapUsed : 0;
     const startCpu = process.cpuUsage ? process.cpuUsage() : undefined;
 
@@ -260,14 +298,13 @@ export class SenzorClient {
     const task = Context.current();
     if (!task || task.contextType !== 'task' || !this.transport) return;
 
-    // Calculate resource deltas
     let resourceMetrics;
     if (process.memoryUsage && task.startMemory !== undefined && process.cpuUsage && task.startCpu) {
       const endMemory = process.memoryUsage().heapUsed;
       const cpuDelta = process.cpuUsage(task.startCpu);
 
       resourceMetrics = {
-        memoryDeltaBytes: endMemory - task.startMemory, // Can be negative if GC ran!
+        memoryDeltaBytes: endMemory - task.startMemory,
         cpuUserUs: cpuDelta.user,
         cpuSystemUs: cpuDelta.system
       };
@@ -280,7 +317,7 @@ export class SenzorClient {
       triggerTraceId: task.data.triggerTraceId,
       queueDelay: task.data.queueDelay,
       attempts: task.data.attempts,
-      isDeadLetter: task.data.isDeadLetter, // Extracted from options/metadata if provided
+      isDeadLetter: task.data.isDeadLetter,
       metadata: { ...task.data.metadata, ...extraMetadata },
       resourceMetrics,
       status,
@@ -308,7 +345,6 @@ export class SenzorClient {
     }) as unknown as T;
   }
 
-  // --- MODIFIED: Context-Aware Error Capture ---
   public captureError(error: unknown, context: any = {}) {
     if (!this.transport) return;
 
@@ -337,7 +373,7 @@ export class SenzorClient {
   }
 
   public track(data: any) {
-    this.transport?.addTrace({ traceId: randomUUID(), ...data, spans: [], timestamp: new Date().toISOString() });
+    this.transport?.addTrace({ traceId: generateW3CTraceId(), ...data, spans: [], timestamp: new Date().toISOString() });
   }
 
   public startSpan(name: string, type: 'db' | 'http' | 'function' | 'custom' = 'custom') {
@@ -345,7 +381,7 @@ export class SenzorClient {
     if (!trace) return { end: () => { } };
     const startTime = performance.now() - trace.startTime;
     const spanStartAbs = performance.now();
-    const spanId = randomUUID();
+    const spanId = randomUUID().replace(/-/g, '').slice(0, 16);
     return { end: (meta?: any, status?: number) => { Context.addSpan({ spanId, name, type, startTime, duration: performance.now() - spanStartAbs, status, meta }); } };
   }
 

package/src/core/transport.ts

@@ -1,11 +1,13 @@
-import { SenzorOptions, Trace, TaskRun, SenzorError } from './types';
+import { SenzorOptions, Trace, TaskRun, SenzorError, SenzorLog } from './types';
 
 export class Transport {
   private traceQueue: Trace[] = [];
   private apmErrorQueue: SenzorError[] = [];
+  private apmLogQueue: SenzorLog[] = []; // APM Logs
 
   private taskQueue: TaskRun[] = [];
   private taskErrorQueue: SenzorError[] = [];
+  private taskLogQueue: SenzorLog[] = []; // Task Logs
 
   private timer: NodeJS.Timeout | null = null;
   private apmEndpoint: string;
@@ -41,40 +43,59 @@ export class Transport {
     this.checkFlush();
   }
 
+  // Add captured log to the correct batch queue
+  public addLog(log: SenzorLog, type: 'apm' | 'task' = 'apm') {
+    if (type === 'task') this.taskLogQueue.push(log);
+    else this.apmLogQueue.push(log);
+    this.checkFlush();
+  }
+
   private checkFlush() {
-    const totalApm = this.traceQueue.length + this.apmErrorQueue.length;
-    const totalTask = this.taskQueue.length + this.taskErrorQueue.length;
+    const totalApm = this.traceQueue.length + this.apmErrorQueue.length + this.apmLogQueue.length;
+    const totalTask = this.taskQueue.length + this.taskErrorQueue.length + this.taskLogQueue.length;
     if (totalApm >= (this.config.batchSize || 100) || totalTask >= (this.config.batchSize || 100)) {
       this.flush();
     }
   }
 
   public async flush() {
-    const apmPayload = { traces: [...this.traceQueue], errors: [...this.apmErrorQueue] };
-    const taskPayload = { runs: [...this.taskQueue], errors: [...this.taskErrorQueue] };
-
+    const apmPayload = {
+      traces: [...this.traceQueue],
+      errors: [...this.apmErrorQueue],
+      logs: [...this.apmLogQueue]
+    };
+    const taskPayload = {
+      runs: [...this.taskQueue],
+      errors: [...this.taskErrorQueue],
+      logs: [...this.taskLogQueue]
+    };
+
+    // Reset Queues instantly
     this.traceQueue = [];
     this.apmErrorQueue = [];
+    this.apmLogQueue = [];
     this.taskQueue = [];
     this.taskErrorQueue = [];
+    this.taskLogQueue = [];
 
     const headers = { 'Content-Type': 'application/json', 'x-service-api-key': this.config.apiKey };
 
     try {
       const promises = [];
 
-      if (apmPayload.traces.length > 0 || apmPayload.errors.length > 0) {
+      // Piggyback logs onto APM/Task batch ingestion to bypass extra network round-trips
+      if (apmPayload.traces.length > 0 || apmPayload.errors.length > 0 || apmPayload.logs.length > 0) {
         promises.push(fetch(this.apmEndpoint, { method: 'POST', headers, body: JSON.stringify(apmPayload), keepalive: true }));
       }
 
-      if (taskPayload.runs.length > 0 || taskPayload.errors.length > 0) {
+      if (taskPayload.runs.length > 0 || taskPayload.errors.length > 0 || taskPayload.logs.length > 0) {
         promises.push(fetch(this.taskEndpoint, { method: 'POST', headers, body: JSON.stringify(taskPayload), keepalive: true }));
       }
 
       await Promise.allSettled(promises);
 
       if (this.config.debug) {
-        console.log(`[Senzor] Flushed: ${apmPayload.traces.length} traces, ${taskPayload.runs.length} tasks`);
+        console.log(`[Senzor] Flushed: APM(${apmPayload.traces.length} traces, ${apmPayload.logs.length} logs), Task(${taskPayload.runs.length} runs, ${taskPayload.logs.length} logs)`);
       }
     } catch (err) {
       if (this.config.debug) console.error('[Senzor] Transport Flush Error:', err);

package/src/core/types.ts

@@ -4,6 +4,7 @@ export interface SenzorOptions {
   batchSize?: number;
   flushInterval?: number;
   debug?: boolean;
+  autoLogs?: boolean;
 }
 
 export interface Span {
@@ -26,6 +27,17 @@ export interface SenzorError {
   timestamp: string;
 }
 
+// NEW: Enterprise Log Payload
+export interface SenzorLog {
+  message: string;
+  level: 'info' | 'warn' | 'error' | 'debug' | 'fatal';
+  attributes: Record<string, any>;
+  traceId?: string; // Used if context is APM
+  runId?: string;   // Used if context is Task
+  spanId?: string;
+  timestamp: string;
+}
+
 export interface Trace {
   traceId: string;
   parentTraceId?: string;

package/src/instrumentation/http.ts

@@ -3,6 +3,7 @@ import https from 'https';
 import { URL } from 'url';
 import { Context } from '../core/context';
 import { randomUUID } from 'crypto';
+import { generateTraceparent } from '../utils/traceContext';
 
 const shimmer = (module: any, methodName: string, wrapper: (original: Function) => Function) => {
   if (!module[methodName]) return;
@@ -10,6 +11,9 @@ const shimmer = (module: any, methodName: string, wrapper: (original: Function)
   module[methodName] = wrapper(original);
 };
 
+// 16-char hex for W3C standard spans
+const generateSpanId = () => randomUUID().replace(/-/g, '').slice(0, 16);
+
 // --- FETCH INSTRUMENTATION ---
 export const instrumentFetch = (ingestUrl: string, debug = false) => {
   if (!globalThis.fetch) return;
@@ -38,16 +42,14 @@ export const instrumentFetch = (ingestUrl: string, debug = false) => {
     const method = (init?.method || 'GET').toUpperCase();
     const startTime = performance.now() - trace.startTime;
     const spanStartAbs = performance.now();
-    const spanId = randomUUID();
+    const spanId = generateSpanId();
 
     let hostname = 'unknown';
     try { hostname = new URL(urlStr).hostname; } catch (e) { }
 
-    // Inject Headers
     const newInit = { ...init } as RequestInit;
     if (!newInit.headers) newInit.headers = {};
 
-    // Helper to set header on various types
     const setHeader = (key: string, value: string) => {
       if (newInit.headers instanceof Headers) {
         newInit.headers.set(key, value);
@@ -58,35 +60,21 @@ export const instrumentFetch = (ingestUrl: string, debug = false) => {
       }
     };
 
+    // W3C Trace Context Injection
+    setHeader('traceparent', generateTraceparent(trace.id, spanId));
+
+    // Legacy fallback for older Senzor services
     setHeader('x-senzor-trace-id', trace.id);
     setHeader('x-senzor-parent-span-id', spanId);
 
     try {
       const response = await originalFetch(input, newInit);
-
       const duration = performance.now() - spanStartAbs;
-      Context.addSpan({
-        spanId,
-        name: `${method} ${hostname}`,
-        type: 'http',
-        startTime,
-        duration,
-        status: response.status,
-        meta: { url: urlStr, method, library: 'fetch' }
-      });
-
+      Context.addSpan({ spanId, name: `${method} ${hostname}`, type: 'http', startTime, duration, status: response.status, meta: { url: urlStr, method, library: 'fetch' } });
       return response;
     } catch (err: any) {
       const duration = performance.now() - spanStartAbs;
-      Context.addSpan({
-        spanId,
-        name: `${method} ${hostname}`,
-        type: 'http',
-        startTime,
-        duration,
-        status: 500,
-        meta: { error: err.message, url: urlStr, library: 'fetch' }
-      });
+      Context.addSpan({ spanId, name: `${method} ${hostname}`, type: 'http', startTime, duration, status: 500, meta: { error: err.message, url: urlStr, library: 'fetch' } });
       throw err;
     }
   };
@@ -103,7 +91,6 @@ export const instrumentHttp = (ingestUrl: string, debug = false) => {
       let urlStr = '';
       let optionsIndex = 0;
 
-      // Parsing Logic: http.request(url, options, cb) OR http.request(options, cb)
       if (typeof args[0] === 'string' || args[0] instanceof URL) {
         urlStr = args[0].toString();
         optionsIndex = 1;
@@ -111,13 +98,11 @@ export const instrumentHttp = (ingestUrl: string, debug = false) => {
         optionsIndex = 0;
       }
 
-      // Ensure options object exists at correct index
       if (!args[optionsIndex] || typeof args[optionsIndex] !== 'object') {
         args[optionsIndex] = {};
       }
       options = args[optionsIndex];
 
-      // Construct URL if missing
       if (!urlStr) {
         const protocol = options.protocol || (options.port === 443 ? 'https:' : 'http:');
         const host = options.hostname || options.host || 'localhost';
@@ -125,7 +110,6 @@ export const instrumentHttp = (ingestUrl: string, debug = false) => {
         urlStr = `${protocol}//${host}${path}`;
       }
 
-      // Guard
       if (ingestHost && (urlStr.includes(ingestHost) || (options.hostname && options.hostname.includes(ingestHost)))) {
         return original.apply(this, args);
       }
@@ -136,33 +120,27 @@ export const instrumentHttp = (ingestUrl: string, debug = false) => {
       const method = (options.method || 'GET').toUpperCase();
       const startTime = performance.now() - trace.startTime;
       const spanStartAbs = performance.now();
-      const spanId = randomUUID();
+      const spanId = generateSpanId();
 
       let hostname = 'unknown';
       try { hostname = new URL(urlStr).hostname; } catch (e) { hostname = options.hostname || 'unknown'; }
 
-      // Inject Headers (Mutate the options object reference directly)
       if (!options.headers) options.headers = {};
+
+      // W3C Trace Context Injection
+      options.headers['traceparent'] = generateTraceparent(trace.id, spanId);
+
+      // Legacy fallback
       options.headers['x-senzor-trace-id'] = trace.id;
       options.headers['x-senzor-parent-span-id'] = spanId;
 
-      // Debug
-      if (debug) console.log(`[Senzor] Injecting headers to ${urlStr}`);
+      if (debug) console.log(`[Senzor] Injecting W3C traceparent headers to ${urlStr}`);
 
-      // Call Original
       const req = original.apply(this, args);
 
       const captureSpan = (res: any, error?: Error) => {
         const duration = performance.now() - spanStartAbs;
-        Context.addSpan({
-          spanId,
-          name: `${method} ${hostname}`,
-          type: 'http',
-          startTime,
-          duration,
-          status: error ? 500 : res?.statusCode || 0,
-          meta: { url: urlStr, method, library: 'http' }
-        });
+        Context.addSpan({ spanId, name: `${method} ${hostname}`, type: 'http', startTime, duration, status: error ? 500 : res?.statusCode || 0, meta: { url: urlStr, method, library: 'http' } });
       };
 
       req.on('response', (res: any) => {

package/src/utils/traceContext.ts

@@ -0,0 +1,44 @@
+/**
+ * W3C Trace Context Implementation
+ * Standard: https://www.w3.org/TR/trace-context/
+ * Format: 00-{traceId}-{spanId}-{traceFlags}
+ */
+
+export interface TraceContext {
+  traceId: string;
+  parentSpanId: string;
+  sampled: boolean;
+}
+
+const TRACEPARENT_REGEX = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export const parseTraceparent = (header?: string | string[]): TraceContext | null => {
+  if (!header) return null;
+
+  const traceparent = Array.isArray(header) ? header[0] : header;
+  if (typeof traceparent !== 'string') return null;
+
+  const match = traceparent.trim().toLowerCase().match(TRACEPARENT_REGEX);
+  if (!match) return null;
+
+  const traceId = match[1];
+  const parentSpanId = match[2];
+  const flags = match[3];
+
+  // Invalid IDs according to W3C specification
+  if (traceId === '00000000000000000000000000000000') return null;
+  if (parentSpanId === '0000000000000000') return null;
+
+  // The least significant bit of flags indicates if the trace is sampled
+  const sampled = (parseInt(flags, 16) & 0x01) === 0x01;
+
+  return { traceId, parentSpanId, sampled };
+};
+
+/**
+ * Generates a valid W3C traceparent header string for OUTGOING requests.
+ */
+export const generateTraceparent = (traceId: string, spanId: string, sampled: boolean = true): string => {
+  const flags = sampled ? '01' : '00';
+  return `00-${traceId}-${spanId}-${flags}`;
+};