@senzops/apm-node 1.1.3 → 1.1.5

package/src/core/context.ts

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from 'async_hooks';
-import { ActiveTrace } from './types';
+import { ActiveTrace, TraceError } from './types';
 
 export const storage = new AsyncLocalStorage<ActiveTrace>();
 
@@ -16,11 +16,18 @@ export const Context = {
     const store = storage.getStore();
     if (store) {
       store.spans.push(span);
-    } else {
-      // If we are here, something tried to add a span but lost context
-      // This is common if users await inside a callback that wasn't bound
-      // However, usually silent failure is preferred in production APM
-      console.warn('[Senzor] Lost context for span:', span.name);
+    }
+  },
+
+  // Attach error to current trace
+  setError: (error: Error) => {
+    const store = storage.getStore();
+    if (store) {
+      store.error = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      };
     }
   }
 };

package/src/core/types.ts

@@ -2,36 +2,49 @@ export interface SenzorOptions {
   apiKey: string;
   endpoint?: string;
   batchSize?: number;
-  flushInterval?: number; // ms
+  flushInterval?: number;
   debug?: boolean;
 }
 
 export interface Span {
+  spanId: string; // NEW: Unique ID for this span
   name: string;
   type: 'db' | 'http' | 'function' | 'custom';
-  startTime: number; // Relative to trace start
+  startTime: number;
   duration: number;
   status?: number;
   meta?: Record<string, any>;
 }
 
+export interface TraceError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
 export interface Trace {
   traceId: string;
+
+  // Distributed Tracing Fields
+  parentTraceId?: string; // NEW
+  parentSpanId?: string;  // NEW
+
   method: string;
-  route: string; // Normalized
-  path: string;  // Raw
+  route: string;
+  path: string;
   status: number;
   duration: number;
   ip?: string;
   userAgent?: string;
   timestamp: string;
   spans: Span[];
+  error?: TraceError;
 }
 
-// Internal interface for an active trace object
 export interface ActiveTrace {
   id: string;
   startTime: number;
   data: Partial<Trace>;
   spans: Span[];
+  error?: TraceError;
 }

package/src/index.ts

@@ -1,23 +1,26 @@
 import { client } from './core/client';
