@onebun/metrics 0.1.0

package/src/middleware.ts

@@ -0,0 +1,186 @@
+import { Effect } from 'effect';
+
+import type { HttpMetricsData } from './types';
+
+import { HttpStatusCode } from '@onebun/requests';
+
+import { MetricsService } from './metrics.service';
+
+/**
+ * Metrics middleware for automatic HTTP metrics collection
+ */
+export class MetricsMiddleware {
+  constructor(private metricsService: MetricsService) {}
+
+  /**
+   * Create middleware function for HTTP request metrics
+   */
+  createHttpMetricsMiddleware() {
+    return async (
+      req: Request,
+      context: {
+        controller?: string;
+        action?: string;
+        route?: string;
+      } = {},
+    ): Promise<(response: Response, startTime: number) => void> => {
+      return (response: Response, requestStartTime: number) => {
+        const duration = (Date.now() - requestStartTime) / 1000; // Convert to seconds
+        const url = new URL(req.url);
+
+        const metricsData: HttpMetricsData = {
+          method: req.method,
+          route: context.route || url.pathname,
+          statusCode: response.status,
+          duration,
+          controller: context.controller,
+          action: context.action,
+        };
+
+        this.metricsService.recordHttpRequest(metricsData);
+      };
+    };
+  }
+
+  /**
+   * Wrap controller method with metrics collection
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  wrapControllerMethod<T extends (...args: any[]) => any>(
+    originalMethod: T,
+    controllerName: string,
+    methodName: string,
+    route: string,
+  ): T {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (async (...args: any[]) => {
+      const startTime = Date.now();
+      let statusCode = HttpStatusCode.OK;
+      try {
+        const result = await originalMethod.apply(this, args);
+
+        // If result is a Response, extract status code
+        if (result instanceof Response) {
+          statusCode = result.status;
+        }
+
+        return result;
+      } catch (err) {
+        statusCode = HttpStatusCode.INTERNAL_SERVER_ERROR; // Default error status
+        throw err;
+      } finally {
+        const duration = (Date.now() - startTime) / 1000;
+
+        this.metricsService.recordHttpRequest({
+          method: 'UNKNOWN', // Will be overridden by actual request
+          route,
+          statusCode,
+          duration,
+          controller: controllerName,
+          action: methodName,
+        });
+      }
+    }) as T;
+  }
+}
+
+/**
+ * Decorator for automatic metrics collection on controller methods
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention,@typescript-eslint/no-explicit-any
+export function WithMetrics(route?: string): any {
+  return (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target: any, 
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) => {
+    const originalMethod = descriptor.value;
+    const controllerName = target.constructor.name;
+    const routePath = route || `/${propertyKey}`;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    descriptor.value = function (...args: any[]) {
+      const startTime = Date.now(); 
+
+      try {
+        const result = originalMethod.apply(this, args);
+
+        // Handle both sync and async methods
+        if (result instanceof Promise) {
+          return result
+            .then((res) => {
+              recordMetrics(controllerName, propertyKey, routePath, startTime, HttpStatusCode.OK);
+
+              return res;
+            })
+            .catch((err) => {
+              recordMetrics(
+                controllerName,
+                propertyKey,
+                routePath,
+                startTime,
+                HttpStatusCode.INTERNAL_SERVER_ERROR,
+              );
+              throw err;
+            });
+        } else {
+          recordMetrics(controllerName, propertyKey, routePath, startTime, HttpStatusCode.OK);
+
+          return result;
+        }
+      } catch (err) {
+        recordMetrics(
+          controllerName,
+          propertyKey,
+          routePath,
+          startTime,
+          HttpStatusCode.INTERNAL_SERVER_ERROR,
+        );
+        throw err;
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Helper function to record metrics
+ */
+function recordMetrics(
+  controller: string,
+  action: string,
+  route: string,
+  startTime: number,
+  statusCode: number,
+): void {
+  const duration = (Date.now() - startTime) / 1000;
+
+  // This would ideally get the metrics service from the current context
+  // For now, we'll store this information and let the application handle it
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if (typeof globalThis !== 'undefined' && (globalThis as any).__onebunMetricsService) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const metricsService = (globalThis as any).__onebunMetricsService; 
+    metricsService.recordHttpRequest({
+      method: 'UNKNOWN',
+      route,
+      statusCode,
+      duration,
+      controller,
+      action,
+    });
+  }
+}
+
+/**
+ * Effect-based metrics collection
+ */
+export const recordHttpMetrics = (
+  data: HttpMetricsData,
+): Effect.Effect<void, never, MetricsService> =>
+  Effect.gen(function* () {
+    const metricsService = yield* MetricsService;
+    metricsService.recordHttpRequest(data);
+  });

