@senzops/apm-node 1.2.8 → 1.3.0

package/src/instrumentation/hapi.ts

@@ -0,0 +1,257 @@
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+
+// ---------------------------------------------------------------------------
+// Hapi Instrumentation
+//
+// Instruments @hapi/hapi at the route registration layer:
+//   - Server.prototype.route() — wraps route handlers at registration time
+//     so every request generates a span with:
+//       hapi.route, hapi.method, http.route
+//
+// Captures the full handler execution including any route-level validation,
+// payload parsing, and response formatting done by Hapi.
+//
+// The handler signature is always: (request, h) => response
+// ---------------------------------------------------------------------------
+
+/** HTTP method enum to string mapping for older Hapi versions. */
+const METHOD_MAP: Record<number, string> = {
+  0: 'GET', 1: 'HEAD', 2: 'POST', 3: 'PUT',
+  4: 'DELETE', 5: 'OPTIONS', 6: 'PATCH',
+};
+
+const normalizeMethod = (method: any): string => {
+  if (typeof method === 'string') return method.toUpperCase();
+  if (typeof method === 'number') return METHOD_MAP[method] || 'UNKNOWN';
+  return 'UNKNOWN';
+};
+
+// ---------------------------------------------------------------------------
+// Handler wrapping
+// ---------------------------------------------------------------------------
+
+const wrapHandler = (
+  handler: Function,
+  routePath: string,
+  routeMethod: string,
+  options?: SenzorOptions
+): Function => {
+  if (typeof handler !== 'function') return handler;
+
+  return function wrappedHapiHandler(this: any, request: any, h: any) {
+    const method = normalizeMethod(routeMethod);
+    const path = routePath || request?.route?.path || request?.path || '/';
+
+    const span = startCapturedSpan(
+      `Hapi ${method} ${path}`,
+      'function',
+      {
+        'hapi.type': 'route_handler',
+        'hapi.route': path,
+        'hapi.method': method,
+        'http.route': path,
+        framework: 'hapi',
+      },
+      options
+    );
+
+    if (!span) return handler.call(this, request, h);
+
+    return runWithCapturedSpan(span, () => {
+      try {
+        const result = handler.call(this, request, h);
+
+        if (result && typeof result.then === 'function') {
+          return result.then(
+            (val: any) => {
+              const statusCode = val?.statusCode || request?.response?.statusCode || 200;
+              span.end(statusCode >= 400 ? statusCode : 0, {
+                'http.response.status_code': statusCode,
+              });
+              return val;
+            },
+            (error: any) => {
+              const statusCode = error?.output?.statusCode || 500;
+              span.end(statusCode, {
+                'error.message': error?.message,
+                'error.type': error?.name || 'Error',
+                'http.response.status_code': statusCode,
+              });
+              throw error;
+            }
+          );
+        }
+
+        span.end(0);
+        return result;
+      } catch (error: any) {
+        const statusCode = error?.output?.statusCode || 500;
+        span.end(statusCode, {
+          'error.message': error?.message,
+          'error.type': error?.name || 'Error',
+          'http.response.status_code': statusCode,
+        });
+        throw error;
+      }
+    });
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Route config processing
+// ---------------------------------------------------------------------------
+
+/**
+ * Process a single route configuration object and wrap its handler.
+ * Hapi route configs can have handler at config.handler or config.options.handler.
+ */
+const processRouteConfig = (config: any, options?: SenzorOptions): any => {
+  if (!config) return config;
+
+  const method = config.method || 'GET';
+  const path = config.path || '/';
+
+  // Clone config to avoid mutating user's original object
+  const wrapped = { ...config };
+
+  // Handler can be at config.handler or config.options.handler
+  if (typeof wrapped.handler === 'function') {
+    wrapped.handler = wrapHandler(wrapped.handler, path, method, options);
+  } else if (wrapped.options && typeof wrapped.options.handler === 'function') {
+    wrapped.options = { ...wrapped.options };
+    wrapped.options.handler = wrapHandler(wrapped.options.handler, path, method, options);
+  } else if (wrapped.config && typeof wrapped.config.handler === 'function') {
+    // Legacy Hapi config location
+    wrapped.config = { ...wrapped.config };
+    wrapped.config.handler = wrapHandler(wrapped.config.handler, path, method, options);
+  }
+
+  return wrapped;
+};
+
+// ---------------------------------------------------------------------------
+// Server.route() patching
+// ---------------------------------------------------------------------------
+
+const patchServerRoute = (serverProto: any, options?: SenzorOptions) => {
+  if (!serverProto) return;
+
+  patchMethod(
+    serverProto,
+    'route',
+    'senzor.hapi.server.route',
+    (original) =>
+      function patchedRoute(this: any, routeConfig: any) {
+        // server.route() accepts a single config or an array of configs
+        if (Array.isArray(routeConfig)) {
+          const wrappedConfigs = routeConfig.map((config: any) =>
+            processRouteConfig(config, options)
+          );
+          return original.call(this, wrappedConfigs);
+        }
+
+        const wrappedConfig = processRouteConfig(routeConfig, options);
+        return original.call(this, wrappedConfig);
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Extension point patching (for lifecycle span visibility)
+// ---------------------------------------------------------------------------
+
+const patchServerExt = (serverProto: any, options?: SenzorOptions) => {
+  if (!serverProto) return;
+
+  patchMethod(
+    serverProto,
+    'ext',
+    'senzor.hapi.server.ext',
+    (original) =>
+      function patchedExt(this: any, event: any, method?: any, extOptions?: any) {
+        // ext() can be called as:
+        //   ext(event, method, options)  — single extension
+        //   ext([{ type, method, options }])  — array of extensions
+        //   ext({ type, method, options })  — single object
+
+        if (typeof event === 'string' && typeof method === 'function') {
+          const eventName = event;
+          const originalMethod = method;
+
+          const wrappedMethod = function (this: any, request: any, h: any) {
+            const span = startCapturedSpan(
+              `Hapi ext ${eventName}`,
+              'function',
+              {
+                'hapi.type': 'lifecycle_hook',
+                'hapi.hook': eventName,
+                framework: 'hapi',
+              },
+              options
+            );
+
+            if (!span) return originalMethod.call(this, request, h);
+
+            return runWithCapturedSpan(span, () => {
+              try {
+                const result = originalMethod.call(this, request, h);
+                if (result && typeof result.then === 'function') {
+                  return result.then(
+                    (val: any) => { span.end(0); return val; },
+                    (err: any) => {
+                      span.end(500, { 'error.message': err?.message });
+                      throw err;
+                    }
+                  );
+                }
+                span.end(0);
+                return result;
+              } catch (err: any) {
+                span.end(500, { 'error.message': err?.message });
+                throw err;
+              }
+            });
+          };
+
+          return original.call(this, event, wrappedMethod, extOptions);
+        }
+
+        // For array/object form, pass through unchanged (avoid complex nesting)
+        return original.call(this, event, method, extOptions);
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentHapi = (options?: SenzorOptions) => {
+  hookRequire('@hapi/hapi', (exports: any) => {
+    // Hapi exports a Server class
+    const Server = exports?.Server || exports?.server?.Server;
+
+    if (Server?.prototype) {
+      patchServerRoute(Server.prototype, options);
+
+      // Only patch ext if framework spans are enabled
+      if (options?.frameworkSpans !== false) {
+        patchServerExt(Server.prototype, options);
+      }
+    }
+  });
+
+  // Also try the legacy 'hapi' package name (pre-scoped)
+  hookRequire('hapi', (exports: any) => {
+    const Server = exports?.Server || exports?.server?.Server;
+    if (Server?.prototype) {
+      patchServerRoute(Server.prototype, options);
+      if (options?.frameworkSpans !== false) {
+        patchServerExt(Server.prototype, options);
+      }
+    }
+  });
+};

package/src/instrumentation/kafka.ts

@@ -0,0 +1,360 @@
+import { Context } from '../core/context';
+import { SenzorOptions } from '../core/types';
+import { hookRequire } from './hook';
+import { patchMethod } from './patch';
+import { runWithCapturedSpan, startCapturedSpan } from './span';
+import { generateTraceparent, parseTraceparent } from '../utils/traceContext';
+
+// ---------------------------------------------------------------------------
+// Kafka (kafkajs) Instrumentation
+//
+// Instruments the kafkajs library:
+//   - Producer: send(), sendBatch() — outbound publish spans
+//   - Consumer: run() — wraps eachMessage/eachBatch callbacks with spans
+//   - Context propagation via message headers (traceparent, x-senzor-*)
+//
+// Follows OTel messaging semantic conventions:
+//   messaging.system = kafka
+//   messaging.destination.name = topic
+//   messaging.operation.name = publish | receive
+//   messaging.kafka.consumer.group
+//   messaging.kafka.message.offset
+//   messaging.batch.message_count
+// ---------------------------------------------------------------------------
+
+const TRACEPARENT_KEY = 'traceparent';
+const SENZOR_TRACE_KEY = 'x-senzor-trace-id';
+const SENZOR_SPAN_KEY = 'x-senzor-parent-span-id';
+
+/** Inject trace context into Kafka message headers. */
+const injectHeaders = (
+  headers: Record<string, any> | undefined,
+  traceId: string,
+  spanId: string
+): Record<string, any> => {
+  const h = headers ? { ...headers } : {};
+  h[TRACEPARENT_KEY] = Buffer.from(generateTraceparent(traceId, spanId));
+  h[SENZOR_TRACE_KEY] = Buffer.from(traceId);
+  h[SENZOR_SPAN_KEY] = Buffer.from(spanId);
+  return h;
+};
+
+/** Extract trace context from incoming Kafka message headers. */
+const extractHeaders = (
+  headers: Record<string, any> | undefined
+): { traceId?: string; parentSpanId?: string } => {
+  if (!headers) return {};
+
+  try {
+    const tp = headers[TRACEPARENT_KEY];
+    if (tp) {
+      const tpStr = Buffer.isBuffer(tp) ? tp.toString() : String(tp);
+      const parsed = parseTraceparent(tpStr);
+      if (parsed) return parsed;
+    }
+
+    const traceId = headers[SENZOR_TRACE_KEY];
+    const spanId = headers[SENZOR_SPAN_KEY];
+    return {
+      traceId: traceId ? (Buffer.isBuffer(traceId) ? traceId.toString() : String(traceId)) : undefined,
+      parentSpanId: spanId ? (Buffer.isBuffer(spanId) ? spanId.toString() : String(spanId)) : undefined,
+    };
+  } catch {
+    return {};
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Producer patching
+// ---------------------------------------------------------------------------
+
+const patchProducer = (producer: any, options?: SenzorOptions) => {
+  // send({ topic, messages, ... })
+  patchMethod(
+    producer,
+    'send',
+    'senzor.kafka.producer.send',
+    (original) =>
+      function patchedSend(this: any, payload: any) {
+        const trace = Context.current();
+        if (!trace) return original.call(this, payload);
+
+        const topic = payload?.topic || 'unknown';
+        const messageCount = payload?.messages?.length || 0;
+
+        const span = startCapturedSpan(
+          `Kafka publish ${topic}`,
+          'messaging',
+          {
+            'messaging.system': 'kafka',
+            'messaging.destination.name': topic,
+            'messaging.operation.name': 'publish',
+            'messaging.batch.message_count': messageCount,
+          },
+          options
+        );
+
+        if (!span) return original.call(this, payload);
+
+        // Inject trace context into each message's headers
+        if (payload?.messages && Array.isArray(payload.messages)) {
+          payload = {
+            ...payload,
+            messages: payload.messages.map((msg: any) => ({
+              ...msg,
+              headers: injectHeaders(msg.headers, trace.id, span.spanId),
+            })),
+          };
+        }
+
+        return runWithCapturedSpan(span, () => {
+          const result = original.call(this, payload);
+
+          if (result && typeof result.then === 'function') {
+            return result.then(
+              (res: any) => {
+                span.end(0, {
+                  'messaging.kafka.partitions': Array.isArray(res)
+                    ? res.map((r: any) => r.partition).join(',')
+                    : undefined,
+                });
+                return res;
+              },
+              (error: any) => {
+                span.end(500, {
+                  'error.message': error?.message,
+                  'error.type': error?.name || 'KafkaError',
+                });
+                throw error;
+              }
+            );
+          }
+
+          span.end(0);
+          return result;
+        });
+      }
+  );
+
+  // sendBatch({ topicMessages: [{ topic, messages }], ... })
+  patchMethod(
+    producer,
+    'sendBatch',
+    'senzor.kafka.producer.sendBatch',
+    (original) =>
+      function patchedSendBatch(this: any, payload: any) {
+        const trace = Context.current();
+        if (!trace) return original.call(this, payload);
+
+        const topicMessages = payload?.topicMessages || [];
+        const topics = topicMessages.map((tm: any) => tm.topic).join(',');
+        const totalMessages = topicMessages.reduce(
+          (sum: number, tm: any) => sum + (tm.messages?.length || 0),
+          0
+        );
+
+        const span = startCapturedSpan(
+          `Kafka publishBatch ${topics}`,
+          'messaging',
+          {
+            'messaging.system': 'kafka',
+            'messaging.destination.name': topics,
+            'messaging.operation.name': 'publish',
+            'messaging.batch.message_count': totalMessages,
+            'messaging.kafka.batch_topic_count': topicMessages.length,
+          },
+          options
+        );
+
+        if (!span) return original.call(this, payload);
+
+        // Inject trace context into all messages
+        if (topicMessages.length > 0) {
+          payload = {
+            ...payload,
+            topicMessages: topicMessages.map((tm: any) => ({
+              ...tm,
+              messages: (tm.messages || []).map((msg: any) => ({
+                ...msg,
+                headers: injectHeaders(msg.headers, trace.id, span.spanId),
+              })),
+            })),
+          };
+        }
+
+        return runWithCapturedSpan(span, () => {
+          const result = original.call(this, payload);
+
+          if (result && typeof result.then === 'function') {
+            return result.then(
+              (res: any) => {
+                span.end(0);
+                return res;
+              },
+              (error: any) => {
+                span.end(500, {
+                  'error.message': error?.message,
+                  'error.type': error?.name || 'KafkaError',
+                });
+                throw error;
+              }
+            );
+          }
+
+          span.end(0);
+          return result;
+        });
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Consumer patching
+// ---------------------------------------------------------------------------
+
+const patchConsumer = (consumer: any, options?: SenzorOptions) => {
+  patchMethod(
+    consumer,
+    'run',
+    'senzor.kafka.consumer.run',
+    (original) =>
+      function patchedRun(this: any, config: any) {
+        if (!config) return original.call(this, config);
+
+        const wrappedConfig = { ...config };
+
+        // Wrap eachMessage
+        if (typeof config.eachMessage === 'function') {
+          const originalHandler = config.eachMessage;
+          wrappedConfig.eachMessage = async (payload: any) => {
+            const { topic, partition, message } = payload;
+            const parentCtx = extractHeaders(message?.headers);
+
+            const span = startCapturedSpan(
+              `Kafka receive ${topic}`,
+              'messaging',
+              {
+                'messaging.system': 'kafka',
+                'messaging.destination.name': topic,
+                'messaging.operation.name': 'receive',
+                'messaging.kafka.partition': partition,
+                'messaging.kafka.message.offset': message?.offset,
+                'messaging.kafka.message.key': message?.key?.toString(),
+                ...(parentCtx.traceId ? { 'messaging.parent_trace_id': parentCtx.traceId } : {}),
+              },
+              options
+            );
+
+            if (!span) return originalHandler(payload);
+
+            return runWithCapturedSpan(span, async () => {
+              try {
+                const result = await originalHandler(payload);
+                span.end(0);
+                return result;
+              } catch (error: any) {
+                span.end(500, {
+                  'error.message': error?.message,
+                  'error.type': error?.name || 'Error',
+                });
+                throw error;
+              }
+            });
+          };
+        }
+
+        // Wrap eachBatch
+        if (typeof config.eachBatch === 'function') {
+          const originalBatchHandler = config.eachBatch;
+          wrappedConfig.eachBatch = async (payload: any) => {
+            const { batch } = payload;
+            const topic = batch?.topic || 'unknown';
+            const messageCount = batch?.messages?.length || 0;
+
+            const span = startCapturedSpan(
+              `Kafka receiveBatch ${topic}`,
+              'messaging',
+              {
+                'messaging.system': 'kafka',
+                'messaging.destination.name': topic,
+                'messaging.operation.name': 'receive',
+                'messaging.kafka.partition': batch?.partition,
+                'messaging.batch.message_count': messageCount,
+                'messaging.kafka.first_offset': batch?.messages?.[0]?.offset,
+                'messaging.kafka.last_offset': batch?.messages?.[messageCount - 1]?.offset,
+              },
+              options
+            );
+
+            if (!span) return originalBatchHandler(payload);
+
+            return runWithCapturedSpan(span, async () => {
+              try {
+                const result = await originalBatchHandler(payload);
+                span.end(0);
+                return result;
+              } catch (error: any) {
+                span.end(500, {
+                  'error.message': error?.message,
+                  'error.type': error?.name || 'Error',
+                });
+                throw error;
+              }
+            });
+          };
+        }
+
+        return original.call(this, wrappedConfig);
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Kafka class patching (wraps factory methods)
+// ---------------------------------------------------------------------------
+
+const patchKafkaClass = (kafkaModule: any, options?: SenzorOptions) => {
+  const KafkaClass = kafkaModule?.Kafka;
+  if (!KafkaClass?.prototype) return;
+
+  // Wrap producer() factory
+  patchMethod(
+    KafkaClass.prototype,
+    'producer',
+    'senzor.kafka.producer',
+    (original) =>
+      function patchedProducerFactory(this: any, ...args: any[]) {
+        const producer = original.apply(this, args);
+        if (producer) patchProducer(producer, options);
+        return producer;
+      }
+  );
+
+  // Wrap consumer() factory
+  patchMethod(
+    KafkaClass.prototype,
+    'consumer',
+    'senzor.kafka.consumer',
+    (original) =>
+      function patchedConsumerFactory(this: any, ...args: any[]) {
+        const consumer = original.apply(this, args);
+        if (consumer) patchConsumer(consumer, options);
+        return consumer;
+      }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const instrumentKafka = (options?: SenzorOptions) => {
+  hookRequire('kafkajs', (exports: any) => {
+    patchKafkaClass(exports, options);
+
+    // Also handle default export
+    if (exports?.default?.Kafka) {
+      patchKafkaClass(exports.default, options);
+    }
+  });
+};