@senzops/apm-node 1.2.7 → 1.3.0

package/src/instrumentation/firebase.ts

@@ -0,0 +1,445 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Firebase Admin SDK Instrumentation
+//
+// Instruments `firebase-admin` services:
+//   1. Firestore — document/collection CRUD and queries
+//   2. Auth — user management and token verification
+//   3. Storage — file upload/download operations
+//   4. Messaging (FCM) — push notification delivery
+//
+// Also instruments `firebase-functions` for Cloud Functions triggers.
+//
+// Strategy: Hook each firebase-admin sub-module separately since they're
+// lazy-loaded. Firestore is the most critical — we patch DocumentReference,
+// CollectionReference, Query, and Transaction prototypes.
+//
+// Captured attributes:
+//   - db.system.name: 'firestore' (for Firestore ops)
+//   - db.operation.name: GET, SET, ADD, UPDATE, DELETE, QUERY
+//   - db.collection.name: collection path
+//   - firebase.service: 'firestore' | 'auth' | 'storage' | 'messaging'
+//   - firebase.operation: specific operation name
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Firestore patching
+// ---------------------------------------------------------------------------
+
+/** Wrap an async Firestore method that returns a promise. */
+const wrapFirestoreMethod = (
+  proto: any,
+  methodName: string,
+  getSpanInfo: (instance: any, args: any[]) => { name: string; meta: Record<string, any> },
+  patchKey: string,
+  options?: SenzorOptions
+) => {
+  if (!proto || typeof proto[methodName] !== 'function') return;
+
+  patchMethod(
+    proto,
+    methodName,
+    patchKey,
+    (original) =>
+      function patchedFirestoreMethod(this: any, ...args: any[]) {
+        const { name, meta } = getSpanInfo(this, args);
+
+        const span = startCapturedSpan(name, 'db', meta, 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) => {
+                  const endMeta: Record<string, any> = {};
+                  // DocumentSnapshot
+                  if (value?.exists !== undefined) {
+                    endMeta['firestore.exists'] = value.exists;
+                  }
+                  // QuerySnapshot
+                  if (value?.size !== undefined) {
+                    endMeta['db.response.row_count'] = value.size;
+                  }
+                  span.end(0, endMeta);
+                  return value;
+                },
+                (error: any) => {
+                  span.end(error?.code || 500, {
+                    'error.message': error?.message,
+                    'error.type': error?.name || 'FirestoreError',
+                    'db.error.code': error?.code,
+                  });
+                  throw error;
+                }
+              );
+            }
+
+            // WriteResult (for set, update, delete — they return a WriteResult promise)
+            span.end(0);
+            return result;
+          } catch (error: any) {
+            span.end(500, { 'error.message': error?.message });
+            throw error;
+          }
+        });
+      }
+  );
+};
+
+/** Get the collection path from a DocumentReference or CollectionReference. */
+const getPath = (ref: any): string => {
+  try {
+    return ref?.path || ref?._path?.toString() || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+const getCollectionName = (ref: any): string => {
+  try {
+    // For DocumentReference, parent is the collection
+    if (ref?.parent?.id) return ref.parent.id;
+    // For CollectionReference, id is the collection name
+    if (ref?.id) return ref.id;
+    // For Query, try _query or _path
+    if (ref?._query?._path) return ref._query._path.toString().split('/').pop() || 'unknown';
+    return getPath(ref).split('/').filter(Boolean).slice(-2, -1)[0] || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+const patchFirestore = (firestoreModule: any, options?: SenzorOptions) => {
+  // --- DocumentReference ---
+  const DocRef = firestoreModule?.DocumentReference;
+  if (DocRef?.prototype) {
+    const docProto = DocRef.prototype;
+
+    // get()
+    wrapFirestoreMethod(docProto, 'get', (instance) => ({
+      name: `Firestore GET ${getPath(instance)}`,
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'GET',
+        'db.collection.name': getCollectionName(instance),
+        'firestore.path': getPath(instance),
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.docRef.get', options);
+
+    // set()
+    wrapFirestoreMethod(docProto, 'set', (instance) => ({
+      name: `Firestore SET ${getPath(instance)}`,
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'SET',
+        'db.collection.name': getCollectionName(instance),
+        'firestore.path': getPath(instance),
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.docRef.set', options);
+
+    // update()
+    wrapFirestoreMethod(docProto, 'update', (instance) => ({
+      name: `Firestore UPDATE ${getPath(instance)}`,
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'UPDATE',
+        'db.collection.name': getCollectionName(instance),
+        'firestore.path': getPath(instance),
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.docRef.update', options);
+
+    // delete()
+    wrapFirestoreMethod(docProto, 'delete', (instance) => ({
+      name: `Firestore DELETE ${getPath(instance)}`,
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'DELETE',
+        'db.collection.name': getCollectionName(instance),
+        'firestore.path': getPath(instance),
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.docRef.delete', options);
+
+    // create()
+    if (typeof docProto.create === 'function') {
+      wrapFirestoreMethod(docProto, 'create', (instance) => ({
+        name: `Firestore CREATE ${getPath(instance)}`,
+        meta: {
+          'db.system.name': 'firestore',
+          'db.operation.name': 'CREATE',
+          'db.collection.name': getCollectionName(instance),
+          'firebase.service': 'firestore',
+          library: 'firebase-admin',
+        },
+      }), 'senzor.firebase.docRef.create', options);
+    }
+  }
+
+  // --- CollectionReference ---
+  const ColRef = firestoreModule?.CollectionReference;
+  if (ColRef?.prototype) {
+    // add()
+    wrapFirestoreMethod(ColRef.prototype, 'add', (instance) => ({
+      name: `Firestore ADD ${getPath(instance)}`,
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'ADD',
+        'db.collection.name': getCollectionName(instance),
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.colRef.add', options);
+
+    // listDocuments()
+    if (typeof ColRef.prototype.listDocuments === 'function') {
+      wrapFirestoreMethod(ColRef.prototype, 'listDocuments', (instance) => ({
+        name: `Firestore LIST ${getPath(instance)}`,
+        meta: {
+          'db.system.name': 'firestore',
+          'db.operation.name': 'LIST',
+          'db.collection.name': getCollectionName(instance),
+          'firebase.service': 'firestore',
+          library: 'firebase-admin',
+        },
+      }), 'senzor.firebase.colRef.listDocuments', options);
+    }
+  }
+
+  // --- Query ---
+  const Query = firestoreModule?.Query;
+  if (Query?.prototype) {
+    wrapFirestoreMethod(Query.prototype, 'get', (instance) => ({
+      name: `Firestore QUERY ${getCollectionName(instance)}`,
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'QUERY',
+        'db.collection.name': getCollectionName(instance),
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.query.get', options);
+  }
+
+  // --- Transaction ---
+  const Transaction = firestoreModule?.Transaction;
+  if (Transaction?.prototype) {
+    for (const method of ['get', 'set', 'update', 'delete', 'create'] as const) {
+      if (typeof Transaction.prototype[method] !== 'function') continue;
+      // Transaction methods are sync (they queue operations) — except get()
+      if (method === 'get') {
+        wrapFirestoreMethod(Transaction.prototype, 'get', (_instance, args) => ({
+          name: `Firestore TX GET ${getPath(args[0])}`,
+          meta: {
+            'db.system.name': 'firestore',
+            'db.operation.name': 'TX_GET',
+            'firebase.service': 'firestore',
+            library: 'firebase-admin',
+          },
+        }), 'senzor.firebase.transaction.get', options);
+      }
+    }
+  }
+
+  // --- WriteBatch ---
+  const WriteBatch = firestoreModule?.WriteBatch;
+  if (WriteBatch?.prototype && typeof WriteBatch.prototype.commit === 'function') {
+    wrapFirestoreMethod(WriteBatch.prototype, 'commit', () => ({
+      name: 'Firestore BATCH COMMIT',
+      meta: {
+        'db.system.name': 'firestore',
+        'db.operation.name': 'BATCH_COMMIT',
+        'firebase.service': 'firestore',
+        library: 'firebase-admin',
+      },
+    }), 'senzor.firebase.writeBatch.commit', options);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Auth patching
+// ---------------------------------------------------------------------------
+
+const AUTH_METHODS = [
+  'createUser', 'getUser', 'getUserByEmail', 'getUserByPhoneNumber',
+  'listUsers', 'deleteUser', 'deleteUsers', 'updateUser',
+  'verifyIdToken', 'verifySessionCookie', 'createSessionCookie',
+  'revokeRefreshTokens', 'setCustomUserClaims', 'generateEmailVerificationLink',
+  'generatePasswordResetLink', 'generateSignInWithEmailLink',
+] as const;
+
+const patchFirebaseAuth = (authModule: any, options?: SenzorOptions) => {
+  // Auth is typically at auth().* or Auth.prototype
+  const Auth = authModule?.Auth;
+  if (!Auth?.prototype) return;
+
+  for (const method of AUTH_METHODS) {
+    if (typeof Auth.prototype[method] !== 'function') continue;
+
+    patchMethod(
+      Auth.prototype,
+      method,
+      `senzor.firebase.auth.${method}`,
+      (original) =>
+        function patchedAuthMethod(this: any, ...args: any[]) {
+          const span = startCapturedSpan(
+            `Firebase Auth ${method}`,
+            'function',
+            {
+              'firebase.service': 'auth',
+              'firebase.operation': method,
+              library: 'firebase-admin',
+            },
+            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); return value; },
+                  (error: any) => {
+                    span.end(500, {
+                      'error.message': error?.message,
+                      'error.type': error?.code || error?.name || 'AuthError',
+                    });
+                    throw error;
+                  }
+                );
+              }
+              span.end(0);
+              return result;
+            } catch (error: any) {
+              span.end(500, { 'error.message': error?.message });
+              throw error;
+            }
+          });
+        }
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Messaging (FCM) patching
+// ---------------------------------------------------------------------------
+
+const MESSAGING_METHODS = [
+  'send', 'sendEach', 'sendEachForMulticast', 'sendMulticast',
+  'sendToDevice', 'sendToTopic', 'sendToCondition',
+  'subscribeToTopic', 'unsubscribeFromTopic',
+] as const;
+
+const patchFirebaseMessaging = (messagingModule: any, options?: SenzorOptions) => {
+  const Messaging = messagingModule?.Messaging;
+  if (!Messaging?.prototype) return;
+
+  for (const method of MESSAGING_METHODS) {
+    if (typeof Messaging.prototype[method] !== 'function') continue;
+
+    patchMethod(
+      Messaging.prototype,
+      method,
+      `senzor.firebase.messaging.${method}`,
+      (original) =>
+        function patchedMessagingMethod(this: any, ...args: any[]) {
+          const span = startCapturedSpan(
+            `Firebase FCM ${method}`,
+            'messaging',
+            {
+              'firebase.service': 'messaging',
+              'firebase.operation': method,
+              'messaging.system': 'fcm',
+              library: 'firebase-admin',
+            },
+            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) => {
+                    const endMeta: Record<string, any> = {};
+                    // sendEach/sendMulticast returns BatchResponse
+                    if (value?.successCount !== undefined) {
+                      endMeta['firebase.fcm.success_count'] = value.successCount;
+                      endMeta['firebase.fcm.failure_count'] = value.failureCount;
+                    }
+                    span.end(0, endMeta);
+                    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 instrumentFirebase = (options?: SenzorOptions) => {
+  // Firestore
+  hookRequire('firebase-admin/firestore', (exports: any) => {
+    patchFirestore(exports, options);
+  });
+  hookRequire('@google-cloud/firestore', (exports: any) => {
+    patchFirestore(exports, options);
+  });
+
+  // Auth
+  hookRequire('firebase-admin/auth', (exports: any) => {
+    patchFirebaseAuth(exports, options);
+  });
+
+  // Messaging
+  hookRequire('firebase-admin/messaging', (exports: any) => {
+    patchFirebaseMessaging(exports, options);
+  });
+
+  // firebase-admin main module — try to access services from it
+  hookRequire('firebase-admin', (exports: any) => {
+    // In newer firebase-admin, services are at exports.firestore, exports.auth, etc.
+    // They're getter-based, so accessing them triggers sub-module loading
+    // which our hooks above will catch.
+    // Just ensure the main module export is patched if it exposes prototypes
+    try {
+      const firestore = exports?.firestore;
+      if (firestore) {
+        // This forces the lazy-load, which triggers our hookRequire above
+      }
+    } catch { }
+  });
+};

package/src/instrumentation/fs.ts

@@ -0,0 +1,260 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// File System (fs) Instrumentation
+//
+// Instruments Node.js core `fs` module to capture file I/O operations.
+// File system calls are a common source of latency in Node.js applications
+// (template rendering, config loading, log writing, file uploads, etc.).
+//
+// Only instruments ASYNC methods (callback + promises) — never sync methods,
+// as those block the event loop and adding span overhead would be wasteful.
+//
+// Patches:
+//   - Callback-based: fs.readFile, fs.writeFile, fs.stat, fs.access,
+//     fs.readdir, fs.mkdir, fs.rmdir, fs.unlink, fs.rename, fs.copyFile,
+//     fs.appendFile, fs.chmod, fs.chown, fs.link, fs.symlink, fs.realpath,
+//     fs.mkdtemp, fs.open, fs.close
+//   - Promise-based: fs.promises.* (same set)
+//
+// Captured attributes:
+//   - fs.operation: readFile, writeFile, stat, etc.
+//   - fs.path: file path (sanitized — no secrets in paths)
+//   - fs.flags: open flags (r, w, a, etc.)
+// ---------------------------------------------------------------------------
+
+/** Operations to instrument. Grouped by argument patterns. */
+const PATH_OPERATIONS = [
+  'readFile', 'writeFile', 'appendFile', 'stat', 'lstat',
+  'access', 'readdir', 'mkdir', 'rmdir', 'unlink',
+  'chmod', 'chown', 'realpath', 'mkdtemp', 'truncate',
+  'readlink', 'exists',
+] as const;
+
+const TWO_PATH_OPERATIONS = [
+  'rename', 'copyFile', 'link', 'symlink',
+] as const;
+
+/** Sanitize a file path — strip home directory prefix for privacy. */
+const sanitizePath = (filePath: any): string | undefined => {
+  if (typeof filePath !== 'string' && !(filePath instanceof Buffer) && !(filePath instanceof URL)) {
+    return undefined;
+  }
+  const pathStr = String(filePath);
+  // Truncate very long paths
+  if (pathStr.length > 200) return pathStr.slice(0, 200) + '...';
+  return pathStr;
+};
+
+// ---------------------------------------------------------------------------
+// Callback-based fs method patching
+// ---------------------------------------------------------------------------
+
+const patchFsCallbackMethod = (
+  fsModule: any,
+  methodName: string,
+  pathArgCount: number,
+  options?: SenzorOptions
+) => {
+  if (typeof fsModule[methodName] !== 'function') return;
+
+  patchMethod(
+    fsModule,
+    methodName,
+    `senzor.fs.${methodName}`,
+    (original) =>
+      function patchedFsMethod(this: any, ...args: any[]) {
+        const operation = methodName.toUpperCase();
+        const filePath = sanitizePath(args[0]);
+
+        const spanMeta: Record<string, any> = {
+          'fs.operation': methodName,
+          'fs.path': filePath,
+          library: 'fs',
+        };
+
+        if (pathArgCount === 2 && args[1]) {
+          spanMeta['fs.destination'] = sanitizePath(args[1]);
+        }
+
+        const span = startCapturedSpan(
+          `FS ${operation}`,
+          'custom',
+          spanMeta,
+          options
+        );
+
+        if (!span) return original.apply(this, args);
+
+        // Find and wrap the callback (last function argument)
+        const callbackIndex = args.findIndex(
+          (arg, idx) => idx >= pathArgCount && typeof arg === 'function'
+        );
+
+        if (callbackIndex >= 0) {
+          const originalCb = args[callbackIndex];
+          args[callbackIndex] = function (err: any, ...results: any[]) {
+            if (err) {
+              span.end(500, {
+                'error.message': err.message,
+                'error.type': err.name || 'Error',
+                'error.code': err.code,
+              });
+            } else {
+              span.end(0);
+            }
+            return originalCb.call(this, err, ...results);
+          };
+        }
+
+        return runWithCapturedSpan(span, () => {
+          try {
+            const result = original.apply(this, args);
+
+            // If no callback found, end span after sync return
+            if (callbackIndex < 0) {
+              span.end(0);
+            }
+
+            return result;
+          } catch (error: any) {
+            span.end(500, {
+              'error.message': error?.message,
+              'error.code': error?.code,
+            });
+            throw error;
+          }
+        });
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Promise-based fs.promises method patching
+// ---------------------------------------------------------------------------
+
+const patchFsPromiseMethod = (
+  fsPromises: any,
+  methodName: string,
+  pathArgCount: number,
+  options?: SenzorOptions
+) => {
+  if (typeof fsPromises[methodName] !== 'function') return;
+
+  patchMethod(
+    fsPromises,
+    methodName,
+    `senzor.fs.promises.${methodName}`,
+    (original) =>
+      function patchedFsPromiseMethod(this: any, ...args: any[]) {
+        const operation = methodName.toUpperCase();
+        const filePath = sanitizePath(args[0]);
+
+        const spanMeta: Record<string, any> = {
+          'fs.operation': methodName,
+          'fs.path': filePath,
+          'fs.api': 'promises',
+          library: 'fs',
+        };
+
+        if (pathArgCount === 2 && args[1]) {
+          spanMeta['fs.destination'] = sanitizePath(args[1]);
+        }
+
+        const span = startCapturedSpan(
+          `FS ${operation}`,
+          'custom',
+          spanMeta,
+          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); return value; },
+                (error: any) => {
+                  span.end(500, {
+                    'error.message': error?.message,
+                    'error.code': error?.code,
+                  });
+                  throw error;
+                }
+              );
+            }
+
+            span.end(0);
+            return result;
+          } catch (error: any) {
+            span.end(500, { 'error.message': error?.message });
+            throw error;
+          }
+        });
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Core fs module patching
+// ---------------------------------------------------------------------------
+
+const patchFs = (fsModule: any, options?: SenzorOptions) => {
+  if (!fsModule) return;
+
+  // Patch callback-based methods (single path argument)
+  for (const method of PATH_OPERATIONS) {
+    patchFsCallbackMethod(fsModule, method, 1, options);
+  }
+
+  // Patch callback-based methods (two path arguments)
+  for (const method of TWO_PATH_OPERATIONS) {
+    patchFsCallbackMethod(fsModule, method, 2, options);
+  }
+
+  // Patch open/close separately (they have different signatures)
+  patchFsCallbackMethod(fsModule, 'open', 1, options);
+  patchFsCallbackMethod(fsModule, 'close', 1, options);
+
+  // Patch fs.promises
+  const promises = fsModule.promises;
+  if (promises) {
+    for (const method of PATH_OPERATIONS) {
+      if (method === 'exists') continue; // fs.promises.exists doesn't exist
+      patchFsPromiseMethod(promises, method, 1, options);
+    }
+
+    for (const method of TWO_PATH_OPERATIONS) {
+      patchFsPromiseMethod(promises, method, 2, options);
+    }
+
+    patchFsPromiseMethod(promises, 'open', 1, options);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentFs = (options?: SenzorOptions) => {
+  // fs is a Node.js built-in — require it directly
+  try {
+    const fs = require('fs');
+    patchFs(fs, options);
+  } catch { }
+
+  // Also hook for any dynamic requires
+  hookRequire('fs', (exports: any) => {
+    patchFs(exports, options);
+  });
+
+  hookRequire('node:fs', (exports: any) => {
+    patchFs(exports, options);
+  });
+};