@senzops/apm-node 1.2.0 → 1.2.1

package/src/instrumentation/framework.ts

@@ -0,0 +1,301 @@
+import { Context } from '../core/context';
+import { SenzorOptions } from '../core/types';
+import { CapturedSpan, runWithCapturedSpan, startCapturedSpan } from './span';
+
+export type FrameworkSpanType =
+  | 'middleware'
+  | 'router'
+  | 'request_handler'
+  | 'route_handler'
+  | 'controller_handler'
+  | 'lifecycle_hook'
+  | 'error_handler'
+  | 'event_handler';
+
+export interface FrameworkSpanInfo {
+  framework: string;
+  type: FrameworkSpanType;
+  name: string;
+  route?: string;
+  method?: string;
+  layerPath?: string;
+  handlerName?: string;
+  request?: any;
+  response?: any;
+  attributes?: Record<string, unknown>;
+}
+
+interface InvokeOptions {
+  callbackIndex?: number;
+  callbackCompletesSpan?: boolean;
+  responseEndsSpan?: boolean;
+}
+
+const ignoredNextValues = new Set([undefined, null, 'route', 'router']);
+
+export const shouldCaptureFrameworkSpan = (
+  type: FrameworkSpanType,
+  options?: SenzorOptions
+): boolean => {
+  if (options?.frameworkSpans === false) return false;
+  if (type === 'middleware' && options?.captureMiddlewareSpans === false) return false;
+  if (type === 'router' && options?.captureRouterSpans === false) return false;
+  if (type === 'lifecycle_hook' && options?.captureLifecycleHookSpans === false) return false;
+  if (options?.ignoreFrameworkSpanTypes?.includes(type)) return false;
+  return true;
+};
+
+const statusFrom = (
+  info: FrameworkSpanInfo,
+  fallback = 0
+): number => {
+  const res = info.response;
+  return (
+    res?.statusCode ||
+    res?.status ||
+    res?.raw?.statusCode ||
+    res?.status_code ||
+    fallback
+  );
+};
+
+const isPromiseLike = (value: unknown): value is Promise<unknown> =>
+  Boolean(value && typeof (value as any).then === 'function');
+
+const runWithParentOf = <T>(
+  span: CapturedSpan,
+  fn: () => T
+): T => {
+  if (!span.parentSpanId) return fn();
+  return Context.withActiveSpan(span.parentSpanId, fn);
+};
+
+const copyFunctionProperties = (
+  source: Function,
+  target: Function
+) => {
+  for (const key in source as any) {
+    try {
+      Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: true,
+        get() {
+          return (source as any)[key];
+        },
+        set(value) {
+          (source as any)[key] = value;
+        }
+      });
+    } catch { }
+  }
+};
+
+export const invokeWithFrameworkSpan = (
+  handler: Function,
+  thisArg: unknown,
+  args: any[],
+  info: FrameworkSpanInfo,
+  options?: SenzorOptions,
+  invokeOptions: InvokeOptions = {}
+) => {
+  if (!shouldCaptureFrameworkSpan(info.type, options) || !Context.current()) {
+    return handler.apply(thisArg, args);
+  }
+
+  const span = startCapturedSpan(
+    info.name,
+    'function',
+    {
+      framework: info.framework,
+      'senzor.framework': info.framework,
+      'senzor.framework.type': info.type,
+      'http.route': info.route,
+      route: info.route,
+      method: info.method,
+      layerPath: info.layerPath,
+      handlerName: info.handlerName,
+      ...info.attributes
+    },
+    options
+  );
+
+  if (!span) return handler.apply(thisArg, args);
+
+  let ended = false;
+  const cleanup: Array<() => void> = [];
+
+  const endSpan = (
+    status = statusFrom(info),
+    meta: Record<string, unknown> = {}
+  ) => {
+    if (ended) return;
+    ended = true;
+
+    for (const clean of cleanup) {
+      try { clean(); } catch { }
+    }
+
+    span.end(status, meta);
+  };
+
+  const res = info.response;
+  if (invokeOptions.responseEndsSpan !== false && res?.once) {
+    const onFinish = () =>
+      endSpan(statusFrom(info), { completion: 'response.finish' });
+    const onClose = () =>
+      endSpan(statusFrom(info), { completion: 'response.close' });
+
+    res.once('finish', onFinish);
+    res.once('close', onClose);
+
+    cleanup.push(() => {
+      try { res.removeListener?.('finish', onFinish); } catch { }
+      try { res.removeListener?.('close', onClose); } catch { }
+    });
+  }
+
+  const callbackIndex =
+    invokeOptions.callbackIndex ??
+    args.findIndex((arg) => typeof arg === 'function');
+
+  if (
+    invokeOptions.callbackCompletesSpan !== false &&
+    callbackIndex >= 0 &&
+    typeof args[callbackIndex] === 'function'
+  ) {
+    const originalCallback = args[callbackIndex];
+    args[callbackIndex] = function wrappedFrameworkCallback(
+      this: unknown,
+      ...callbackArgs: any[]
+    ) {
+      const maybeError = callbackArgs[0];
+      const hasError = !ignoredNextValues.has(maybeError);
+
+      endSpan(hasError ? 500 : statusFrom(info), {
+        completion: 'callback',
+        error: hasError ? String(maybeError?.message || maybeError) : undefined,
+        'error.type': hasError
+          ? maybeError?.name || typeof maybeError
+          : undefined
+      });
+
+      return runWithParentOf(span, () =>
+        originalCallback.apply(this, callbackArgs)
+      );
+    };
+  }
+
+  return runWithCapturedSpan(span, () => {
+    try {
+      const result = handler.apply(thisArg, args);
+
+      if (isPromiseLike(result)) {
+        return result.then(
+          (value) => {
+            endSpan(statusFrom(info), { completion: 'promise.resolve' });
+            return value;
+          },
+          (error) => {
+            endSpan(500, {
+              completion: 'promise.reject',
+              error: error?.message,
+              'error.type': error?.name || 'Error'
+            });
+            throw error;
+          }
+        );
+      }
+
+      if (callbackIndex < 0 && invokeOptions.responseEndsSpan === false) {
+        endSpan(statusFrom(info), { completion: 'sync.return' });
+      }
+
+      return result;
+    } catch (error: any) {
+      endSpan(500, {
+        completion: 'throw',
+        error: error?.message,
+        'error.type': error?.name || 'Error'
+      });
+      throw error;
+    }
+  });
+};
+
+export const wrapFrameworkHandler = <T extends Function>(
+  handler: T,
+  getInfo: (thisArg: unknown, args: any[]) => FrameworkSpanInfo,
+  options?: SenzorOptions,
+  invokeOptions: InvokeOptions = {}
+): T => {
+  if (typeof handler !== 'function') return handler;
+
+  const wrapped = function wrappedFrameworkHandler(
+    this: unknown,
+    ...args: any[]
+  ) {
+    return invokeWithFrameworkSpan(
+      handler,
+      this,
+      args,
+      getInfo(this, args),
+      options,
+      invokeOptions
+    );
+  };
+
+  copyFunctionProperties(handler, wrapped);
+  return wrapped as unknown as T;
+};
+
+export const wrapFrameworkHandlerWithArity = <T extends Function>(
+  handler: T,
+  getInfo: (thisArg: unknown, args: any[]) => FrameworkSpanInfo,
+  options?: SenzorOptions,
+  invokeOptions: InvokeOptions = {}
+): T => {
+  if (typeof handler !== 'function') return handler;
+
+  const invoke = (thisArg: unknown, args: any[]) =>
+    invokeWithFrameworkSpan(
+      handler,
+      thisArg,
+      args,
+      getInfo(thisArg, args),
+      options,
+      invokeOptions
+    );
+
+  let wrapped: Function;
+
+  switch (handler.length) {
+    case 4:
+      wrapped = function wrapped4(this: unknown, a: any, b: any, c: any, d: any) {
+        return invoke(this, [a, b, c, d]);
+      };
+      break;
+    case 3:
+      wrapped = function wrapped3(this: unknown, a: any, b: any, c: any) {
+        return invoke(this, [a, b, c]);
+      };
+      break;
+    case 2:
+      wrapped = function wrapped2(this: unknown, a: any, b: any) {
+        return invoke(this, [a, b]);
+      };
+      break;
+    case 1:
+      wrapped = function wrapped1(this: unknown, a: any) {
+        return invoke(this, [a]);
+      };
+      break;
+    default:
+      wrapped = function wrapped0(this: unknown) {
+        return invoke(this, Array.from(arguments));
+      };
+      break;
+  }
+
+  copyFunctionProperties(handler, wrapped);
+  return wrapped as unknown as T;
+};

