@senzops/apm-node 1.2.7 → 1.3.0

package/src/instrumentation/knex.ts

@@ -0,0 +1,249 @@
+import { getSqlOperation, normalizeSql } from '../core/sanitizer';
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Knex.js Instrumentation
+//
+// Instruments the Knex query builder at two layers:
+//   1. Client.prototype.query() — the final execution point for all queries.
+//      Every .select(), .insert(), .where().update(), raw(), etc. funnels
+//      through this method before hitting the underlying driver (pg, mysql,
+//      sqlite3, mssql, oracledb).
+//
+//   2. Client.prototype._stream() — covers streaming queries.
+//
+// Captured span attributes (OTel semantic conventions):
+//   - db.system.name: derived from client dialect (pg, mysql, sqlite3, etc.)
+//   - db.operation.name: SELECT, INSERT, UPDATE, DELETE, etc.
+//   - db.query.text: parameterized/normalized SQL
+//   - db.collection.name: table name if detectable
+//   - knex.method: Knex builder method (select, insert, update, del, raw)
+// ---------------------------------------------------------------------------
+
+/** Map knex dialect names to OTel db.system.name values. */
+const DIALECT_MAP: Record<string, string> = {
+  pg: 'postgresql',
+  'pg-native': 'postgresql',
+  mysql: 'mysql',
+  mysql2: 'mysql',
+  sqlite3: 'sqlite',
+  'better-sqlite3': 'sqlite',
+  mssql: 'mssql',
+  oracledb: 'oracle',
+  oracle: 'oracle',
+  redshift: 'redshift',
+  cockroachdb: 'cockroachdb',
+};
+
+/** Extract the database system from a Knex client instance. */
+const getDbSystem = (client: any): string => {
+  const dialect = client?.config?.client
+    || client?.dialect
+    || client?.driverName
+    || 'unknown';
+
+  const normalized = typeof dialect === 'string' ? dialect.toLowerCase() : 'unknown';
+  return DIALECT_MAP[normalized] || normalized;
+};
+
+/** Extract table name from SQL statement. */
+const extractTableName = (sql: string | undefined): string | undefined => {
+  if (!sql) return undefined;
+  // Match FROM table, INTO table, UPDATE table, JOIN table
+  const match = sql.match(
+    /(?:FROM|INTO|UPDATE|JOIN)\s+[`"[\]]?(\w+)[`"\]]?/i
+  );
+  return match?.[1] || undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Client.prototype.query patching
+// ---------------------------------------------------------------------------
+
+const patchKnexClient = (knexModule: any, options?: SenzorOptions) => {
+  // Knex exports a factory function. The Client base class is at:
+  //   knex.Client (in some versions)
+  //   require('knex/lib/client') (internal)
+  // We also intercept the factory to patch client instances.
+
+  let ClientClass: any;
+
+  // Try to get Client from the module
+  ClientClass = knexModule?.Client;
+
+  // Try the internal path
+  if (!ClientClass) {
+    try {
+      ClientClass = require('knex/lib/client');
+    } catch { }
+  }
+
+  if (!ClientClass?.prototype) return;
+
+  // Patch query() — the core execution method
+  patchMethod(
+    ClientClass.prototype,
+    'query',
+    'senzor.knex.client.query',
+    (original) =>
+      function patchedQuery(this: any, connection: any, queryObj: any) {
+        // queryObj contains { sql, bindings, method, options, ... }
+        const sql = queryObj?.sql;
+        const method = queryObj?.method || 'raw';
+        const operation = getSqlOperation(sql) || method.toUpperCase();
+        const dbSystem = getDbSystem(this);
+        const tableName = extractTableName(sql);
+
+        const span = startCapturedSpan(
+          `Knex ${operation}`,
+          'db',
+          {
+            'db.system.name': dbSystem,
+            'db.operation.name': operation,
+            'db.query.text': normalizeSql(sql, options),
+            'db.collection.name': tableName,
+            'knex.method': method,
+            library: 'knex',
+          },
+          options
+        );
+
+        if (!span) return original.call(this, connection, queryObj);
+
+        return runWithCapturedSpan(span, () => {
+          try {
+            const result = original.call(this, connection, queryObj);
+
+            if (result && typeof result.then === 'function') {
+              return result.then(
+                (value: any) => {
+                  const rowCount = Array.isArray(value)
+                    ? value.length
+                    : value?.rowCount ?? value?.affectedRows;
+
+                  span.end(0, {
+                    'db.response.row_count': rowCount,
+                  });
+                  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,
+              'error.type': error?.name || 'Error',
+              'db.error.code': error?.code,
+            });
+            throw error;
+          }
+        });
+      }
+  );
+
+  // Patch _stream() — for streaming queries
+  if (typeof ClientClass.prototype._stream === 'function') {
+    patchMethod(
+      ClientClass.prototype,
+      '_stream',
+      'senzor.knex.client._stream',
+      (original) =>
+        function patchedStream(this: any, connection: any, queryObj: any, stream: any, streamOptions: any) {
+          const sql = queryObj?.sql;
+          const operation = getSqlOperation(sql) || 'STREAM';
+          const dbSystem = getDbSystem(this);
+
+          const span = startCapturedSpan(
+            `Knex STREAM ${operation}`,
+            'db',
+            {
+              'db.system.name': dbSystem,
+              'db.operation.name': `STREAM_${operation}`,
+              'db.query.text': normalizeSql(sql, options),
+              'knex.method': 'stream',
+              library: 'knex',
+            },
+            options
+          );
+
+          if (!span) return original.call(this, connection, queryObj, stream, streamOptions);
+
+          return runWithCapturedSpan(span, () => {
+            try {
+              const result = original.call(this, connection, queryObj, stream, streamOptions);
+
+              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;
+            }
+          });
+        }
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Factory wrapping — ensure clients created via knex() get patched
+// ---------------------------------------------------------------------------
+
+const patchKnexFactory = (knexModule: any, options?: SenzorOptions) => {
+  if (typeof knexModule !== 'function') return;
+
+  // Knex's default export is the factory function
+  // We can't replace the module export, but Client.prototype is shared
+  // across all instances, so patching the prototype is sufficient.
+
+  // Also try to patch via the factory's client property
+  if (knexModule.Client?.prototype) {
+    patchKnexClient(knexModule, options);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentKnex = (options?: SenzorOptions) => {
+  hookRequire('knex', (exports: any) => {
+    patchKnexFactory(exports, options);
+    patchKnexClient(exports, options);
+
+    // Handle default exports
+    if (exports?.default) {
+      patchKnexFactory(exports.default, options);
+      patchKnexClient(exports.default, options);
+    }
+  });
+
+  // Also try the internal client module directly
+  hookRequire('knex/lib/client', (exports: any) => {
+    if (exports?.prototype) {
+      patchKnexClient({ Client: exports }, options);
+    }
+  });
+};

package/src/instrumentation/lru-memoizer.ts

@@ -0,0 +1,175 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// LRU-Memoizer Instrumentation
+//
+// Instruments the `lru-memoizer` package — a popular caching/memoization
+// library used by Auth0's node-auth0 SDK, passport strategies, and other
+// authentication/authorization flows for caching tokens, JWKS keys, etc.
+//
+// Strategy: Wrap the lru-memoizer factory functions to intercept the
+// returned memoized function. Each call to the memoized function gets
+// a span showing cache hit/miss and execution time.
+//
+// lru-memoizer exports:
+//   - lruMemoizer(options)      — callback-based memoizer (default)
+//   - lruMemoizer.sync(options) — synchronous memoizer
+//
+// The options object contains:
+//   - load: the function to memoize (fetches the value on cache miss)
+//   - hash: key generation function
+//   - max: max cache entries
+//   - maxAge: TTL in ms
+//
+// Captured attributes:
+//   - memoizer.operation: 'lookup'
+//   - memoizer.name: function name or 'memoized'
+//   - memoizer.cache_size: current cache size (if available)
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Memoized function wrapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a memoized function (returned by lru-memoizer) to add spans.
+ * The original load function name is used as the span name.
+ */
+const wrapMemoizedFunction = (
+  memoized: Function,
+  loadFnName: string,
+  options?: SenzorOptions
+): Function => {
+  if (typeof memoized !== 'function') return memoized;
+  if ((memoized as any).__senzorWrapped) return memoized;
+
+  const name = loadFnName || 'memoized';
+
+  const wrapped = function wrappedMemoized(this: any, ...args: any[]) {
+    const span = startCapturedSpan(
+      `LRU ${name}`,
+      'function',
+      {
+        'memoizer.operation': 'lookup',
+        'memoizer.name': name,
+        library: 'lru-memoizer',
+      },
+      options
+    );
+
+    if (!span) return memoized.apply(this, args);
+
+    // Check if last arg is a callback
+    const lastIdx = args.length - 1;
+    const hasCallback = lastIdx >= 0 && typeof args[lastIdx] === 'function';
+
+    if (hasCallback) {
+      const originalCb = args[lastIdx];
+      args[lastIdx] = function (err: any, ...results: any[]) {
+        if (err) {
+          span.end(500, {
+            'error.message': typeof err === 'string' ? err : err?.message,
+            'error.type': err?.name || 'Error',
+          });
+        } else {
+          span.end(0);
+        }
+        return originalCb.call(this, err, ...results);
+      };
+
+      return runWithCapturedSpan(span, () => {
+        try {
+          return memoized.apply(this, args);
+        } catch (error: any) {
+          span.end(500, { 'error.message': error?.message });
+          throw error;
+        }
+      });
+    }
+
+    // Promise-based or sync
+    return runWithCapturedSpan(span, () => {
+      try {
+        const result = memoized.apply(this, args);
+
+        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;
+      }
+    });
+  };
+
+  // Preserve any properties on the original memoized function
+  // (e.g., .keys(), .reset(), .del())
+  for (const key of Object.keys(memoized)) {
+    try { (wrapped as any)[key] = (memoized as any)[key]; } catch { }
+  }
+
+  (wrapped as any).__senzorWrapped = true;
+  return wrapped;
+};
+
+// ---------------------------------------------------------------------------
+// Factory wrapping
+// ---------------------------------------------------------------------------
+
+const patchLruMemoizer = (lruMemoizer: any, options?: SenzorOptions) => {
+  if (typeof lruMemoizer !== 'function') return lruMemoizer;
+
+  // Wrap the main factory (callback-based)
+  const wrappedFactory = function patchedLruMemoizer(this: any, memoizerOptions: any) {
+    const loadFnName = memoizerOptions?.load?.name || memoizerOptions?.name || 'memoized';
+    const result = lruMemoizer.call(this, memoizerOptions);
+    return wrapMemoizedFunction(result, loadFnName, options);
+  };
+
+  // Copy all static properties
+  for (const key of Object.keys(lruMemoizer)) {
+    try { (wrappedFactory as any)[key] = (lruMemoizer as any)[key]; } catch { }
+  }
+
+  // Wrap .sync() if it exists
+  if (typeof lruMemoizer.sync === 'function') {
+    const originalSync = lruMemoizer.sync;
+    (wrappedFactory as any).sync = function patchedSync(this: any, memoizerOptions: any) {
+      const loadFnName = memoizerOptions?.load?.name || memoizerOptions?.name || 'memoized-sync';
+      const result = originalSync.call(this, memoizerOptions);
+      return wrapMemoizedFunction(result, loadFnName, options);
+    };
+  }
+
+  return wrappedFactory;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentLruMemoizer = (options?: SenzorOptions) => {
+  hookRequire('lru-memoizer', (exports: any) => {
+    // lru-memoizer exports the factory directly
+    if (typeof exports === 'function') {
+      return patchLruMemoizer(exports, options);
+    }
+
+    // Handle { default: fn } or { memoizer: fn }
+    if (typeof exports?.default === 'function') {
+      exports.default = patchLruMemoizer(exports.default, options);
+    }
+  });
+};

package/src/instrumentation/memcached.ts

@@ -0,0 +1,190 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Memcached Instrumentation
+//
+// Instruments the `memcached` npm package (the most popular pure-JS
+// Memcached client for Node.js, used by production deployments).
+//
+// Patches Memcached.prototype command methods:
+//   - get(), gets(), getMulti()        — read operations
+//   - set(), add(), replace(), cas()   — write operations
+//   - append(), prepend()              — mutation operations
+//   - incr(), decr()                   — counter operations
+//   - del() / delete()                 — delete operations
+//   - touch()                          — TTL refresh
+//   - stats(), version(), items()      — admin/info operations
+//   - flush()                          — cache flush
+//
+// All memcached operations are callback-based. The callback is always
+// the last argument: fn(err, result).
+//
+// Captured attributes (OTel semantic conventions):
+//   - db.system.name: 'memcached'
+//   - db.operation.name: GET, SET, DELETE, etc.
+//   - db.memcached.key: cache key (if single key)
+//   - db.memcached.key_count: number of keys (for multi-key ops)
+//   - server.address: memcached server(s)
+// ---------------------------------------------------------------------------
+
+/** Commands to instrument, grouped by signature pattern. */
+const KEY_VALUE_COMMANDS = ['set', 'add', 'replace', 'append', 'prepend'] as const;
+const KEY_ONLY_COMMANDS = ['get', 'gets', 'del', 'delete', 'touch'] as const;
+const KEY_NUMBER_COMMANDS = ['incr', 'decr'] as const;
+const CAS_COMMAND = ['cas'] as const;
+const MULTI_KEY_COMMANDS = ['getMulti'] as const;
+const NO_KEY_COMMANDS = ['stats', 'version', 'items', 'flush'] as const;
+
+/** Get server address string from a Memcached instance. */
+const getServerAddress = (client: any): string | undefined => {
+  try {
+    const servers = client?.servers;
+    if (Array.isArray(servers) && servers.length > 0) {
+      return servers.length === 1 ? servers[0] : `${servers[0]} (+${servers.length - 1})`;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Generic command wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a callback-based memcached command.
+ * The callback is always the last argument in memcached commands.
+ */
+const wrapCommand = (
+  proto: any,
+  commandName: string,
+  getSpanMeta: (args: any[]) => Record<string, any>,
+  options?: SenzorOptions
+) => {
+  if (typeof proto[commandName] !== 'function') return;
+
+  patchMethod(
+    proto,
+    commandName,
+    `senzor.memcached.${commandName}`,
+    (original) =>
+      function patchedCommand(this: any, ...args: any[]) {
+        const operation = commandName.toUpperCase();
+        const serverAddress = getServerAddress(this);
+        const extraMeta = getSpanMeta(args);
+
+        const span = startCapturedSpan(
+          `Memcached ${operation}`,
+          'db',
+          {
+            'db.system.name': 'memcached',
+            'db.operation.name': operation,
+            'server.address': serverAddress,
+            library: 'memcached',
+            ...extraMeta,
+          },
+          options
+        );
+
+        if (!span) return original.apply(this, args);
+
+        // Wrap the callback (always last argument)
+        const callbackIndex = args.length - 1;
+        if (callbackIndex >= 0 && typeof args[callbackIndex] === 'function') {
+          const originalCb = args[callbackIndex];
+          args[callbackIndex] = function (err: any, ...results: any[]) {
+            if (err) {
+              span.end(500, {
+                'error.message': typeof err === 'string' ? err : err?.message,
+                'error.type': err?.name || 'MemcachedError',
+              });
+            } else {
+              span.end(0);
+            }
+            return originalCb.call(this, err, ...results);
+          };
+        } else {
+          // No callback — end span immediately
+          span.end(0);
+        }
+
+        return runWithCapturedSpan(span, () => {
+          try {
+            return original.apply(this, args);
+          } catch (error: any) {
+            span.end(500, { 'error.message': error?.message });
+            throw error;
+          }
+        });
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Memcached prototype patching
+// ---------------------------------------------------------------------------
+
+const patchMemcachedClient = (Memcached: any, options?: SenzorOptions) => {
+  const proto = Memcached?.prototype;
+  if (!proto) return;
+
+  // key-value commands: command(key, value, lifetime, callback)
+  for (const cmd of KEY_VALUE_COMMANDS) {
+    wrapCommand(proto, cmd, (args) => ({
+      'db.memcached.key': typeof args[0] === 'string' ? args[0] : undefined,
+    }), options);
+  }
+
+  // key-only commands: command(key, callback) or command(key, ttl, callback)
+  for (const cmd of KEY_ONLY_COMMANDS) {
+    wrapCommand(proto, cmd, (args) => ({
+      'db.memcached.key': typeof args[0] === 'string' ? args[0] : undefined,
+    }), options);
+  }
+
+  // key-number commands: command(key, amount, callback)
+  for (const cmd of KEY_NUMBER_COMMANDS) {
+    wrapCommand(proto, cmd, (args) => ({
+      'db.memcached.key': typeof args[0] === 'string' ? args[0] : undefined,
+    }), options);
+  }
+
+  // cas: cas(key, value, cas, lifetime, callback)
+  for (const cmd of CAS_COMMAND) {
+    wrapCommand(proto, cmd, (args) => ({
+      'db.memcached.key': typeof args[0] === 'string' ? args[0] : undefined,
+    }), options);
+  }
+
+  // multi-key commands: command(keys, callback) where keys is string[]
+  for (const cmd of MULTI_KEY_COMMANDS) {
+    wrapCommand(proto, cmd, (args) => ({
+      'db.memcached.key_count': Array.isArray(args[0]) ? args[0].length : undefined,
+    }), options);
+  }
+
+  // no-key commands: command(callback)
+  for (const cmd of NO_KEY_COMMANDS) {
+    wrapCommand(proto, cmd, () => ({}), options);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentMemcached = (options?: SenzorOptions) => {
+  hookRequire('memcached', (exports: any) => {
+    // memcached exports the constructor directly
+    patchMemcachedClient(exports, options);
+
+    // Handle default export
+    if (exports?.default?.prototype) {
+      patchMemcachedClient(exports.default, options);
+    }
+  });
+};