@senzops/apm-node 1.0.1 → 1.1.0

package/src/core/client.ts

@@ -1,43 +1,73 @@
 import { Transport } from './transport';
-
-export interface SenzorOptions {
-  apiKey: string;
-  endpoint?: string;
-  batchSize?: number;
-  flushInterval?: number;
-  debug?: boolean;
-}
+import { Context } from './context';
+import { SenzorOptions, ActiveTrace } from './types';
+import { randomUUID } from 'crypto';
+import { instrumentHttp } from '../instrumentation/http';
+import { instrumentMongo } from '../instrumentation/mongo';
+import { instrumentPg } from '../instrumentation/pg';
 
 export class SenzorClient {
   private transport: Transport | null = null;
   private options: SenzorOptions | null = null;
+  private isInstrumented = false;
 
   public init(options: SenzorOptions) {
     if (!options.apiKey) {
       console.warn('[Senzor] API Key missing. SDK disabled.');
       return;
     }
-
-    this.options = {
-      endpoint: 'https://api.senzor.dev/api/ingest/apm',
-      batchSize: 100,
-      flushInterval: 10000,
-      debug: false,
-      ...options
-    };
+    this.options = options;
+    const endpoint = options.endpoint || 'https://api.senzor.dev/api/ingest/apm';
 
     this.transport = new Transport({
-      apiKey: this.options.apiKey,
-      endpoint: this.options.endpoint!,
-      batchSize: this.options.batchSize!,
-      flushInterval: this.options.flushInterval!,
-      debug: this.options.debug || false
+      ...options,
+      endpoint
     });
 
-    if (this.options.debug) console.log('[Senzor] Initialized');
+    if (!this.isInstrumented) {
+      try { instrumentHttp(endpoint); } catch (e) { }
+      try { instrumentMongo(); } catch (e) { }
+      try { instrumentPg(); } catch (e) { }
+
+      this.isInstrumented = true;
+      if (options.debug) console.log('[Senzor] Auto-instrumentation enabled');
+    }
+
+    if (options.debug) console.log('[Senzor] Initialized');
+  }
+
+  public startTrace<T>(data: Partial<ActiveTrace['data']>, next: () => T): T {
+    if (!this.transport) return next();
+
+    const trace: ActiveTrace = {
+      id: randomUUID(),
+      startTime: performance.now(),
+      data: data,
+      spans: []
+    };
+
+    return Context.run(trace, next);
+  }
+
+  public endTrace(status: number, extraData: any = {}) {
+    const trace = Context.current();
+    if (!trace || !this.transport) return;
+
+    const duration = performance.now() - trace.startTime;
+
+    const payload = {
+      traceId: trace.id,
+      ...trace.data,
+      ...extraData,
+      status,
+      duration,
+      spans: trace.spans,
+      timestamp: new Date().toISOString()
+    };
+
+    this.transport.add(payload);
   }
 
-  // --- Manual Tracking (For any framework) ---
   public track(data: {
     method: string;
     route: string;
@@ -48,14 +78,37 @@ export class SenzorClient {
     userAgent?: string;
   }) {
     if (!this.transport) return;
-
-    this.transport.add({
+    const payload = {
+      traceId: randomUUID(),
       ...data,
+      spans: [],
       timestamp: new Date().toISOString()
-    });
+    };
+    this.transport.add(payload);
+  }
+
+  public startSpan(name: string, type: 'db' | 'http' | 'function' | 'custom' = 'custom') {
+    const trace = Context.current();
+    if (!trace) return { end: () => { } };
+
+    const startTime = performance.now() - trace.startTime;
+    const spanStartAbs = performance.now();
+
+    return {
+      end: (meta?: any, status?: number) => {
+        const duration = performance.now() - spanStartAbs;
+        Context.addSpan({
+          name,
+          type,
+          startTime,
+          duration,
+          status,
+          meta
+        });
+      }
+    };
   }
 
-  // --- Force Flush (For Serverless/Lambda) ---
   public async flush() {
     if (this.transport) await this.transport.flush();
   }

package/src/core/context.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { ActiveTrace } from './types';
+
+// Storage to hold the current Trace for any async operation
+export const storage = new AsyncLocalStorage<ActiveTrace>();
+
+export const Context = {
+  // Run a function within a trace context
+  // Updated to be Generic <T> to allow returning values (Promises, etc)
+  run: <T>(trace: ActiveTrace, fn: () => T): T => {
+    return storage.run(trace, fn);
+  },
+
+  // Get current trace (safe)
+  current: (): ActiveTrace | undefined => {
+    return storage.getStore();
+  },
+
+  // Add a span to the current trace
+  addSpan: (span: any) => {
+    const store = storage.getStore();
+    if (store) {
+      store.spans.push(span);
+    }
+  }
+};

package/src/core/transport.ts

@@ -1,31 +1,21 @@
-export interface TransportConfig {
-  apiKey: string;
-  endpoint: string;
-  batchSize: number;
-  flushInterval: number;
-  debug: boolean;
-}
+import { SenzorOptions } from './types';
 
 export class Transport {
   private queue: any[] = [];
-  private config: TransportConfig;
-  private timer: any = null;
+  private timer: NodeJS.Timeout | null = null;
 
-  constructor(config: TransportConfig) {
-    this.config = config;
-    // Only start timer in non-serverless environments (long running processes)
+  constructor(private config: SenzorOptions) {
     if (typeof setInterval !== 'undefined') {
-      this.timer = setInterval(() => this.flush(), this.config.flushInterval);
-      // Unref if in Node.js to allow process exit
+      this.timer = setInterval(() => this.flush(), config.flushInterval || 10000);
       if (this.timer && typeof this.timer.unref === 'function') {
-        this.timer.unref();
+        this.timer.unref(); // Don't block process exit
       }
     }
   }
 
-  public add(event: any) {
-    this.queue.push(event);
-    if (this.queue.length >= this.config.batchSize) {
+  public add(trace: any) {
+    this.queue.push(trace);
+    if (this.queue.length >= (this.config.batchSize || 100)) {
       this.flush();
     }
   }
@@ -37,22 +27,21 @@ export class Transport {
     this.queue = [];
 
     try {
-      // Use native fetch (Node 18+, Edge, Browser)
-      await fetch(this.config.endpoint, {
+      // Use global fetch (Node 18+)
+      await fetch(this.config.endpoint || 'https://api.senzor.dev/api/ingest/apm', {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'x-service-api-key': this.config.apiKey,
         },
         body: JSON.stringify(batch),
-        // keepalive ensures connection stays open even if function ends (vital for APM)
         keepalive: true,
       });
-
+      
       if (this.config.debug) console.log(`[Senzor] Flushed ${batch.length} traces`);
     } catch (err) {
       if (this.config.debug) console.error('[Senzor] Ingestion Error:', err);
-      // We drop data on failure to prevent memory leaks in the app
+      // Dropping data to prevent memory leaks is preferred in APM
     }
   }
 }

package/src/core/types.ts

@@ -0,0 +1,37 @@
+export interface SenzorOptions {
+  apiKey: string;
+  endpoint?: string;
+  batchSize?: number;
+  flushInterval?: number; // ms
+  debug?: boolean;
+}
+
+export interface Span {
+  name: string;
+  type: 'db' | 'http' | 'function' | 'custom';
+  startTime: number; // Relative to trace start
+  duration: number;
+  status?: number;
+  meta?: Record<string, any>;
+}
+
+export interface Trace {
+  traceId: string;
+  method: string;
+  route: string; // Normalized
+  path: string;  // Raw
+  status: number;
+  duration: number;
+  ip?: string;
+  userAgent?: string;
+  timestamp: string;
+  spans: Span[];
+}
+
+// Internal interface for an active trace object
+export interface ActiveTrace {
+  id: string;
+  startTime: number;
+  data: Partial<Trace>;
+  spans: Span[];
+}

package/src/index.ts

@@ -1,14 +1,14 @@
-import { client, SenzorOptions } from './core/client';
+import { client } from './core/client';
 import { expressMiddleware } 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),
 
   // Express / Connect
   requestHandler: expressMiddleware,

package/src/instrumentation/http.ts

@@ -0,0 +1,94 @@
+import http from 'http';
+import https from 'https';
+import { URL } from 'url';
+import { Context } from '../core/context';
+
+// Helper to safely wrap modules
+const shimmer = (module: any, methodName: string, wrapper: (original: Function) => Function) => {
+  if (!module[methodName]) return;
+  const original = module[methodName];
+  module[methodName] = wrapper(original);
+};
+
+export const instrumentHttp = (ingestUrl: string) => {
+  const ingestHost = new URL(ingestUrl).hostname;
+
+  const requestWrapper = (original: Function) => {
+    return function (this: any, ...args: any[]) {
+      // 1. Parse Arguments to get URL
+      let options: any = {};
+      let urlStr = '';
+
+      if (typeof args[0] === 'string' || args[0] instanceof URL) {
+        urlStr = args[0].toString();
+        options = args[1] || {};
+      } else {
+        options = args[0] || {};
+        const protocol = options.protocol || 'http:';
+        const host = options.hostname || options.host || 'localhost';
+        const path = options.path || '/';
+        urlStr = `${protocol}//${host}${path}`;
+      }
+
+      // 2. SAFETY GUARD: Ignore calls to Senzor Ingest API (Prevent Infinite Loop)
+      if (urlStr.includes(ingestHost) || (options.hostname && options.hostname.includes(ingestHost))) {
+        return original.apply(this, args);
+      }
+
+      // 3. Check if we are inside an Active Trace
+      // If we are not handling a user request, don't trace background http calls
+      const trace = Context.current();
+      if (!trace) {
+        return original.apply(this, args);
+      }
+
+      // 4. Start Span
+      const method = (options.method || 'GET').toUpperCase();
+      const startTime = performance.now() - trace.startTime; // Relative to trace start
+      const spanStartAbs = performance.now();
+
+      // 5. Execute Request
+      const req = original.apply(this, args);
+
+      // 6. Hook into Response/Error
+      req.on('response', (res: any) => {
+        // Wait for end of stream to calculate full duration (TTFB + Download)
+        res.on('end', () => {
+          const duration = performance.now() - spanStartAbs;
+          
+          Context.addSpan({
+            name: `${method} ${new URL(urlStr).hostname}`, // e.g. "GET api.stripe.com"
+            type: 'http',
+            startTime,
+            duration,
+            status: res.statusCode,
+            meta: {
+              url: urlStr,
+              method: method,
+            }
+          });
+        });
+      });
+
+      req.on('error', (err: Error) => {
+        const duration = performance.now() - spanStartAbs;
+        Context.addSpan({
+          name: `${method} ${urlStr}`,
+          type: 'http',
+          startTime,
+          duration,
+          status: 500, // Client Error
+          meta: { error: err.message }
+        });
+      });
+
+      return req;
+    };
+  };
+
+  // Apply patches
+  shimmer(http, 'request', requestWrapper);
+  shimmer(http, 'get', requestWrapper);
+  shimmer(https, 'request', requestWrapper);
+  shimmer(https, 'get', requestWrapper);
+};

package/src/instrumentation/mongo.ts

@@ -0,0 +1,77 @@
+import { Context } from '../core/context';
+
+export const instrumentMongo = () => {
+  try {
+    const mongodb = require('mongodb');
+    const Collection = mongodb.Collection;
+
+    const methods = [
+      'find',
+      'findOne',
+      'insertOne',
+      'insertMany',
+      'updateOne',
+      'updateMany',
+      'deleteOne',
+      'deleteMany',
+      'aggregate',
+      'countDocuments'
+    ];
+
+    methods.forEach((method) => {
+      if (!Collection.prototype[method]) return;
+
+      const original = Collection.prototype[method];
+
+      Collection.prototype[method] = function (...args: any[]) {
+        const trace = Context.current();
+        // If not inside a tracked request, just run normally
+        if (!trace) return original.apply(this, args);
+
+        const startTime = performance.now() - trace.startTime;
+        const spanStartAbs = performance.now();
+        const collectionName = this.collectionName;
+
+        // Helper to finish span
+        const endSpan = (err?: Error) => {
+          const duration = performance.now() - spanStartAbs;
+          Context.addSpan({
+            name: `MongoDB ${method} (${collectionName})`,
+            type: 'db',
+            startTime,
+            duration,
+            status: err ? 500 : 0,
+            meta: {
+              collection: collectionName,
+              operation: method,
+              error: err ? err.message : undefined
+            }
+          });
+        };
+
+        try {
+          const result = original.apply(this, args);
+
+          // Handle Promise/Cursor
+          if (result && typeof result.then === 'function') {
+            return result.then(
+              (res: any) => { endSpan(); return res; },
+              (err: any) => { endSpan(err); throw err; }
+            );
+          }
+          // Handle FindCursor (it doesn't execute immediately, but for APM visuals we mark start/return)
+          // Ideally we'd wrap toArray() but that's complex. For 'find', we just mark the creation.
+          endSpan();
+          return result;
+
+        } catch (err: any) {
+          endSpan(err);
+          throw err;
+        }
+      };
+    });
+
+  } catch (e) {
+    // User doesn't use mongodb, ignore
+  }
+};

package/src/instrumentation/pg.ts

@@ -0,0 +1,41 @@
+import { Context } from '../core/context';
+
+// Simple shim for 'pg' library
+export const instrumentPg = () => {
+  try {
+    // Try to require pg (it might not be installed by user)
+    const pg = require('pg');
+    const originalQuery = pg.Client.prototype.query;
+
+    pg.Client.prototype.query = function (...args: any[]) {
+      const trace = Context.current();
+      if (!trace) return originalQuery.apply(this, args);
+
+      const startTime = performance.now() - trace.startTime;
+      const spanStartAbs = performance.now();
+
+      // Extract SQL (first arg usually string or config object)
+      const sql = typeof args[0] === 'string' ? args[0] : args[0].text;
+
+      // Wrap callback if present, or handle Promise
+      const result = originalQuery.apply(this, args);
+
+      if (result && typeof result.then === 'function') {
+        return result.then((res: any) => {
+          const duration = performance.now() - spanStartAbs;
+          Context.addSpan({
+            name: 'Postgres Query',
+            type: 'db',
+            startTime,
+            duration,
+            meta: { query: sql }
+          });
+          return res;
+        });
+      }
+      return result;
+    };
+  } catch (e) {
+    // User doesn't use pg, ignore
+  }
+};

package/src/middleware/express.ts

@@ -2,42 +2,32 @@ import { client } from '../core/client';
 
 export const expressMiddleware = () => {
   return (req: any, res: any, next: () => void) => {
-    // Start Timer (High Precision)
-    const start = performance.now();
+    // 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'],
+    }, () => {
 
-    // Hook into response finish
-    res.once('finish', () => {
-      try {
-        const duration = performance.now() - start;
+      res.once('finish', () => {
+        try {
+          let route = 'UNKNOWN';
+          if (req.route && req.route.path) {
+            route = (req.baseUrl || '') + req.route.path;
+          } else if (res.statusCode === 404) {
+            route = 'Not Found';
+          } else {
+            route = req.path || 'Wildcard';
+          }
 
-        // Route Normalization Logic
-        // Express stores route info in req.route
-        let route = 'UNKNOWN';
-
-        if (req.route && req.route.path) {
-          // Combined baseUrl (if mounted on /api) + path (/:id)
-          route = (req.baseUrl || '') + req.route.path;
-        } else if (res.statusCode === 404) {
-          route = 'Not Found';
-        } else {
-          // Fallback for unmapped routes or static files
-          route = req.path || 'Wildcard';
+          client.endTrace(res.statusCode, { route });
+        } catch (e) {
+          // Fail open
         }
+      });
 
-        client.track({
-          method: req.method,
-          route: route,
-          path: req.originalUrl || req.url,
-          status: res.statusCode,
-          duration: duration,
-          ip: req.ip || req.socket?.remoteAddress,
-          userAgent: req.headers['user-agent'],
-        });
-      } catch (e) {
-        // Fail open
-      }
+      next();
     });
-
-    next();
   };
 };

package/src/wrappers/fastify.ts

@@ -1,5 +1,5 @@
 import { client } from '../core/client';
-import { SenzorOptions } 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) => {

package/src/wrappers/h3.ts

@@ -1,49 +1,37 @@
 import { client } from '../core/client';
 import { getRoute } from '../core/normalizer';
 
-// Types for H3 (Mocked to avoid heavy peer dependencies)
+// Minimal types for H3 to avoid peer-deps
 type EventHandler = (event: any) => any;
 
 export const wrapH3 = (handler: EventHandler) => {
-  return async (event: any) => {
-    const start = performance.now();
-    let status = 200;
-    let error: any = null;
+  return (event: any) => {
+    const req = event.node.req;
+    const path = req.originalUrl || req.url || '/';
 
-    try {
-      const response = await handler(event);
-      // Try to determine status from response or event
-      if (event.node?.res?.statusCode) {
-        status = event.node.res.statusCode;
-      }
-      return response;
-    } catch (err: any) {
-      error = err;
-      status = err.statusCode || err.status || 500;
-      throw err;
-    } finally {
-      // Non-blocking collection
-      const duration = performance.now() - start;
-      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'],
+    }, async () => {
+      try {
+        const response = await handler(event);
 
-      client.track({
-        method: req.method || 'GET',
-        route: getRoute(event, path), // H3 often attaches context to event
-        path: path,
-        status: status,
-        duration: duration,
-        ip: getIp(req),
-        userAgent: req.headers['user-agent'],
-      });
+        // 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;
 
-      // If serverless, we might need to await flush, but for general H3 usage (Node preset)
-      // we assume the process stays alive or uses ctx.waitUntil
-    }
+        client.endTrace(status, { route: getRoute(event, path) });
+        return response;
+      } catch (err: any) {
+        const status = err.statusCode || err.status || 500;
+        client.endTrace(status, { route: getRoute(event, path) });
+        throw err;
+      }
+    });
   };
-};
-
-const getIp = (req: any) => {
-  return req.headers['x-forwarded-for'] || req.socket?.remoteAddress;
 };