package/src/types.ts

@@ -0,0 +1,133 @@
+import type { register } from 'prom-client';
+
+/**
+ * Default system metrics collection interval (5 seconds)
+ */
+export const DEFAULT_SYSTEM_METRICS_INTERVAL = 5000;
+
+/**
+ * Default HTTP duration buckets for histogram metrics (in seconds)
+ */
+/* eslint-disable no-magic-numbers -- Standard Prometheus histogram buckets defined in one place */
+export const DEFAULT_HTTP_DURATION_BUCKETS = [
+  0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+];
+/* eslint-enable no-magic-numbers */
+
+/**
+ * Default metrics max age in seconds (10 minutes)
+ */
+export const DEFAULT_METRICS_MAX_AGE_SECONDS = 600;
+
+/**
+ * Metrics module configuration options
+ */
+export interface MetricsOptions {
+  /**
+   * Enable/disable metrics collection
+   * @defaultValue true
+   */
+  enabled?: boolean;
+
+  /**
+   * HTTP path for exposing metrics endpoint
+   * @defaultValue '/metrics'
+   */
+  path?: string;
+
+  /**
+   * Default labels to add to all metrics
+   */
+  defaultLabels?: Record<string, string>;
+
+  /**
+   * Enable automatic HTTP metrics collection
+   * @defaultValue true
+   */
+  collectHttpMetrics?: boolean;
+
+  /**
+   * Enable automatic system metrics collection
+   * @defaultValue true
+   */
+  collectSystemMetrics?: boolean;
+
+  /**
+   * Enable GC metrics collection
+   * @defaultValue true
+   */
+  collectGcMetrics?: boolean;
+
+  /**
+   * Collection interval for system metrics in milliseconds
+   * @defaultValue 5000
+   */
+  systemMetricsInterval?: number;
+
+  /**
+   * Custom prefix for all metrics
+   * @defaultValue 'onebun_'
+   */
+  prefix?: string;
+
+  /**
+   * Buckets for HTTP request duration histogram
+   * @defaultValue [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+   */
+  httpDurationBuckets?: number[];
+}
+
+/**
+ * HTTP metrics data
+ */
+export interface HttpMetricsData {
+  method: string;
+  route: string;
+  statusCode: number;
+  duration: number;
+  controller?: string;
+  action?: string;
+}
+
+/**
+ * System metrics data
+ */
+export interface SystemMetricsData {
+  memoryUsage: NodeJS.MemoryUsage;
+  cpuUsage: NodeJS.CpuUsage;
+  uptime: number;
+}
+
+/**
+ * Metrics registry interface
+ */
+export interface MetricsRegistry {
+  getMetrics(): Promise<string>;
+  getContentType(): string;
+  clear(): void;
+  register: typeof register;
+}
+
+/**
+ * Custom metric types
+ */
+export enum MetricType {
+  COUNTER = 'counter',
+  GAUGE = 'gauge',
+  HISTOGRAM = 'histogram',
+  SUMMARY = 'summary',
+}
+
+/**
+ * Custom metric configuration
+ */
+export interface CustomMetricConfig {
+  name: string;
+  help: string;
+  type: MetricType;
+  labelNames?: string[];
+  buckets?: number[]; // for histogram
+  percentiles?: number[]; // for summary
+  maxAgeSeconds?: number; // for summary
+  ageBuckets?: number; // for summary
+}