@senzops/apm-node 1.2.8 → 1.3.0

package/src/instrumentation/tedious.ts

@@ -0,0 +1,509 @@
+import { getSqlOperation, normalizeSql } from '../core/sanitizer';
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Tedious (SQL Server / MSSQL) Instrumentation
+//
+// Instruments the `tedious` package — the primary pure-JS driver for
+// Microsoft SQL Server used by node-mssql, Knex (mssql dialect),
+// TypeORM, Sequelize, and Prisma (sqlserver provider).
+//
+// Patches Connection.prototype methods:
+//   - execSql()       — standard parameterized queries
+//   - execSqlBatch()  — raw SQL batch execution
+//   - execBulkLoad()  — bulk insert operations
+//   - callProcedure() — stored procedure calls
+//   - prepare()       — prepared statement creation
+//   - execute()       — prepared statement execution
+//
+// Also instruments `mssql` (node-mssql) — the popular high-level wrapper
+// around tedious — by patching Request.prototype.query/execute/batch.
+//
+// Captured attributes (OTel semantic conventions):
+//   - db.system.name: 'mssql'
+//   - db.operation.name: operation type
+//   - db.query.text: normalized SQL
+//   - db.namespace: database name
+//   - server.address: SQL Server hostname
+//   - server.port: SQL Server port
+// ---------------------------------------------------------------------------
+
+/** Extract connection metadata from a tedious Connection instance. */
+const getConnectionMeta = (connection: any): Record<string, any> => {
+  const config = connection?.config;
+  if (!config) return {};
+
+  const meta: Record<string, any> = {
+    'db.system.name': 'mssql',
+  };
+
+  if (config.server) meta['server.address'] = config.server;
+  if (config.options?.port) meta['server.port'] = config.options.port;
+  if (config.options?.database) meta['db.namespace'] = config.options.database;
+
+  return meta;
+};
+
+// ---------------------------------------------------------------------------
+// Connection method patching
+// ---------------------------------------------------------------------------
+
+const patchTediousConnection = (tedious: any, options?: SenzorOptions) => {
+  const Connection = tedious?.Connection;
+  if (!Connection?.prototype) return;
+
+  const proto = Connection.prototype;
+
+  // --- execSql(request) ---
+  patchMethod(
+    proto,
+    'execSql',
+    'senzor.tedious.connection.execSql',
+    (original) =>
+      function patchedExecSql(this: any, request: any) {
+        const sql = request?.sqlTextOrProcedure;
+        const operation = getSqlOperation(sql) || 'QUERY';
+        const connMeta = getConnectionMeta(this);
+
+        const span = startCapturedSpan(
+          `MSSQL ${operation}`,
+          'db',
+          {
+            ...connMeta,
+            'db.operation.name': operation,
+            'db.query.text': normalizeSql(sql, options),
+            'tedious.method': 'execSql',
+            library: 'tedious',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, request);
+
+        return runWithCapturedSpan(span, () => {
+          wrapTediousRequest(request, span);
+          return original.call(this, request);
+        });
+      }
+  );
+
+  // --- execSqlBatch(request) ---
+  patchMethod(
+    proto,
+    'execSqlBatch',
+    'senzor.tedious.connection.execSqlBatch',
+    (original) =>
+      function patchedExecSqlBatch(this: any, request: any) {
+        const sql = request?.sqlTextOrProcedure;
+        const operation = getSqlOperation(sql) || 'BATCH';
+        const connMeta = getConnectionMeta(this);
+
+        const span = startCapturedSpan(
+          `MSSQL BATCH ${operation}`,
+          'db',
+          {
+            ...connMeta,
+            'db.operation.name': `BATCH_${operation}`,
+            'db.query.text': normalizeSql(sql, options),
+            'tedious.method': 'execSqlBatch',
+            library: 'tedious',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, request);
+
+        return runWithCapturedSpan(span, () => {
+          wrapTediousRequest(request, span);
+          return original.call(this, request);
+        });
+      }
+  );
+
+  // --- callProcedure(request) ---
+  patchMethod(
+    proto,
+    'callProcedure',
+    'senzor.tedious.connection.callProcedure',
+    (original) =>
+      function patchedCallProcedure(this: any, request: any) {
+        const procName = request?.sqlTextOrProcedure || 'unknown';
+        const connMeta = getConnectionMeta(this);
+
+        const span = startCapturedSpan(
+          `MSSQL CALL ${procName}`,
+          'db',
+          {
+            ...connMeta,
+            'db.operation.name': 'CALL',
+            'db.query.text': procName,
+            'db.collection.name': procName,
+            'tedious.method': 'callProcedure',
+            library: 'tedious',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, request);
+
+        return runWithCapturedSpan(span, () => {
+          wrapTediousRequest(request, span);
+          return original.call(this, request);
+        });
+      }
+  );
+
+  // --- execBulkLoad(bulkLoad, rows, callback) ---
+  patchMethod(
+    proto,
+    'execBulkLoad',
+    'senzor.tedious.connection.execBulkLoad',
+    (original) =>
+      function patchedExecBulkLoad(this: any, bulkLoad: any, ...args: any[]) {
+        const tableName = bulkLoad?.table || 'unknown';
+        const connMeta = getConnectionMeta(this);
+
+        const span = startCapturedSpan(
+          `MSSQL BULK INSERT ${tableName}`,
+          'db',
+          {
+            ...connMeta,
+            'db.operation.name': 'BULK_INSERT',
+            'db.collection.name': tableName,
+            'tedious.method': 'execBulkLoad',
+            library: 'tedious',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, bulkLoad, ...args);
+
+        return runWithCapturedSpan(span, () => {
+          // Wrap the bulkLoad callback
+          if (bulkLoad && typeof bulkLoad.callback === 'function') {
+            const originalCallback = bulkLoad.callback;
+            bulkLoad.callback = function (err: any, rowCount: any) {
+              if (err) {
+                span.end(500, {
+                  'error.message': err.message,
+                  'error.type': err.name || 'Error',
+                });
+              } else {
+                span.end(0, { 'db.response.row_count': rowCount });
+              }
+              return originalCallback.call(this, err, rowCount);
+            };
+          } else {
+            // If no callback on bulkLoad, try wrapping the last arg
+            const lastIdx = args.length - 1;
+            if (lastIdx >= 0 && typeof args[lastIdx] === 'function') {
+              const cb = args[lastIdx];
+              args[lastIdx] = function (err: any, rowCount: any) {
+                if (err) {
+                  span.end(500, { 'error.message': err.message });
+                } else {
+                  span.end(0, { 'db.response.row_count': rowCount });
+                }
+                return cb.apply(this, arguments);
+              };
+            } else {
+              span.end(0);
+            }
+          }
+
+          return original.call(this, bulkLoad, ...args);
+        });
+      }
+  );
+
+  // --- prepare(request) ---
+  if (typeof proto.prepare === 'function') {
+    patchMethod(
+      proto,
+      'prepare',
+      'senzor.tedious.connection.prepare',
+      (original) =>
+        function patchedPrepare(this: any, request: any) {
+          const sql = request?.sqlTextOrProcedure;
+          const connMeta = getConnectionMeta(this);
+
+          const span = startCapturedSpan(
+            `MSSQL PREPARE`,
+            'db',
+            {
+              ...connMeta,
+              'db.operation.name': 'PREPARE',
+              'db.query.text': normalizeSql(sql, options),
+              'tedious.method': 'prepare',
+              library: 'tedious',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, request);
+
+          return runWithCapturedSpan(span, () => {
+            wrapTediousRequest(request, span);
+            return original.call(this, request);
+          });
+        }
+    );
+  }
+
+  // --- execute(request, parameters) ---
+  if (typeof proto.execute === 'function') {
+    patchMethod(
+      proto,
+      'execute',
+      'senzor.tedious.connection.execute',
+      (original) =>
+        function patchedExecute(this: any, request: any, parameters: any) {
+          const sql = request?.sqlTextOrProcedure;
+          const operation = getSqlOperation(sql) || 'EXECUTE';
+          const connMeta = getConnectionMeta(this);
+
+          const span = startCapturedSpan(
+            `MSSQL EXECUTE ${operation}`,
+            'db',
+            {
+              ...connMeta,
+              'db.operation.name': `EXECUTE_${operation}`,
+              'db.query.text': normalizeSql(sql, options),
+              'tedious.method': 'execute',
+              library: 'tedious',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, request, parameters);
+
+          return runWithCapturedSpan(span, () => {
+            wrapTediousRequest(request, span);
+            return original.call(this, request, parameters);
+          });
+        }
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Tedious Request callback wrapping
+// ---------------------------------------------------------------------------
+
+/** Wrap a tedious Request's completion callback to end the span. */
+const wrapTediousRequest = (request: any, span: any) => {
+  if (!request || !span) return;
+
+  // Tedious Request uses an event-based completion model
+  // The 'requestCompleted' callback is the final callback passed to the Request constructor
+  if (typeof request.callback === 'function') {
+    const originalCallback = request.callback;
+    request.callback = function (err: any, rowCount: any, rows: any) {
+      if (err) {
+        span.end(500, {
+          'error.message': err.message,
+          'error.type': err.name || 'RequestError',
+          'db.error.code': err.code,
+        });
+      } else {
+        span.end(0, {
+          'db.response.row_count': rowCount,
+        });
+      }
+      return originalCallback.call(this, err, rowCount, rows);
+    };
+    return;
+  }
+
+  // Fallback: listen for events
+  if (typeof request.on === 'function') {
+    let ended = false;
+    request.on('requestCompleted', () => {
+      if (!ended) { ended = true; span.end(0); }
+    });
+    request.on('error', (err: any) => {
+      if (!ended) {
+        ended = true;
+        span.end(500, { 'error.message': err?.message });
+      }
+    });
+  }
+};
+
+// ---------------------------------------------------------------------------
+// node-mssql (mssql) wrapper patching
+// ---------------------------------------------------------------------------
+
+const patchMssql = (mssql: any, options?: SenzorOptions) => {
+  // mssql exports Request, ConnectionPool, etc.
+  const RequestClass = mssql?.Request;
+  if (!RequestClass?.prototype) return;
+
+  const proto = RequestClass.prototype;
+
+  // Patch Request.prototype.query(sql)
+  patchMethod(
+    proto,
+    'query',
+    'senzor.mssql.request.query',
+    (original) =>
+      function patchedMssqlQuery(this: any, sql: string) {
+        const operation = getSqlOperation(sql) || 'QUERY';
+
+        const span = startCapturedSpan(
+          `MSSQL ${operation}`,
+          'db',
+          {
+            'db.system.name': 'mssql',
+            'db.operation.name': operation,
+            'db.query.text': normalizeSql(sql, options),
+            library: 'mssql',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, sql);
+
+        return runWithCapturedSpan(span, () => {
+          try {
+            const result = original.call(this, sql);
+
+            if (result && typeof result.then === 'function') {
+              return result.then(
+                (value: any) => {
+                  span.end(0, {
+                    'db.response.row_count': value?.recordset?.length ?? value?.rowsAffected?.[0],
+                  });
+                  return value;
+                },
+                (error: any) => {
+                  span.end(500, {
+                    'error.message': error?.message,
+                    'error.type': error?.name || 'Error',
+                    'db.error.code': error?.code,
+                  });
+                  throw error;
+                }
+              );
+            }
+
+            span.end(0);
+            return result;
+          } catch (error: any) {
+            span.end(500, { 'error.message': error?.message });
+            throw error;
+          }
+        });
+      }
+  );
+
+  // Patch Request.prototype.execute(procedure)
+  patchMethod(
+    proto,
+    'execute',
+    'senzor.mssql.request.execute',
+    (original) =>
+      function patchedMssqlExecute(this: any, procedure: string) {
+        const span = startCapturedSpan(
+          `MSSQL CALL ${procedure}`,
+          'db',
+          {
+            'db.system.name': 'mssql',
+            'db.operation.name': 'CALL',
+            'db.query.text': procedure,
+            'db.collection.name': procedure,
+            library: 'mssql',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, procedure);
+
+        return runWithCapturedSpan(span, () => {
+          try {
+            const result = original.call(this, procedure);
+
+            if (result && typeof result.then === 'function') {
+              return result.then(
+                (value: any) => { span.end(0); return value; },
+                (error: any) => {
+                  span.end(500, { 'error.message': error?.message });
+                  throw error;
+                }
+              );
+            }
+
+            span.end(0);
+            return result;
+          } catch (error: any) {
+            span.end(500, { 'error.message': error?.message });
+            throw error;
+          }
+        });
+      }
+  );
+
+  // Patch Request.prototype.batch(sql)
+  if (typeof proto.batch === 'function') {
+    patchMethod(
+      proto,
+      'batch',
+      'senzor.mssql.request.batch',
+      (original) =>
+        function patchedMssqlBatch(this: any, sql: string) {
+          const operation = getSqlOperation(sql) || 'BATCH';
+
+          const span = startCapturedSpan(
+            `MSSQL BATCH ${operation}`,
+            'db',
+            {
+              'db.system.name': 'mssql',
+              'db.operation.name': `BATCH_${operation}`,
+              'db.query.text': normalizeSql(sql, options),
+              library: 'mssql',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, sql);
+
+          return runWithCapturedSpan(span, () => {
+            try {
+              const result = original.call(this, sql);
+              if (result && typeof result.then === 'function') {
+                return result.then(
+                  (value: any) => { span.end(0); return value; },
+                  (error: any) => {
+                    span.end(500, { 'error.message': error?.message });
+                    throw error;
+                  }
+                );
+              }
+              span.end(0);
+              return result;
+            } catch (error: any) {
+              span.end(500, { 'error.message': error?.message });
+              throw error;
+            }
+          });
+        }
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentTedious = (options?: SenzorOptions) => {
+  hookRequire('tedious', (exports: any) => {
+    patchTediousConnection(exports, options);
+  });
+
+  hookRequire('mssql', (exports: any) => {
+    patchMssql(exports, options);
+  });
+};

package/src/instrumentation/winston.ts

@@ -0,0 +1,149 @@
+import { Context } from '../core/context';
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+
+// ---------------------------------------------------------------------------
+// Winston Log Correlation
+//
+// Injects traceId and spanId from the active Senzor context into every
+// winston log entry. Enables log-to-trace correlation in the dashboard.
+//
+// Strategy: Patch Logger.prototype.write() to inject trace fields into
+// the info object before it flows to transports. This covers all log
+// methods (info, error, warn, debug, etc.) since they all call write().
+//
+// Injected fields:
+//   - traceId: string
+//   - spanId: string
+//   - 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;
+};
+
+// ---------------------------------------------------------------------------
+// Logger.prototype.write patching
+// ---------------------------------------------------------------------------
+
+const patchWinstonLogger = (winston: any, _options?: SenzorOptions) => {
+  // winston exports createLogger, Logger, etc.
+  // Logger is at winston.Logger or winston.transports (for older versions)
+
+  // Try to get Logger from several locations
+  let LoggerClass = winston?.Logger;
+
+  // In winston 3.x, Logger is also accessible via the createLogger factory
+  if (!LoggerClass) {
+    try {
+      const loggerModule = require('winston/lib/winston/logger');
+      LoggerClass = loggerModule?.Logger || loggerModule;
+    } catch { }
+  }
+
+  if (!LoggerClass?.prototype) return;
+
+  // Patch write() — the core method all log calls funnel through
+  patchMethod(
+    LoggerClass.prototype,
+    'write',
+    'senzor.winston.logger.write',
+    (original) =>
+      function patchedWrite(this: any, info: any) {
+        if (info && typeof info === 'object') {
+          const traceFields = getTraceFields();
+          if (traceFields) {
+            // Inject trace fields into the info object
+            // Use non-enumerable setter to avoid conflicts with symbols
+            info.traceId = traceFields.traceId;
+            if (traceFields.spanId) info.spanId = traceFields.spanId;
+            info['senzor.context'] = traceFields['senzor.context'];
+          }
+        }
+        return original.call(this, info);
+      }
+  );
+
+  // Also patch log() as a safety net for custom transports that call log directly
+  patchMethod(
+    LoggerClass.prototype,
+    'log',
+    'senzor.winston.logger.log',
+    (original) =>
+      function patchedLog(this: any, ...args: any[]) {
+        // log() normalizes args into an info object, then calls write()
+        // Since write() is already patched, we just need to ensure the
+        // info object exists for direct log() calls with string args
+        //
+        // log(level, message) or log({ level, message }) or log(info)
+        const traceFields = getTraceFields();
+
+        if (traceFields && args.length > 0) {
+          // If first arg is an info-like object, inject directly
+          if (typeof args[0] === 'object' && args[0] !== null && !(args[0] instanceof Error)) {
+            args[0] = { ...args[0], ...traceFields };
+          }
+          // For other signatures, write() patch handles it
+        }
+
+        return original.apply(this, args);
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// createLogger wrapping
+// ---------------------------------------------------------------------------
+
+const patchCreateLogger = (winston: any, _options?: SenzorOptions) => {
+  if (typeof winston?.createLogger !== 'function') return;
+
+  patchMethod(
+    winston,
+    'createLogger',
+    'senzor.winston.createLogger',
+    (original) =>
+      function patchedCreateLogger(this: any, opts: any) {
+        const logger = original.call(this, opts);
+
+        // Ensure the logger instance has patched write/log
+        // (in case the prototype wasn't patched yet)
+        if (logger && !logger.__senzorPatched) {
+          const proto = Object.getPrototypeOf(logger);
+          if (proto && !proto.__senzorPatched) {
+            patchWinstonLogger({ Logger: { prototype: proto } }, _options);
+            proto.__senzorPatched = true;
+          }
+          logger.__senzorPatched = true;
+        }
+
+        return logger;
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentWinston = (options?: SenzorOptions) => {
+  hookRequire('winston', (exports: any) => {
+    patchWinstonLogger(exports, options);
+    patchCreateLogger(exports, options);
+  });
+};

package/src/register.ts

@@ -19,13 +19,27 @@ const endpoint =
   getEnv('SENZOR_ENDPOINT') ||
   getEnv('SENZOR_APM_ENDPOINT');
 
+// ---------------------------------------------------------------------------
+// Lambda environment auto-detection
+//
+// When running inside AWS Lambda, the execution model differs fundamentally
+// from long-running servers:
+//   - Runtime metrics (event loop, GC, heap) are meaningless per-invocation
+//   - Interval-based flushing wastes resources between frozen invocations
+//   - Batch size should be small since each invocation is short-lived
+//
+// We detect Lambda via the AWS_LAMBDA_FUNCTION_NAME env var (always set by
+// the Lambda runtime) and auto-configure optimal defaults.
+// ---------------------------------------------------------------------------
+const isLambda = !!getEnv('AWS_LAMBDA_FUNCTION_NAME');
+
 const options = {
   apiKey: apiKey || '',
   endpoint,
   debug: truthy(getEnv('SENZOR_DEBUG')),
   autoLogs: getEnv('SENZOR_AUTO_LOGS') === 'false' ? false : undefined,
-  batchSize: numberFromEnv(getEnv('SENZOR_BATCH_SIZE')),
-  flushInterval: numberFromEnv(getEnv('SENZOR_FLUSH_INTERVAL')),
+  batchSize: numberFromEnv(getEnv('SENZOR_BATCH_SIZE')) ?? (isLambda ? 10 : undefined),
+  flushInterval: numberFromEnv(getEnv('SENZOR_FLUSH_INTERVAL')) ?? (isLambda ? 0 : undefined),
   flushTimeoutMs: numberFromEnv(getEnv('SENZOR_FLUSH_TIMEOUT_MS')),
   maxQueueSize: numberFromEnv(getEnv('SENZOR_MAX_QUEUE_SIZE')),
   maxSpansPerTrace: numberFromEnv(getEnv('SENZOR_MAX_SPANS_PER_TRACE')),
@@ -49,7 +63,12 @@ const options = {
   captureLifecycleHookSpans:
     getEnv('SENZOR_CAPTURE_LIFECYCLE_HOOK_SPANS') === 'false'
       ? false
-      : undefined
+      : undefined,
+  runtimeMetrics:
+    getEnv('SENZOR_RUNTIME_METRICS') === 'false' || isLambda
+      ? false
+      : undefined,
+  runtimeMetricsInterval: numberFromEnv(getEnv('SENZOR_RUNTIME_METRICS_INTERVAL')),
 };
 
 if (apiKey) {