@senzops/apm-node 1.2.8 → 1.3.0

package/src/instrumentation/openai.ts

@@ -0,0 +1,281 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// OpenAI SDK Instrumentation
+//
+// Instruments the official `openai` npm package (v4+) to capture API calls
+// to OpenAI services (GPT, DALL-E, Whisper, Embeddings, Assistants, etc.).
+//
+// Strategy: Patch the core APIClient._request() method — the single
+// dispatch point for ALL OpenAI API calls. This covers:
+//   - chat.completions.create()
+//   - completions.create()
+//   - embeddings.create()
+//   - images.generate()
+//   - audio.transcriptions.create()
+//   - moderations.create()
+//   - files.*, fine_tuning.*, assistants.*, threads.*, etc.
+//
+// Also patches specific resource methods for richer attribute capture
+// (model name, token usage, etc.).
+//
+// Captured attributes (following emerging GenAI OTel conventions):
+//   - gen_ai.system: 'openai'
+//   - gen_ai.request.model: model name (gpt-4, gpt-3.5-turbo, etc.)
+//   - gen_ai.operation.name: chat, completions, embeddings, etc.
+//   - gen_ai.response.model: actual model used in response
+//   - gen_ai.usage.input_tokens: prompt tokens
+//   - gen_ai.usage.output_tokens: completion tokens
+//   - gen_ai.request.max_tokens: requested max tokens
+//   - gen_ai.request.temperature: temperature setting
+//   - http.response.status_code: API response status
+// ---------------------------------------------------------------------------
+
+/** Map of resource path segments to operation names. */
+const OPERATION_MAP: Record<string, string> = {
+  'chat/completions': 'chat',
+  completions: 'completions',
+  embeddings: 'embeddings',
+  images: 'images',
+  'images/generations': 'images.generate',
+  'images/edits': 'images.edit',
+  'images/variations': 'images.variation',
+  'audio/transcriptions': 'audio.transcribe',
+  'audio/translations': 'audio.translate',
+  'audio/speech': 'audio.speech',
+  moderations: 'moderations',
+  'fine_tuning/jobs': 'fine_tuning',
+  files: 'files',
+  assistants: 'assistants',
+  threads: 'threads',
+  'threads/runs': 'threads.runs',
+  'threads/messages': 'threads.messages',
+  batches: 'batches',
+  'vector_stores': 'vector_stores',
+};
+
+/** Extract operation name from the API path. */
+const getOperationName = (path: string): string => {
+  if (!path) return 'unknown';
+
+  // Normalize path: strip leading slash, version prefix
+  const normalized = path.replace(/^\/?(v1\/)?/, '').replace(/\/[a-f0-9-]{20,}(\/|$)/g, '/');
+
+  // Try exact match first, then prefix match
+  for (const [pattern, name] of Object.entries(OPERATION_MAP)) {
+    if (normalized === pattern || normalized.startsWith(pattern + '/')) {
+      return name;
+    }
+  }
+
+  // Fallback: first path segment
+  return normalized.split('/')[0] || 'api';
+};
+
+/** Extract model from request body. */
+const getRequestModel = (body: any): string | undefined => {
+  if (!body || typeof body !== 'object') return undefined;
+  return body.model || undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Core APIClient._request patching
+// ---------------------------------------------------------------------------
+
+const patchOpenAIClient = (openaiModule: any, options?: SenzorOptions) => {
+  // openai v4 exports OpenAI class (default export)
+  const OpenAI = openaiModule?.OpenAI || openaiModule?.default || openaiModule;
+
+  if (!OpenAI || typeof OpenAI !== 'function') return;
+
+  const proto = OpenAI.prototype;
+  if (!proto) return;
+
+  // Find the internal request method — could be _request, post, get, etc.
+  // In openai v4, the base client (APIClient) has these methods:
+  // post(), get(), put(), patch(), delete() which all call _request()
+
+  // Patch the HTTP methods on the 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.openai.client.${method}`,
+      (original) =>
+        function patchedMethod(this: any, path: string, opts?: any) {
+          const operationName = getOperationName(path);
+          const model = getRequestModel(opts?.body);
+          const httpMethod = method.toUpperCase();
+
+          const spanName = model
+            ? `OpenAI ${operationName} ${model}`
+            : `OpenAI ${operationName}`;
+
+          const span = startCapturedSpan(
+            spanName,
+            'http',
+            {
+              'gen_ai.system': 'openai',
+              'gen_ai.operation.name': operationName,
+              'gen_ai.request.model': model,
+              'gen_ai.request.max_tokens': opts?.body?.max_tokens,
+              'gen_ai.request.temperature': opts?.body?.temperature,
+              'http.request.method': httpMethod,
+              'url.path': path,
+              library: 'openai',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, path, opts);
+
+          return runWithCapturedSpan(span, () => {
+            try {
+              const result = original.call(this, path, opts);
+
+              if (result && typeof result.then === 'function') {
+                return result.then(
+                  (response: any) => {
+                    const endMeta: Record<string, any> = {};
+
+                    // Extract usage from response
+                    if (response?.usage) {
+                      endMeta['gen_ai.usage.input_tokens'] = response.usage.prompt_tokens;
+                      endMeta['gen_ai.usage.output_tokens'] = response.usage.completion_tokens;
+                      endMeta['gen_ai.usage.total_tokens'] = response.usage.total_tokens;
+                    }
+
+                    // Extract actual model used
+                    if (response?.model) {
+                      endMeta['gen_ai.response.model'] = response.model;
+                    }
+
+                    // Extract finish reason
+                    if (response?.choices?.[0]?.finish_reason) {
+                      endMeta['gen_ai.response.finish_reason'] = response.choices[0].finish_reason;
+                    }
+
+                    span.end(0, endMeta);
+                    return response;
+                  },
+                  (error: any) => {
+                    const statusCode = error?.status || error?.statusCode || 500;
+                    span.end(statusCode, {
+                      'error.message': error?.message,
+                      'error.type': error?.name || error?.type || 'OpenAIError',
+                      'http.response.status_code': statusCode,
+                      'gen_ai.error.code': error?.code,
+                    });
+                    throw error;
+                  }
+                );
+              }
+
+              span.end(0);
+              return result;
+            } catch (error: any) {
+              const statusCode = error?.status || 500;
+              span.end(statusCode, {
+                'error.message': error?.message,
+                'error.type': error?.name || 'Error',
+                'http.response.status_code': statusCode,
+              });
+              throw error;
+            }
+          });
+        }
+    );
+  }
+
+  // Also try to patch the internal request dispatcher
+  if (typeof proto._request === 'function') {
+    patchMethod(
+      proto,
+      '_request',
+      'senzor.openai.client._request',
+      (original) =>
+        function patchedRequest(this: any, requestOptions: any, ...args: any[]) {
+          // _request receives the full request options object
+          const path = requestOptions?.path || '';
+          const method = requestOptions?.method || 'POST';
+          const operationName = getOperationName(path);
+          const model = getRequestModel(requestOptions?.body);
+
+          const spanName = model
+            ? `OpenAI ${operationName} ${model}`
+            : `OpenAI ${operationName}`;
+
+          const span = startCapturedSpan(
+            spanName,
+            'http',
+            {
+              'gen_ai.system': 'openai',
+              'gen_ai.operation.name': operationName,
+              'gen_ai.request.model': model,
+              'http.request.method': method,
+              'url.path': path,
+              library: 'openai',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, requestOptions, ...args);
+
+          return runWithCapturedSpan(span, () => {
+            try {
+              const result = original.call(this, requestOptions, ...args);
+
+              if (result && typeof result.then === 'function') {
+                return result.then(
+                  (response: any) => {
+                    const endMeta: Record<string, any> = {};
+
+                    if (response?.usage) {
+                      endMeta['gen_ai.usage.input_tokens'] = response.usage.prompt_tokens;
+                      endMeta['gen_ai.usage.output_tokens'] = response.usage.completion_tokens;
+                    }
+                    if (response?.model) {
+                      endMeta['gen_ai.response.model'] = response.model;
+                    }
+
+                    span.end(0, endMeta);
+                    return response;
+                  },
+                  (error: any) => {
+                    span.end(error?.status || 500, {
+                      'error.message': error?.message,
+                      'error.type': error?.name || 'OpenAIError',
+                    });
+                    throw error;
+                  }
+                );
+              }
+
+              span.end(0);
+              return result;
+            } catch (error: any) {
+              span.end(500, { 'error.message': error?.message });
+              throw error;
+            }
+          });
+        }
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentOpenAI = (options?: SenzorOptions) => {
+  hookRequire('openai', (exports: any) => {
+    patchOpenAIClient(exports, options);
+  });
+};

package/src/instrumentation/pino.ts

@@ -0,0 +1,170 @@
+import { Context } from '../core/context';
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+
+// ---------------------------------------------------------------------------
+// Pino Log Correlation
+//
+// Injects traceId and spanId from the active Senzor context into every
+// pino log record. This enables log-to-trace correlation in the dashboard.
+//
+// Strategy: Wrap the pino factory to inject a mixin function that reads
+// from AsyncLocalStorage on every log call. If the user provides their
+// own mixin, both are composed together.
+//
+// Also patches existing logger prototypes to ensure loggers created before
+// instrumentation are also covered.
+//
+// Injected fields:
+//   - traceId: string (APM trace ID or Task run ID)
+//   - spanId: string (active span ID)
+//   - senzor.context: 'apm' | 'task'
+// ---------------------------------------------------------------------------
+
+/** Get trace correlation fields from the current async context. */
+const getTraceFields = (): Record<string, string> | null => {
+  const trace = Context.current();
+  if (!trace) return null;
+
+  const fields: Record<string, string> = {
+    traceId: trace.id,
+  };
+
+  if (trace.activeSpanId) {
+    fields.spanId = trace.activeSpanId;
+  }
+
+  fields['senzor.context'] = trace.contextType;
+
+  return fields;
+};
+
+/** Create a mixin function that injects trace context. */
+const createTraceMixin = (userMixin?: Function): Function => {
+  return (mergeObject: any, level: number) => {
+    const traceFields = getTraceFields();
+    const userFields = typeof userMixin === 'function'
+      ? userMixin(mergeObject, level)
+      : {};
+
+    return {
+      ...userFields,
+      ...(traceFields || {}),
+    };
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Factory wrapping
+// ---------------------------------------------------------------------------
+
+const patchPinoFactory = (pinoModule: any, _options?: SenzorOptions) => {
+  // pino is exported as a function (the factory) with properties on it
+  // We need to wrap the function itself, which is tricky since it's the module export
+
+  // Strategy: Patch the internal prototype's write method for already-created loggers
+  // AND wrap the factory for new loggers
+
+  // 1. Wrap the factory
+  const originalPino = pinoModule;
+
+  if (typeof pinoModule !== 'function') return;
+
+  // We can't replace the module export directly from hookRequire,
+  // but we can patch the prototype for existing loggers
+
+  // 2. Patch the internal prototype
+  // Create a temp logger to get the prototype
+  try {
+    const devNull = { write: () => {} };
+    const tempLogger = pinoModule({ level: 'silent' }, devNull);
+    const proto = Object.getPrototypeOf(tempLogger);
+
+    if (proto && !proto.__senzorPatched) {
+      // Find the write symbol or method
+      const writeSymbol = Object.getOwnPropertySymbols(proto).find(
+        (sym) => sym.toString().includes('write') || sym.toString().includes('pino.write')
+      );
+
+      if (writeSymbol) {
+        const originalWrite = proto[writeSymbol];
+        if (typeof originalWrite === 'function') {
+          proto[writeSymbol] = function patchedWrite(this: any, obj: any, msg: any, num: any) {
+            const traceFields = getTraceFields();
+            if (traceFields && obj && typeof obj === 'object') {
+              Object.assign(obj, traceFields);
+            }
+            return originalWrite.call(this, obj, msg, num);
+          };
+        }
+      }
+
+      // Also try patching the level methods directly as fallback
+      const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+      for (const level of levels) {
+        if (typeof proto[level] === 'function') {
+          patchMethod(
+            proto,
+            level,
+            `senzor.pino.${level}`,
+            (original) =>
+              function patchedLevel(this: any, ...args: any[]) {
+                const traceFields = getTraceFields();
+                if (!traceFields) return original.apply(this, args);
+
+                // pino level methods accept:
+                //   .info(obj, msg, ...args)
+                //   .info(msg, ...args)
+                //   .info(err, msg, ...args)
+                if (args.length > 0 && typeof args[0] === 'object' && args[0] !== null && !(args[0] instanceof Error)) {
+                  // First arg is a merge object — inject trace fields
+                  args[0] = { ...args[0], ...traceFields };
+                } else if (args.length > 0 && typeof args[0] === 'string') {
+                  // First arg is message string — prepend a merge object
+                  args.unshift(traceFields);
+                } else if (args.length > 0 && args[0] instanceof Error) {
+                  // First arg is an error — add trace fields alongside
+                  const err = args[0];
+                  args[0] = { ...traceFields, err };
+                  if (typeof args[1] !== 'string') {
+                    args.splice(1, 0, err.message);
+                  }
+                }
+
+                return original.apply(this, args);
+              }
+          );
+        }
+      }
+
+      // Patch child() to ensure child loggers also get correlation
+      if (typeof proto.child === 'function') {
+        patchMethod(
+          proto,
+          'child',
+          'senzor.pino.child',
+          (original) =>
+            function patchedChild(this: any, bindings: any, ...args: any[]) {
+              // Child loggers inherit the patched prototype automatically
+              return original.call(this, bindings, ...args);
+            }
+        );
+      }
+
+      proto.__senzorPatched = true;
+    }
+  } catch {
+    // Pino may not be fully loaded yet — the hookRequire retry will catch it
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentPino = (_options?: SenzorOptions) => {
+  hookRequire('pino', (exports: any) => {
+    patchPinoFactory(exports, _options);
+  });
+};

package/src/instrumentation/restify.ts

@@ -0,0 +1,213 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Restify Instrumentation
+//
+// Instruments the `restify` HTTP framework at the server layer:
+//   - Server route registration methods (get, post, put, del, patch, head, opts)
+//     to wrap route handlers and generate spans per request.
+//   - Server.prototype.use() to optionally capture middleware spans.
+//
+// Restify handler signature: (req, res, next) — same as Express/Connect.
+// Route path is available at registration time via the route config.
+//
+// Captured attributes:
+//   - http.route: registered route path
+//   - http.method: HTTP method
+//   - restify.type: 'route_handler' | 'middleware'
+//   - restify.version: route version (if versioned routes)
+//   - framework: 'restify'
+// ---------------------------------------------------------------------------
+
+const HTTP_METHODS = ['get', 'post', 'put', 'del', 'patch', 'head', 'opts'] as const;
+
+/** Normalize restify method name to HTTP method. */
+const METHOD_MAP: Record<string, string> = {
+  get: 'GET', post: 'POST', put: 'PUT', del: 'DELETE',
+  patch: 'PATCH', head: 'HEAD', opts: 'OPTIONS',
+};
+
+// ---------------------------------------------------------------------------
+// Handler wrapping
+// ---------------------------------------------------------------------------
+
+const wrapHandler = (
+  handler: Function,
+  method: string,
+  path: string,
+  type: 'route_handler' | 'middleware',
+  options?: SenzorOptions
+): Function => {
+  if (typeof handler !== 'function') return handler;
+  if ((handler as any).__senzorWrapped) return handler;
+
+  const wrapped = function wrappedRestifyHandler(this: any, req: any, res: any, next: any) {
+    const httpMethod = METHOD_MAP[method] || method.toUpperCase();
+    const routePath = path || req?.route?.path || req?.getPath?.() || req?.url?.split('?')[0] || '/';
+
+    const spanName = type === 'middleware'
+      ? `Restify middleware ${handler.name || 'anonymous'}`
+      : `Restify ${httpMethod} ${routePath}`;
+
+    const span = startCapturedSpan(
+      spanName,
+      'function',
+      {
+        'restify.type': type,
+        'http.route': routePath,
+        'http.method': httpMethod,
+        framework: 'restify',
+      },
+      options
+    );
+
+    if (!span) return handler.call(this, req, res, next);
+
+    return runWithCapturedSpan(span, () => {
+      // Wrap next() to end span when handler passes control
+      const wrappedNext = function (...args: any[]) {
+        const hasError = args.length > 0 && args[0] instanceof Error;
+        if (hasError) {
+          const err = args[0];
+          span.end(err?.statusCode || 500, {
+            'error.message': err.message,
+            'error.type': err.name || 'Error',
+          });
+        } else {
+          span.end(0);
+        }
+        return next?.(...args);
+      };
+
+      try {
+        const result = handler.call(this, req, res, wrappedNext);
+
+        // Handle async handlers returning promises
+        if (result && typeof result.then === 'function') {
+          return result.then(
+            (val: any) => val,
+            (error: any) => {
+              span.end(error?.statusCode || 500, {
+                'error.message': error?.message,
+                'error.type': error?.name || 'Error',
+              });
+              throw error;
+            }
+          );
+        }
+
+        return result;
+      } catch (error: any) {
+        span.end(error?.statusCode || 500, {
+          'error.message': error?.message,
+          'error.type': error?.name || 'Error',
+        });
+        throw error;
+      }
+    });
+  };
+
+  (wrapped as any).__senzorWrapped = true;
+  return wrapped;
+};
+
+// ---------------------------------------------------------------------------
+// Server route method patching
+// ---------------------------------------------------------------------------
+
+const patchRestifyServer = (restify: any, options?: SenzorOptions) => {
+  // restify.createServer() returns a Server instance
+  // We need to patch Server.prototype
+
+  let ServerProto: any;
+
+  // Try to get Server prototype from a temp server
+  try {
+    const tempServer = restify.createServer({ name: '__senzor_probe' });
+    ServerProto = Object.getPrototypeOf(tempServer);
+    // Close the temp server immediately
+    try { tempServer.close(); } catch { }
+  } catch { }
+
+  // Fallback: try restify.Server
+  if (!ServerProto) {
+    ServerProto = restify?.Server?.prototype;
+  }
+
+  if (!ServerProto) return;
+
+  // Patch route registration methods
+  for (const method of HTTP_METHODS) {
+    if (typeof ServerProto[method] !== 'function') continue;
+
+    patchMethod(
+      ServerProto,
+      method,
+      `senzor.restify.server.${method}`,
+      (original) =>
+        function patchedRouteMethod(this: any, ...args: any[]) {
+          // Restify route methods accept:
+          //   server.get(path, handler1, handler2, ...)
+          //   server.get({ path, version }, handler1, handler2, ...)
+          //   server.get(path, [handler1, handler2])
+
+          let path = '/';
+
+          // Extract path from first argument
+          if (typeof args[0] === 'string') {
+            path = args[0];
+          } else if (args[0] && typeof args[0] === 'object') {
+            path = args[0].path || args[0].url || '/';
+          }
+
+          // Wrap all handler arguments
+          for (let i = 0; i < args.length; i++) {
+            if (typeof args[i] === 'function') {
+              args[i] = wrapHandler(args[i], method, path, 'route_handler', options);
+            } else if (Array.isArray(args[i])) {
+              args[i] = args[i].map((h: any) =>
+                typeof h === 'function' ? wrapHandler(h, method, path, 'route_handler', options) : h
+              );
+            }
+          }
+
+          return original.apply(this, args);
+        }
+    );
+  }
+
+  // Patch use() for middleware spans (optional)
+  if (options?.captureMiddlewareSpans !== false && typeof ServerProto.use === 'function') {
+    patchMethod(
+      ServerProto,
+      'use',
+      'senzor.restify.server.use',
+      (original) =>
+        function patchedUse(this: any, ...args: any[]) {
+          for (let i = 0; i < args.length; i++) {
+            if (typeof args[i] === 'function') {
+              args[i] = wrapHandler(args[i], 'use', '*', 'middleware', options);
+            } else if (Array.isArray(args[i])) {
+              args[i] = args[i].map((h: any) =>
+                typeof h === 'function' ? wrapHandler(h, 'use', '*', 'middleware', options) : h
+              );
+            }
+          }
+          return original.apply(this, args);
+        }
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentRestify = (options?: SenzorOptions) => {
+  hookRequire('restify', (exports: any) => {
+    patchRestifyServer(exports, options);
+  });
+};