package/src/instrumentation/hook.ts

@@ -6,8 +6,8 @@ const SENZOR_PATCHED =
 const SENZOR_HOOKS =
   Symbol.for('senzor.require.hooks');
 
-type HookFn =
-  (exports: unknown) => void;
+type HookFn =
+  (exports: unknown) => unknown | void;
 
 type HookMap =
   Map<string, HookFn[]>;
@@ -37,10 +37,10 @@ function getHookRegistry(): HookMap {
 
 }
 
-function runHooks(
-  moduleName: string,
-  exports: unknown
-) {
+function runHooks(
+  moduleName: string,
+  exports: unknown
+) {
 
   const registry =
     (Module as unknown as Record<
@@ -48,18 +48,27 @@ function runHooks(
       HookMap
     >)[SENZOR_HOOKS];
 
-  if (!registry) return;
+  if (!registry) return exports;
 
   const hooks =
     registry.get(moduleName);
 
-  if (!hooks?.length) return;
-
-  for (const hook of hooks) {
-
-    try {
-      hook(exports);
-    }
+  if (!hooks?.length) return exports;
+
+  let currentExports =
+    exports;
+
+  for (const hook of hooks) {
+
+    try {
+      const nextExports =
+        hook(currentExports);
+
+      if (nextExports !== undefined) {
+        currentExports =
+          nextExports;
+      }
+    }
     catch (err) {
 
       console.error(
@@ -69,9 +78,11 @@ function runHooks(
 
     }
 
-  }
-
-}
+  }
+
+  return currentExports;
+
+}
 
 function patchLoaderOnce() {
 
@@ -98,12 +109,13 @@ function patchLoaderOnce() {
           arguments
         );
 
-      runHooks(
-        request,
-        exports
-      );
-
-      return exports;
+      const patchedExports =
+        runHooks(
+        request,
+        exports
+      );
+
+      return patchedExports;
 
     };
 
@@ -137,11 +149,17 @@ function patchCached(
 
     if (cached?.exports) {
 
-      hook(
-        cached.exports
-      );
-
-    }
+      const replacement =
+        hook(
+        cached.exports
+      );
+
+      if (replacement !== undefined) {
+        cached.exports =
+          replacement;
+      }
+
+    }
 
   }
   catch { }
@@ -159,7 +177,7 @@ function tryRequire(
       require(moduleName);
 
     if (mod) {
-      hook(mod);
+      hook(mod);
     }
 
   }
@@ -188,7 +206,7 @@ function retryPatch(
 
         if (mod) {
 
-          hook(mod);
+          hook(mod);
 
           clearInterval(timer);
 
@@ -244,4 +262,4 @@ export const hookRequire =
       onRequire
     );
 
-  };
+  };

package/src/instrumentation/koa.ts

@@ -0,0 +1,173 @@
+import { normalizePath } from '../core/normalizer';
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { wrapFrameworkHandlerWithArity } from './framework';
+
+const routerMethods = [
+  'all',
+  'del',
+  'delete',
+  'get',
+  'head',
+  'options',
+  'patch',
+  'post',
+  'put'
+];
+
+const stringifyPath = (value: unknown): string | undefined => {
+  if (typeof value === 'string') return value;
+  if (value instanceof RegExp) return value.toString();
+  if (Array.isArray(value)) {
+    return value.map(stringifyPath).filter(Boolean).join(',');
+  }
+  return undefined;
+};
+
+const getPathFromArgs = (args: any[]): string | undefined => {
+  for (const arg of args) {
+    if (typeof arg === 'function') return undefined;
+    const path = stringifyPath(arg);
+    if (path) return path;
+  }
+
+  return undefined;
+};
+
+const wrapKoaMiddleware = (
+  middleware: any,
+  options?: SenzorOptions,
+  layerPath?: string,
+  layerType: 'middleware' | 'router' | 'route_handler' = 'middleware',
+  method?: string
+) => {
+  if (typeof middleware !== 'function') return middleware;
+
+  return wrapFrameworkHandlerWithArity(
+    middleware,
+    (_thisArg, args) => {
+      const ctx = args[0];
+      const route =
+        ctx?._matchedRoute ||
+        ctx?.matched?.[0]?.path ||
+        layerPath ||
+        normalizePath(ctx?.path || ctx?.request?.path || '/');
+      const actualMethod = method || ctx?.method || ctx?.request?.method;
+      const handlerName = middleware.name || layerType;
+
+      return {
+        framework: 'koa',
+        type: layerType,
+        name:
+          layerType === 'route_handler'
+            ? `koa.request_handler ${actualMethod || ''} ${route}`.trim()
+            : `koa.${layerType} ${route || handlerName}`,
+        route,
+        method: actualMethod,
+        layerPath,
+        handlerName,
+        request: ctx?.req || ctx?.request,
+        response: ctx?.res || ctx?.response,
+        attributes: {
+          'koa.type': layerType,
+          'http.route': route,
+          path: ctx?.path || ctx?.request?.path
+        }
+      };
+    },
+    options,
+    {
+      callbackCompletesSpan: false,
+      responseEndsSpan: false
+    }
+  );
+};
+
+const patchKoaApplication = (
+  koa: any,
+  options?: SenzorOptions
+) => {
+  const proto = koa?.prototype || koa?.default?.prototype;
+  if (!proto) return;
+
+  patchMethod(
+    proto,
+    'use',
+    'senzor.koa.application.use',
+    (original) =>
+      function patchedKoaUse(this: any, middleware: any) {
+        return original.call(
+          this,
+          wrapKoaMiddleware(middleware, options, undefined, 'middleware')
+        );
+      }
+  );
+};
+
+const patchKoaRouter = (
+  routerModule: any,
+  options?: SenzorOptions
+) => {
+  const Router =
+    routerModule?.Router ||
+    routerModule?.default ||
+    routerModule;
+  const proto = Router?.prototype;
+  if (!proto) return;
+
+  patchMethod(
+    proto,
+    'use',
+    'senzor.koa.router.use',
+    (original) =>
+      function patchedKoaRouterUse(this: any, ...args: any[]) {
+        const layerPath = getPathFromArgs(args);
+        const nextArgs = args.map((arg) =>
+          typeof arg === 'function'
+            ? wrapKoaMiddleware(arg, options, layerPath, 'router')
+            : arg
+        );
+        return original.apply(this, nextArgs);
+      }
+  );
+
+  for (const method of routerMethods) {
+    patchMethod(
+      proto,
+      method,
+      `senzor.koa.router.${method}`,
+      (original) =>
+        function patchedKoaRouterMethod(this: any, ...args: any[]) {
+          const layerPath = getPathFromArgs(args);
+          const nextArgs = args.map((arg) =>
+            typeof arg === 'function'
+              ? wrapKoaMiddleware(
+                arg,
+                options,
+                layerPath,
+                'route_handler',
+                method.toUpperCase()
+              )
+              : arg
+          );
+
+          return original.apply(this, nextArgs);
+        }
+    );
+  }
+};
+
+export const instrumentKoa = (options?: SenzorOptions) => {
+  hookRequire('koa', (exports: any) => {
+    patchKoaApplication(exports, options);
+  });
+
+  hookRequire('@koa/router', (exports: any) => {
+    patchKoaRouter(exports, options);
+  });
+
+  hookRequire('koa-router', (exports: any) => {
+    patchKoaRouter(exports, options);
+  });
+};

package/src/register.ts

@@ -31,6 +31,22 @@ const options = {
   captureHeaders: truthy(process.env.SENZOR_CAPTURE_HEADERS),
   captureDbStatement:
     process.env.SENZOR_CAPTURE_DB_STATEMENT === 'false'
+      ? false
+      : undefined,
+  frameworkSpans:
+    process.env.SENZOR_FRAMEWORK_SPANS === 'false'
+      ? false
+      : undefined,
+  captureMiddlewareSpans:
+    process.env.SENZOR_CAPTURE_MIDDLEWARE_SPANS === 'false'
+      ? false
+      : undefined,
+  captureRouterSpans:
+    process.env.SENZOR_CAPTURE_ROUTER_SPANS === 'false'
+      ? false
+      : undefined,
+  captureLifecycleHookSpans:
+    process.env.SENZOR_CAPTURE_LIFECYCLE_HOOK_SPANS === 'false'
       ? false
       : undefined
 };

package/src/wrappers/fastify.ts

@@ -1,11 +1,14 @@
-import { client } from '../core/client';
-import { SenzorOptions } from '../core/types';
-import { getClientIp } from '../utils/getClientIp';
+import { client } from '../core/client';
+import { SenzorOptions } from '../core/types';
+import { instrumentFastifyInstance } from '../instrumentation/fastify';
+import { getClientIp } from '../utils/getClientIp';
 
 export const senzorPlugin = (fastify: any, options: SenzorOptions, done: Function) => {
-  if (options && options.apiKey) {
-    client.init(options);
-  }
+  if (options && options.apiKey) {
+    client.init(options);
+  }
+
+  instrumentFastifyInstance(fastify, options);
 
   fastify.addHook('onRequest', (request: any, reply: any, next: Function) => {
     client.startTrace({
@@ -29,4 +32,4 @@ export const senzorPlugin = (fastify: any, options: SenzorOptions, done: Functio
   });
 
   done();
-};
+};