-import { expressMiddleware } from './middleware/express';
+import { expressMiddleware, expressErrorHandler } from './middleware/express';
 import { wrapH3 } from './wrappers/h3';
 import { wrapNextRoute, wrapNextPages } from './wrappers/next';
 import { senzorPlugin } from './wrappers/fastify';
 import { SenzorOptions } from './core/types';
 
 const Senzor = {
-  // Core
   init: (options: SenzorOptions) => client.init(options),
   flush: () => client.flush(),
+  track: client.track.bind(client),
+  startSpan: client.startSpan.bind(client),
+  captureException: client.captureError.bind(client),
 
-  // Express / Connect
+  // Express
   requestHandler: expressMiddleware,
+  errorHandler: expressErrorHandler,
 
-  // Next.js
-  wrapNextRoute, // For App Router (Route Handlers)
-  wrapNextPages, // For Pages Router (API Routes)
+  // Next
+  wrapNextRoute,
+  wrapNextPages,
 
-  // H3 / Nuxt / Nitro
+  // H3
   wrapH3,
 
   // Fastify

package/src/instrumentation/http.ts

@@ -2,6 +2,7 @@ import http from 'http';
 import https from 'https';
 import { URL } from 'url';
 import { Context } from '../core/context';
+import { randomUUID } from 'crypto';
 
 const shimmer = (module: any, methodName: string, wrapper: (original: Function) => Function) => {
   if (!module[methodName]) return;
@@ -9,7 +10,7 @@ const shimmer = (module: any, methodName: string, wrapper: (original: Function)
   module[methodName] = wrapper(original);
 };
 
-// --- Native Fetch Instrumentation (Node 18+) ---
+// --- FETCH INSTRUMENTATION (Node 18+ / Edge) ---
 export const instrumentFetch = (ingestUrl: string, debug = false) => {
   if (!globalThis.fetch) return;
 
@@ -24,7 +25,7 @@ export const instrumentFetch = (ingestUrl: string, debug = false) => {
     let urlStr = '';
     if (typeof input === 'string') urlStr = input;
     else if (input instanceof URL) urlStr = input.toString();
-    else if (input && input.url) urlStr = input.url; // Request object
+    else if (input && (input as any).url) urlStr = (input as any).url;
 
     // 2. Infinite Loop Guard
     if (ingestHost && urlStr.includes(ingestHost)) {
@@ -37,21 +38,45 @@ export const instrumentFetch = (ingestUrl: string, debug = false) => {
       return originalFetch(input, init);
     }
 
-    // 4. Start Span
+    // 4. Prepare Metadata & ID
     const method = (init?.method || 'GET').toUpperCase();
     const startTime = performance.now() - trace.startTime;
     const spanStartAbs = performance.now();
+    const spanId = randomUUID(); // New ID for this specific outbound call
+
     let hostname = 'unknown';
     try { hostname = new URL(urlStr).hostname; } catch (e) { }
 
-    if (debug) console.log(`[Senzor] Tracking Fetch: ${method} ${hostname}`);
+    if (debug) console.log(`[Senzor] Fetch: ${method} ${hostname}`);
+
+    // 5. Inject Distributed Tracing Headers
+    // We need to clone init or create it to avoid mutating original ref unexpectedly
+    const newInit = { ...init };
+    if (!newInit.headers) {
+      newInit.headers = {};
+    }
+
+    // Handle different Header formats (Headers object vs plain object)
+    if (newInit.headers instanceof Headers) {
+      newInit.headers.set('x-senzor-trace-id', trace.id);
+      newInit.headers.set('x-senzor-parent-span-id', spanId);
+    } else if (Array.isArray(newInit.headers)) {
+      newInit.headers.push(['x-senzor-trace-id', trace.id]);
+      newInit.headers.push(['x-senzor-parent-span-id', spanId]);
+    } else {
+      // Plain object
+      (newInit.headers as any)['x-senzor-trace-id'] = trace.id;
+      (newInit.headers as any)['x-senzor-parent-span-id'] = spanId;
+    }
 
     try {
-      const response = await originalFetch(input, init);
+      // 6. Execute Fetch
+      const response = await originalFetch(input, newInit);
 
-      // 5. End Span
+      // 7. Record Span
       const duration = performance.now() - spanStartAbs;
       Context.addSpan({
+        spanId,
         name: `${method} ${hostname}`,
         type: 'http',
         startTime,
@@ -64,6 +89,7 @@ export const instrumentFetch = (ingestUrl: string, debug = false) => {
     } catch (err: any) {
       const duration = performance.now() - spanStartAbs;
       Context.addSpan({
+        spanId,
         name: `${method} ${hostname}`,
         type: 'http',
         startTime,
@@ -76,12 +102,10 @@ export const instrumentFetch = (ingestUrl: string, debug = false) => {
   };
 };
 
-// --- Standard HTTP/HTTPS Instrumentation ---
+// --- HTTP/HTTPS INSTRUMENTATION ---
 export const instrumentHttp = (ingestUrl: string, debug = false) => {
   let ingestHost = '';
-  try {
-    ingestHost = new URL(ingestUrl).hostname;
-  } catch (e) { }
+  try { ingestHost = new URL(ingestUrl).hostname; } catch (e) { }
 
   const requestWrapper = (original: Function) => {
     return function (this: any, ...args: any[]) {
@@ -109,14 +133,22 @@ 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(); // Generate ID
+
       let hostname = 'unknown';
       try { hostname = new URL(urlStr).hostname; } catch (e) { hostname = options.hostname || 'unknown'; }
 
+      // Inject Headers
+      if (!options.headers) options.headers = {};
+      options.headers['x-senzor-trace-id'] = trace.id;
+      options.headers['x-senzor-parent-span-id'] = spanId;
+
       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,
@@ -128,6 +160,7 @@ export const instrumentHttp = (ingestUrl: string, debug = false) => {
 
       req.on('response', (res: any) => {
         res.once('end', () => captureSpan(res));
+        res.once('close', () => captureSpan(res)); // Safety if stream not consumed
         res.once('error', (err: Error) => captureSpan(res, err));
       });
 

package/src/middleware/express.ts

@@ -1,18 +1,21 @@
 import { client } from '../core/client';
 
+// 1. Request Handler (Place before routes)
 export const expressMiddleware = () => {
   return (req: any, res: any, next: () => void) => {
-    // We MUST use startTrace to enable Auto-Instrumentation for this request
     client.startTrace({
       method: req.method,
       path: req.originalUrl || req.url,
       ip: req.ip || req.socket?.remoteAddress,
       userAgent: req.headers['user-agent'],
+      headers: req.headers
     }, () => {
 
+      // Auto-detect status code on finish
       res.once('finish', () => {
         try {
           let route = 'UNKNOWN';
+          // Express populates req.route only if a route matched
           if (req.route && req.route.path) {
             route = (req.baseUrl || '') + req.route.path;
           } else if (res.statusCode === 404) {
@@ -22,12 +25,23 @@ export const expressMiddleware = () => {
           }
 
           client.endTrace(res.statusCode, { route });
-        } catch (e) {
-          // Fail open
-        }
+        } catch (e) { /* Fail open */ }
       });
 
       next();
     });
   };
+};
+
+// 2. Error Handler (Place after routes)
+// This is required in Express to capture the actual Error Object (Stack Trace)
+export const expressErrorHandler = () => {
+  return (err: any, req: any, res: any, next: (err?: any) => void) => {
+
+    // 1. Capture the exception context
+    client.captureError(err);
+
+    // 2. Pass it to the next error handler (don't swallow it)
+    next(err);
+  };
 };

package/src/wrappers/fastify.ts

@@ -1,37 +1,29 @@
 import { client } from '../core/client';
 import { SenzorOptions } from '../core/types';
 
-// We don't import Fastify types to keep zero-deps, but structure matches
 export const senzorPlugin = (fastify: any, options: SenzorOptions, done: Function) => {
-
-  // Init if options provided inline, otherwise assume global init
   if (options && options.apiKey) {
     client.init(options);
   }
 
-  // Hook: On Request (Start Timer)
   fastify.addHook('onRequest', (request: any, reply: any, next: Function) => {
-    request.senzorStart = performance.now();
-    next();
-  });
-
-  // Hook: On Response (End Timer & Track)
-  fastify.addHook('onResponse', (request: any, reply: any, next: Function) => {
-    const duration = performance.now() - (request.senzorStart || performance.now());
-
-    // Fastify provides 'routerPath' (e.g. /user/:id)
-    const route = request.routeOptions?.url || request.routerPath;
-
-    client.track({
+    client.startTrace({
       method: request.method,
-      route: route || 'UNKNOWN',
       path: request.raw.url || request.url,
-      status: reply.statusCode,
-      duration: duration,
       ip: request.ip,
-      userAgent: request.headers['user-agent']
-    });
+      userAgent: request.headers['user-agent'],
+      headers: request.headers // Pass headers
+    }, () => next());
+  });
+
+  fastify.addHook('onError', (request: any, reply: any, error: any, next: Function) => {
+    client.captureError(error);
+    next();
+  });
 
+  fastify.addHook('onResponse', (request: any, reply: any, next: Function) => {
+    const route = request.routeOptions?.url || request.routerPath || 'UNKNOWN';
+    client.endTrace(reply.statusCode, { route });
     next();
   });
 

package/src/wrappers/h3.ts

@@ -1,7 +1,6 @@
 import { client } from '../core/client';
 import { getRoute } from '../core/normalizer';
 
-// Minimal types for H3 to avoid peer-deps
 type EventHandler = (event: any) => any;
 
 export const wrapH3 = (handler: EventHandler) => {
@@ -9,25 +8,23 @@ export const wrapH3 = (handler: EventHandler) => {
     const req = event.node.req;
     const path = req.originalUrl || req.url || '/';
 
-    // Start Trace Context
     return client.startTrace({
       method: req.method || 'GET',
       path: path,
       ip: req.headers['x-forwarded-for'] || req.socket?.remoteAddress,
       userAgent: req.headers['user-agent'],
+      headers: req.headers // Pass headers
     }, async () => {
       try {
         const response = await handler(event);
-
-        // H3/Nitro response status
         let status = 200;
         if (event.node.res.statusCode) status = event.node.res.statusCode;
-        // Check if response is an error object
         if (response && response.statusCode) status = response.statusCode;
 
         client.endTrace(status, { route: getRoute(event, path) });
         return response;
       } catch (err: any) {
+        client.captureError(err);
         const status = err.statusCode || err.status || 500;
         client.endTrace(status, { route: getRoute(event, path) });
         throw err;

package/src/wrappers/next.ts

@@ -1,29 +1,50 @@
 import { client } from '../core/client';
 import { normalizePath } from '../core/normalizer';
 
-// --- App Router Wrapper (Route Handlers) ---
+// --- App Router Wrapper ---
 export const wrapNextRoute = (handler: Function) => {
   return async (req: Request | any, context?: any) => {
-    // 1. Extract Info
+
+    // Extract info from Web Standard Request
     const url = req.url ? new URL(req.url) : { pathname: '/' };
     const method = req.method || 'GET';
-    const ua = req.headers.get ? req.headers.get('user-agent') : undefined;
-    const ip = req.headers.get ? req.headers.get('x-forwarded-for') : undefined;
 
-    // 2. Run in Context
+    // Header Extraction
+    let headers: Record<string, string> = {};
+    let ua: string | undefined;
+    let ip: string | undefined;
+
+    if (typeof req.headers.get === 'function') {
+      // It's a Web Request Object
+      ua = req.headers.get('user-agent');
+      ip = req.headers.get('x-forwarded-for');
+
+      // Convert to plain object for trace context extraction
+      req.headers.forEach((value: string, key: string) => {
+        headers[key] = value;
+      });
+    } else {
+      // It's a Node Request Object (rare in App router but possible)
+      headers = req.headers;
+      ua = headers['user-agent'];
+      ip = headers['x-forwarded-for'] as string;
+    }
+
     return client.startTrace({
       method,
       path: url.pathname,
       userAgent: ua,
-      ip: ip
+      ip: ip,
+      headers: headers // Pass extracted headers
     }, async () => {
       try {
         const response = await handler(req, context);
         const status = response?.status || 200;
-        
+
         client.endTrace(status, { route: normalizePath(url.pathname) });
         return response;
       } catch (err: any) {
+        client.captureError(err);
         client.endTrace(500, { route: normalizePath(url.pathname) });
         throw err;
       }
@@ -31,33 +52,30 @@ export const wrapNextRoute = (handler: Function) => {
   };
 };
 
-// --- Pages Router Wrapper (API Routes) ---
+// --- Pages Router Wrapper ---
 export const wrapNextPages = (handler: Function) => {
   return async (req: any, res: any) => {
     const path = req.url ? req.url.split('?')[0] : '/';
-    
-    // 1. Run in Context
+
     return client.startTrace({
       method: req.method || 'GET',
       path: path,
       userAgent: req.headers['user-agent'],
       ip: req.headers['x-forwarded-for'] || req.socket?.remoteAddress,
+      headers: req.headers // Standard Node headers work fine
     }, async () => {
-      
-      // 2. Hook Response
+
       const done = () => {
         client.endTrace(res.statusCode || 200, { route: normalizePath(path) });
       };
-      
+
       res.once('finish', done);
-      res.once('close', done); // Fallback if finish doesn't fire
+      res.once('close', done);
 
-      // 3. Execute
       try {
         return await handler(req, res);
-      } catch (e) {
-        // Next.js Pages router usually handles errors internally, 
-        // but we ensure we catch sync errors here
+      } catch (e: any) {
+        client.captureError(e);
         throw e;
       }
     });