@senzops/apm-node 1.2.8 → 1.3.0

package/src/instrumentation/mistral.ts

@@ -0,0 +1,254 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Mistral AI SDK Instrumentation
+//
+// Instruments the official `@mistralai/mistralai` package.
+//
+// Mistral SDK architecture: The `Mistral` class has resource namespaces
+// (chat, fim, embeddings, classifiers, models, agents, files, etc.) that
+// each have async methods returning promises.
+//
+// The SDK also has an internal `_request` or `_fetch` method on the base
+// client. We patch both the high-level resource methods AND the internal
+// dispatch for full coverage.
+//
+// Patches:
+//   - Mistral.prototype methods (post, get, etc.) — internal HTTP dispatch
+//   - chat.complete() / chat.stream() — via resource namespaces
+//   - embeddings.create()
+//   - fim.complete() / fim.stream()
+//   - classifiers.moderate() / classifiers.moderateChat()
+//
+// Captured attributes (OTel GenAI semantic conventions):
+//   - gen_ai.system: 'mistral'
+//   - gen_ai.request.model: mistral-large, codestral, etc.
+//   - gen_ai.operation.name: chat, embeddings, fim, classify
+//   - gen_ai.usage.input_tokens: prompt tokens
+//   - gen_ai.usage.output_tokens: completion tokens
+//   - gen_ai.response.model: actual model from response
+//   - gen_ai.response.finish_reason: stop, length, etc.
+// ---------------------------------------------------------------------------
+
+/** Extract token usage from Mistral response. */
+const extractMistralUsage = (result: any): Record<string, any> => {
+  const meta: Record<string, any> = {};
+
+  if (result?.usage) {
+    meta['gen_ai.usage.input_tokens'] = result.usage.promptTokens ?? result.usage.prompt_tokens;
+    meta['gen_ai.usage.output_tokens'] = result.usage.completionTokens ?? result.usage.completion_tokens;
+    meta['gen_ai.usage.total_tokens'] = result.usage.totalTokens ?? result.usage.total_tokens;
+  }
+
+  if (result?.model) {
+    meta['gen_ai.response.model'] = result.model;
+  }
+
+  const finishReason = result?.choices?.[0]?.finishReason
+    ?? result?.choices?.[0]?.finish_reason;
+  if (finishReason) {
+    meta['gen_ai.response.finish_reason'] = finishReason;
+  }
+
+  return meta;
+};
+
+// ---------------------------------------------------------------------------
+// Resource method patching
+// ---------------------------------------------------------------------------
+
+/** Patch a specific method on a resource namespace object. */
+const patchResourceMethod = (
+  resource: any,
+  methodName: string,
+  operation: string,
+  getModel: (args: any[]) => string | undefined,
+  extractUsage: (result: any) => Record<string, any>,
+  patchKey: string,
+  options?: SenzorOptions
+) => {
+  if (!resource || typeof resource[methodName] !== 'function') return;
+
+  patchMethod(
+    resource,
+    methodName,
+    patchKey,
+    (original) =>
+      function patchedMistralMethod(this: any, ...args: any[]) {
+        const model = getModel(args);
+        const spanName = model
+          ? `Mistral ${operation} ${model}`
+          : `Mistral ${operation}`;
+
+        const span = startCapturedSpan(
+          spanName,
+          'http',
+          {
+            'gen_ai.system': 'mistral',
+            'gen_ai.operation.name': operation,
+            'gen_ai.request.model': model,
+            library: 'mistral',
+          },
+          options
+        );
+
+        if (!span) return original.apply(this, args);
+
+        return runWithCapturedSpan(span, () => {
+          try {
+            const result = original.apply(this, args);
+
+            if (result && typeof result.then === 'function') {
+              return result.then(
+                (value: any) => {
+                  span.end(0, extractUsage(value));
+                  return value;
+                },
+                (error: any) => {
+                  span.end(error?.statusCode || error?.status || 500, {
+                    'error.message': error?.message,
+                    'error.type': error?.name || 'MistralError',
+                  });
+                  throw error;
+                }
+              );
+            }
+
+            span.end(0);
+            return result;
+          } catch (error: any) {
+            span.end(500, { 'error.message': error?.message });
+            throw error;
+          }
+        });
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Mistral client patching
+// ---------------------------------------------------------------------------
+
+const patchMistralClient = (mistralModule: any, options?: SenzorOptions) => {
+  const Mistral = mistralModule?.Mistral
+    || mistralModule?.MistralClient
+    || mistralModule?.default;
+
+  if (!Mistral || typeof Mistral !== 'function') return;
+
+  const proto = Mistral.prototype;
+  if (!proto) return;
+
+  // Patch internal HTTP methods on the client prototype
+  const httpMethods = ['post', 'get', 'put', 'patch', 'delete'] as const;
+  for (const method of httpMethods) {
+    if (typeof proto[method] !== 'function') continue;
+
+    patchMethod(
+      proto,
+      method,
+      `senzor.mistral.client.${method}`,
+      (original) =>
+        function patchedHttpMethod(this: any, path: string, ...args: any[]) {
+          const body = args[0]?.body || args[0];
+          const model = body?.model;
+          const operation = path?.replace(/^\/?(v1\/)?/, '').split('/')[0] || 'api';
+
+          const spanName = model
+            ? `Mistral ${operation} ${model}`
+            : `Mistral ${operation}`;
+
+          const span = startCapturedSpan(
+            spanName,
+            'http',
+            {
+              'gen_ai.system': 'mistral',
+              'gen_ai.operation.name': operation,
+              'gen_ai.request.model': model,
+              'http.request.method': method.toUpperCase(),
+              'url.path': path,
+              library: 'mistral',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, path, ...args);
+
+          return runWithCapturedSpan(span, () => {
+            try {
+              const result = original.call(this, path, ...args);
+
+              if (result && typeof result.then === 'function') {
+                return result.then(
+                  (value: any) => {
+                    span.end(0, extractMistralUsage(value));
+                    return value;
+                  },
+                  (error: any) => {
+                    span.end(error?.status || 500, {
+                      'error.message': error?.message,
+                    });
+                    throw error;
+                  }
+                );
+              }
+
+              span.end(0);
+              return result;
+            } catch (error: any) {
+              span.end(500, { 'error.message': error?.message });
+              throw error;
+            }
+          });
+        }
+    );
+  }
+
+  // Try to patch resource namespaces on instances
+  // These are created in the constructor, so we wrap the constructor
+  try {
+    const tempClient = new Mistral({ apiKey: '__senzor_probe__' });
+
+    // Patch chat resource
+    if (tempClient.chat) {
+      const chatProto = Object.getPrototypeOf(tempClient.chat);
+      if (chatProto) {
+        patchResourceMethod(chatProto, 'complete', 'chat', (a) => a[0]?.model, extractMistralUsage, 'senzor.mistral.chat.complete', options);
+        patchResourceMethod(chatProto, 'stream', 'chat.stream', (a) => a[0]?.model, () => ({}), 'senzor.mistral.chat.stream', options);
+      }
+    }
+
+    // Patch embeddings resource
+    if (tempClient.embeddings) {
+      const embedProto = Object.getPrototypeOf(tempClient.embeddings);
+      if (embedProto) {
+        patchResourceMethod(embedProto, 'create', 'embeddings', (a) => a[0]?.model, extractMistralUsage, 'senzor.mistral.embeddings.create', options);
+      }
+    }
+
+    // Patch fim resource
+    if ((tempClient as any).fim) {
+      const fimProto = Object.getPrototypeOf((tempClient as any).fim);
+      if (fimProto) {
+        patchResourceMethod(fimProto, 'complete', 'fim', (a) => a[0]?.model, extractMistralUsage, 'senzor.mistral.fim.complete', options);
+        patchResourceMethod(fimProto, 'stream', 'fim.stream', (a) => a[0]?.model, () => ({}), 'senzor.mistral.fim.stream', options);
+      }
+    }
+  } catch {
+    // Mistral constructor may require a real API key — resource patching is best-effort
+    // The HTTP method patches on the prototype still cover all calls
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentMistral = (options?: SenzorOptions) => {
+  hookRequire('@mistralai/mistralai', (exports: any) => {
+    patchMistralClient(exports, options);
+  });
+};

package/src/instrumentation/nestjs.ts

@@ -0,0 +1,243 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// NestJS Instrumentation
+//
+// Instruments @nestjs/core at the router execution layer:
+//   - RouterExecutionContext.prototype.create() — wraps the handler factory
+//     so every controller method invocation generates a span with:
+//       nestjs.controller, nestjs.method, nestjs.route, http.route
+//
+// This captures the full NestJS request lifecycle including guards,
+// interceptors, pipes, and the controller method execution.
+//
+// Works with both Express and Fastify adapters since we patch at the
+// NestJS layer above the HTTP adapter.
+// ---------------------------------------------------------------------------
+
+/** Extract a human-readable name from a NestJS controller class. */
+const getControllerName = (instance: any): string => {
+  if (!instance) return 'UnknownController';
+  return instance.constructor?.name || 'UnknownController';
+};
+
+// ---------------------------------------------------------------------------
+// RouterExecutionContext patching
+// ---------------------------------------------------------------------------
+
+const patchRouterExecutionContext = (nestCore: any, options?: SenzorOptions) => {
+  // Try to access RouterExecutionContext from the module
+  let RouterExecutionContext: any;
+
+  try {
+    RouterExecutionContext = require('@nestjs/core/router/router-execution-context')?.RouterExecutionContext;
+  } catch { }
+
+  // Fallback: search in exports
+  if (!RouterExecutionContext) {
+    RouterExecutionContext = nestCore?.RouterExecutionContext;
+  }
+
+  if (!RouterExecutionContext?.prototype?.create) return;
+
+  patchMethod(
+    RouterExecutionContext.prototype,
+    'create',
+    'senzor.nestjs.routerExecutionContext.create',
+    (original) =>
+      function patchedCreate(
+        this: any,
+        instance: any,
+        callback: Function,
+        methodName: string,
+        moduleKey: string,
+        requestMethod: number,
+        ...rest: any[]
+      ) {
+        const handler = original.call(this, instance, callback, methodName, moduleKey, requestMethod, ...rest);
+
+        if (typeof handler !== 'function') return handler;
+
+        const controllerName = getControllerName(instance);
+
+        return function wrappedNestHandler(this: any, req: any, res: any, next: any) {
+          // Extract route from request
+          const route = req?.route?.path || req?.url?.split('?')[0] || '/';
+
+          const span = startCapturedSpan(
+            `NestJS ${controllerName}.${methodName}`,
+            'function',
+            {
+              'nestjs.controller': controllerName,
+              'nestjs.method': methodName,
+              'nestjs.module': moduleKey,
+              'nestjs.type': 'request_handler',
+              'http.route': route,
+            },
+            options
+          );
+
+          if (!span) return handler.call(this, req, res, next);
+
+          return runWithCapturedSpan(span, () => {
+            try {
+              const result = handler.call(this, req, res, next);
+
+              if (result && typeof result.then === 'function') {
+                return result.then(
+                  (val: any) => {
+                    span.end(0);
+                    return val;
+                  },
+                  (error: any) => {
+                    span.end(500, {
+                      'error.message': error?.message,
+                      'error.type': error?.name || 'Error',
+                    });
+                    throw error;
+                  }
+                );
+              }
+
+              span.end(0);
+              return result;
+            } catch (error: any) {
+              span.end(500, {
+                'error.message': error?.message,
+                'error.type': error?.name || 'Error',
+              });
+              throw error;
+            }
+          });
+        };
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// RouterExplorer patching (alternative / complementary)
+// ---------------------------------------------------------------------------
+
+const patchRouterExplorer = (nestCore: any, options?: SenzorOptions) => {
+  let RouterExplorer: any;
+
+  try {
+    RouterExplorer = require('@nestjs/core/router/router-explorer')?.RouterExplorer;
+  } catch { }
+
+  if (!RouterExplorer) {
+    RouterExplorer = nestCore?.RouterExplorer;
+  }
+
+  if (!RouterExplorer?.prototype?.applyCallbackToRouter) return;
+
+  patchMethod(
+    RouterExplorer.prototype,
+    'applyCallbackToRouter',
+    'senzor.nestjs.routerExplorer.applyCallbackToRouter',
+    (original) =>
+      function patchedApplyCallback(
+        this: any,
+        router: any,
+        routeDefinition: any,
+        instanceWrapper: any,
+        moduleKey: string,
+        ...rest: any[]
+      ) {
+        // Extract metadata before registration
+        const methodName = routeDefinition?.methodName || 'unknown';
+        const path = routeDefinition?.path || '/';
+        const requestMethod = routeDefinition?.requestMethod;
+
+        const controllerName = instanceWrapper?.metatype?.name
+          || instanceWrapper?.name
+          || 'UnknownController';
+
+        // Let NestJS register the route normally
+        const result = original.call(this, router, routeDefinition, instanceWrapper, moduleKey, ...rest);
+
+        // Log registration for debug
+        if (options?.debug) {
+          console.log(`[Senzor] NestJS route registered: ${controllerName}.${methodName} → ${path}`);
+        }
+
+        return result;
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentNestJS = (options?: SenzorOptions) => {
+  hookRequire('@nestjs/core', (exports: any) => {
+    patchRouterExecutionContext(exports, options);
+    patchRouterExplorer(exports, options);
+  });
+
+  // Also try the specific sub-module paths (varies by NestJS version)
+  hookRequire('@nestjs/core/router/router-execution-context', (exports: any) => {
+    if (exports?.RouterExecutionContext?.prototype?.create) {
+      patchMethod(
+        exports.RouterExecutionContext.prototype,
+        'create',
+        'senzor.nestjs.rec.create.direct',
+        (original) =>
+          function patchedCreateDirect(
+            this: any,
+            instance: any,
+            callback: Function,
+            methodName: string,
+            moduleKey: string,
+            requestMethod: number,
+            ...rest: any[]
+          ) {
+            const handler = original.call(this, instance, callback, methodName, moduleKey, requestMethod, ...rest);
+            if (typeof handler !== 'function') return handler;
+
+            const controllerName = getControllerName(instance);
+
+            return function wrappedHandler(this: any, req: any, res: any, next: any) {
+              const route = req?.route?.path || req?.url?.split('?')[0] || '/';
+
+              const span = startCapturedSpan(
+                `NestJS ${controllerName}.${methodName}`,
+                'function',
+                {
+                  'nestjs.controller': controllerName,
+                  'nestjs.method': methodName,
+                  'nestjs.module': moduleKey,
+                  'nestjs.type': 'request_handler',
+                  'http.route': route,
+                },
+                options
+              );
+
+              if (!span) return handler.call(this, req, res, next);
+
+              return runWithCapturedSpan(span, () => {
+                try {
+                  const result = handler.call(this, req, res, next);
+                  if (result && typeof result.then === 'function') {
+                    return result.then(
+                      (val: any) => { span.end(0); return val; },
+                      (err: any) => { span.end(500, { 'error.message': err?.message }); throw err; }
+                    );
+                  }
+                  span.end(0);
+                  return result;
+                } catch (err: any) {
+                  span.end(500, { 'error.message': err?.message });
+                  throw err;
+                }
+              });
+            };
+          }
+      );
+    }
+  });
+};

package/src/instrumentation/net.ts

@@ -0,0 +1,171 @@
+import { SenzorOptions } from '../core/types';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Net (TCP) Instrumentation
+//
+// Instruments Node.js core `net` module:
+//   - net.connect() / net.createConnection()  — TCP connection spans
+//   - net.Socket.prototype.connect()          — socket-level connection
+//
+// Captures TCP connection establishment latency and peer information.
+// Follows OTel semantic conventions: net.peer.name, net.peer.port, net.transport
+//
+// NOTE: This instrumentation only captures connection establishment, not
+// data transfer. This prevents excessive span noise while still providing
+// visibility into network bottlenecks (slow connects, timeouts, refused).
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize connection options from the various net.connect() signatures:
+ *   - connect(port, host, cb)
+ *   - connect({ port, host }, cb)
+ *   - connect(path, cb)        — IPC / Unix domain socket
+ *   - connect({ path }, cb)    — IPC / Unix domain socket
+ */
+const normalizeConnectArgs = (
+  args: any[]
+): { host: string; port: number | string; isIPC: boolean } => {
+  const first = args[0];
+
+  // Object form: { port, host } or { path }
+  if (typeof first === 'object' && first !== null && !Array.isArray(first)) {
+    if (first.path) {
+      return { host: first.path, port: 'ipc', isIPC: true };
+    }
+    return {
+      host: first.host || 'localhost',
+      port: first.port || 0,
+      isIPC: false,
+    };
+  }
+
+  // String form: path (IPC)
+  if (typeof first === 'string' && !Number.isFinite(Number(first))) {
+    return { host: first, port: 'ipc', isIPC: true };
+  }
+
+  // Numeric form: port, [host]
+  const port = Number(first) || 0;
+  const host = typeof args[1] === 'string' ? args[1] : 'localhost';
+  return { host, port, isIPC: false };
+};
+
+// ---------------------------------------------------------------------------
+// Patching
+// ---------------------------------------------------------------------------
+
+const patchSocketConnect = (netModule: any, options?: SenzorOptions) => {
+  const socketProto = netModule?.Socket?.prototype;
+  if (!socketProto) return;
+
+  patchMethod(
+    socketProto,
+    'connect',
+    'senzor.net.socket.connect',
+    (original) =>
+      function patchedSocketConnect(this: any, ...args: any[]) {
+        const { host, port, isIPC } = normalizeConnectArgs(args);
+
+        const spanName = isIPC
+          ? `TCP connect ${host}`
+          : `TCP connect ${host}:${port}`;
+
+        const span = startCapturedSpan(
+          spanName,
+          'custom',
+          {
+            'net.peer.name': host,
+            'net.peer.port': isIPC ? undefined : port,
+            'net.transport': isIPC ? 'unix' : 'tcp',
+            'network.transport': isIPC ? 'unix' : 'tcp',
+          },
+          options
+        );
+
+        if (!span) return original.apply(this, args);
+
+        return runWithCapturedSpan(span, () => {
+          const socket = original.apply(this, args);
+
+          let ended = false;
+          const endOnce = (status: number, meta: Record<string, any> = {}) => {
+            if (ended) return;
+            ended = true;
+            span.end(status, meta);
+          };
+
+          // Connection established successfully
+          socket.once('connect', () => {
+            endOnce(0, {
+              'net.peer.address': socket.remoteAddress,
+              'net.peer.port': socket.remotePort,
+              'net.local.address': socket.localAddress,
+              'net.local.port': socket.localPort,
+            });
+          });
+
+          // Connection failed
+          socket.once('error', (err: any) => {
+            endOnce(500, {
+              'error.message': err?.message,
+              'error.type': err?.code || err?.name || 'NetError',
+              'net.error_code': err?.code,
+            });
+          });
+
+          // Connection timed out
+          socket.once('timeout', () => {
+            endOnce(504, {
+              'error.message': 'Connection timed out',
+              'error.type': 'TimeoutError',
+            });
+          });
+
+          // Connection closed before establishing
+          socket.once('close', (hadError: boolean) => {
+            if (hadError) {
+              endOnce(500, {
+                'error.message': 'Connection closed with error',
+              });
+            } else {
+              endOnce(0);
+            }
+          });
+
+          return socket;
+        });
+      }
+  );
+};
+
+/**
+ * Patch net.connect() and net.createConnection() factory functions.
+ * These create a new Socket and immediately call socket.connect().
+ * Since we patch Socket.prototype.connect, these are automatically covered.
+ * However, we add a thin wrapper for consistency in span naming.
+ */
+const patchNetFactories = (netModule: any, options?: SenzorOptions) => {
+  // net.connect and net.createConnection are usually the same function
+  // Since we patch Socket.prototype.connect, the factory functions are
+  // automatically instrumented. No additional patching needed.
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentNet = (options?: SenzorOptions) => {
+  let net: any;
+  try {
+    net = require('net');
+  } catch {
+    return;
+  }
+
+  if (!net) return;
+
+  patchSocketConnect(net, options);
+  patchNetFactories(net, options);
+};