autotel 2.1.0

package/src/metric.ts

@@ -0,0 +1,434 @@
+/**
+ * Metrics API for OpenTelemetry
+ *
+ * Track business metrics for OpenTelemetry (Prometheus/Grafana).
+ * For business people who think in metrics.
+ *
+ * @example Track business metrics
+ * ```typescript
+ * const metrics = new Metric('checkout')
+ *
+ * // Track events as metrics
+ * metrics.trackEvent('order.completed', {
+ *   amount: 99.99,
+ *   currency: 'USD'
+ * })
+ *
+ * // Track conversion funnels
+ * metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 })
+ * metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 })
+ *
+ * // Track outcomes
+ * metrics.trackOutcome('payment.process', 'success', { amount: 99.99 })
+ * metrics.trackOutcome('payment.process', 'failure', { error: 'insufficient_funds' })
+ *
+ * // Track values
+ * metrics.trackValue('revenue', 149.99, { currency: 'USD' })
+ * ```
+ */
+
+import {
+  type Counter,
+  type Histogram,
+  type Attributes,
+} from '@opentelemetry/api';
+import { getConfig } from './config';
+import { type Logger } from './logger';
+import {
+  type EventAttributes,
+  type FunnelStatus,
+  type OutcomeStatus,
+} from './event-subscriber';
+import { type MetricsCollector } from './metric-testing';
+
+// Re-export types for convenience
+export type {
+  EventAttributes,
+  FunnelStatus,
+  OutcomeStatus,
+} from './event-subscriber';
+
+/**
+ * Metrics class for tracking business metrics in OpenTelemetry
+ *
+ * Track critical business indicators such as:
+ * - User events (signups, purchases, feature usage) as metrics
+ * - Conversion funnels (signup → activation → purchase)
+ * - Business outcomes (success/failure rates)
+ * - Value metrics (revenue, counts, etc.)
+ *
+ * All metrics are sent to OpenTelemetry (OTLP/Prometheus/Grafana).
+ */
+/**
+ * Metric configuration for customizing metric names and descriptions
+ */
+export interface MetricConfig {
+  /** Metric name (e.g., 'metrics.events' or 'custom.events') */
+  name?: string;
+  /** Metric description */
+  description?: string;
+  /** Metric unit (default: '1') */
+  unit?: string;
+}
+
+/**
+ * Metrics options
+ */
+export interface MetricsOptions {
+  /** Optional logger for audit trail */
+  logger?: Logger;
+  /** Optional collector for testing (captures metrics in memory) */
+  collector?: MetricsCollector;
+
+  /**
+   * Namespace for metrics (default: 'metrics')
+   * Results in metrics like: {serviceName}.{namespace}.events
+   */
+  namespace?: string;
+
+  /**
+   * Custom metric configurations
+   * Override metric names, descriptions, and units
+   */
+  metrics?: {
+    events?: MetricConfig;
+    funnel?: MetricConfig;
+    outcomes?: MetricConfig;
+    value?: MetricConfig;
+  };
+}
+
+export class Metric {
+  private serviceName: string;
+  private eventCounter: Counter;
+  private funnelCounter: Counter;
+  private outcomeCounter: Counter;
+  private valueHistogram: Histogram;
+  private logger?: Logger;
+  private collector?: MetricsCollector;
+
+  /**
+   * Create a new Metrics instance
+   *
+   * @param serviceName - Service name for metric namespacing
+   * @param options - Optional configuration (logger, collector, namespace, metrics)
+   *
+   * @example Basic usage (default 'metrics' namespace)
+   * ```typescript
+   * const metrics = new Metric('checkout');
+   * // Creates: checkout.metrics.events, checkout.metrics.funnel, etc.
+   * ```
+   *
+   * @example Custom namespace
+   * ```typescript
+   * const metrics = new Metric('api', { namespace: 'business' });
+   * // Creates: api.business.events, api.business.funnel, etc.
+   * ```
+   *
+   * @example Custom metric names and descriptions
+   * ```typescript
+   * const metrics = new Metric('payments', {
+   *   metrics: {
+   *     outcomes: {
+   *       name: 'payments.transactions',
+   *       description: 'Payment transaction outcomes',
+   *       unit: 'transactions'
+   *     },
+   *     value: {
+   *       name: 'payments.revenue',
+   *       description: 'Payment revenue in USD',
+   *       unit: 'USD'
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  constructor(serviceName: string, options: MetricsOptions = {}) {
+    this.serviceName = serviceName;
+    this.logger = options.logger;
+    this.collector = options.collector;
+
+    const config = getConfig();
+    const meter = config.meter;
+
+    // Default namespace and metric configurations
+    const namespace = options.namespace || 'metrics';
+    const metricsConfig = options.metrics || {};
+
+    // Event counter configuration
+    const eventsConfig = metricsConfig.events || {};
+    this.eventCounter = meter.createCounter(
+      eventsConfig.name || `${serviceName}.${namespace}.events`,
+      {
+        description: eventsConfig.description || 'Count of business events',
+        unit: eventsConfig.unit || '1',
+      },
+    );
+
+    // Funnel counter configuration
+    const funnelConfig = metricsConfig.funnel || {};
+    this.funnelCounter = meter.createCounter(
+      funnelConfig.name || `${serviceName}.${namespace}.funnel`,
+      {
+        description: funnelConfig.description || 'Conversion funnel tracking',
+        unit: funnelConfig.unit || '1',
+      },
+    );
+
+    // Outcome counter configuration
+    const outcomesConfig = metricsConfig.outcomes || {};
+    this.outcomeCounter = meter.createCounter(
+      outcomesConfig.name || `${serviceName}.${namespace}.outcomes`,
+      {
+        description:
+          outcomesConfig.description || 'Outcome tracking (success/failure)',
+        unit: outcomesConfig.unit || '1',
+      },
+    );
+
+    // Value histogram configuration
+    const valueConfig = metricsConfig.value || {};
+    this.valueHistogram = meter.createHistogram(
+      valueConfig.name || `${serviceName}.${namespace}.value`,
+      {
+        description:
+          valueConfig.description || 'Value metrics (revenue, counts, etc.)',
+        unit: valueConfig.unit || '1',
+      },
+    );
+  }
+
+  /**
+   * Track a business event as a metric
+   *
+   * Use this for tracking user actions, business events, product usage as metrics:
+   * - "user.signup"
+   * - "order.completed"
+   * - "feature.used"
+   *
+   * @example
+   * ```typescript
+   * // Track user signup as metric
+   * metrics.trackEvent('user.signup', {
+   *   userId: '123',
+   *   plan: 'pro'
+   * })
+   *
+   * // Track order as metric
+   * metrics.trackEvent('order.completed', {
+   *   orderId: 'ord_123',
+   *   amount: 99.99
+   * })
+   * ```
+   */
+  trackEvent(eventName: string, attributes?: EventAttributes): void {
+    const attrs: Attributes = {
+      service: this.serviceName,
+      event: eventName,
+      ...attributes,
+    };
+
+    this.eventCounter.add(1, attrs);
+
+    this.logger?.info('Metric event tracked', {
+      event: eventName,
+      attributes,
+    });
+
+    // Record for testing
+    this.collector?.recordEvent({
+      event: eventName,
+      attributes,
+      service: this.serviceName,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Track conversion funnel steps as metrics
+   *
+   * Monitor where users drop off in multi-step processes.
+   *
+   * @example
+   * ```typescript
+   * // Track signup funnel
+   * metrics.trackFunnelStep('signup', 'started', { userId: '123' })
+   * metrics.trackFunnelStep('signup', 'email_verified', { userId: '123' })
+   * metrics.trackFunnelStep('signup', 'completed', { userId: '123' })
+   *
+   * // Track checkout flow
+   * metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 })
+   * metrics.trackFunnelStep('checkout', 'payment_info', { cartValue: 99.99 })
+   * metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 })
+   * ```
+   */
+  trackFunnelStep(
+    funnelName: string,
+    status: FunnelStatus,
+    attributes?: EventAttributes,
+  ): void {
+    const attrs: Attributes = {
+      service: this.serviceName,
+      funnel: funnelName,
+      status,
+      ...attributes,
+    };
+
+    this.funnelCounter.add(1, attrs);
+
+    this.logger?.info('Funnel step tracked', {
+      funnel: funnelName,
+      status,
+      attributes,
+    });
+
+    // Record for testing
+    this.collector?.recordFunnelStep({
+      funnel: funnelName,
+      status,
+      attributes,
+      service: this.serviceName,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Track outcomes (success/failure/partial) as metrics
+   *
+   * Monitor success rates of critical operations.
+   *
+   * @example
+   * ```typescript
+   * // Track email delivery
+   * metrics.trackOutcome('email.delivery', 'success', {
+   *   recipientType: 'user',
+   *   emailType: 'welcome'
+   * })
+   *
+   * metrics.trackOutcome('email.delivery', 'failure', {
+   *   recipientType: 'user',
+   *   errorCode: 'invalid_email'
+   * })
+   *
+   * // Track payment processing
+   * metrics.trackOutcome('payment.process', 'success', { amount: 99.99 })
+   * metrics.trackOutcome('payment.process', 'failure', { error: 'insufficient_funds' })
+   * ```
+   */
+  trackOutcome(
+    operationName: string,
+    status: OutcomeStatus,
+    attributes?: EventAttributes,
+  ): void {
+    const attrs: Attributes = {
+      service: this.serviceName,
+      operation: operationName,
+      status,
+      ...attributes,
+    };
+
+    this.outcomeCounter.add(1, attrs);
+
+    this.logger?.info('Outcome tracked', {
+      operation: operationName,
+      status,
+      attributes,
+    });
+
+    // Record for testing
+    this.collector?.recordOutcome({
+      operation: operationName,
+      status,
+      attributes,
+      service: this.serviceName,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Track value metrics
+   *
+   * Record numerical values like revenue, transaction amounts,
+   * item counts, processing times, engagement scores, etc.
+   *
+   * @example
+   * ```typescript
+   * // Track revenue
+   * metrics.trackValue('order.revenue', 149.99, {
+   *   currency: 'USD',
+   *   productCategory: 'electronics'
+   * })
+   *
+   * // Track items per cart
+   * metrics.trackValue('cart.item_count', 5, {
+   *   userId: '123'
+   * })
+   *
+   * // Track processing time
+   * metrics.trackValue('api.response_time', 250, {
+   *   unit: 'ms',
+   *   endpoint: '/api/checkout'
+   * })
+   * ```
+   */
+  trackValue(
+    metricName: string,
+    value: number,
+    attributes?: EventAttributes,
+  ): void {
+    const attrs: Attributes = {
+      service: this.serviceName,
+      metric: metricName,
+      ...attributes,
+    };
+
+    this.valueHistogram.record(value, attrs);
+
+    this.logger?.debug('Value metric tracked', {
+      metric: metricName,
+      value,
+      attributes,
+    });
+
+    // Record for testing
+    this.collector?.recordValue({
+      metric: metricName,
+      value,
+      attributes,
+      service: this.serviceName,
+      timestamp: Date.now(),
+    });
+  }
+}
+
+/**
+ * Global metrics instances (singleton pattern)
+ */
+const metricsInstances = new Map<string, Metric>();
+
+/**
+ * Get or create a Metrics instance for a service
+ *
+ * @param serviceName - Service name for metric namespacing
+ * @param logger - Optional logger
+ * @returns Metrics instance
+ *
+ * @example
+ * ```typescript
+ * const metrics = getMetrics('checkout')
+ * metrics.trackEvent('order.completed', { orderId: '123' })
+ * ```
+ */
+export function getMetrics(serviceName: string, logger?: Logger): Metric {
+  if (!metricsInstances.has(serviceName)) {
+    metricsInstances.set(serviceName, new Metric(serviceName, { logger }));
+  }
+  return metricsInstances.get(serviceName)!;
+}
+
+/**
+ * Reset all metrics instances (mainly for testing)
+ */
+export function resetMetrics(): void {
+  metricsInstances.clear();
+}

package/src/metrics.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { Metric, getMetrics, resetMetrics } from './metric';
+import { type ILogger } from './logger';
+import { init } from './init';
+import { configure } from './config';
+
+describe('Metrics', () => {
+  let mockLogger: ILogger;
+
+  beforeEach(() => {
+    resetMetrics();
+    init({ service: 'test-app' });
+    configure({
+      meterName: 'test',
+    });
+    mockLogger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    };
+  });
+
+  describe('trackEvent', () => {
+    it('should track business events as metrics', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackEvent('order.completed', {
+        orderId: '123',
+        amount: 99.99,
+      });
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Metric event tracked', {
+        event: 'order.completed',
+        attributes: { orderId: '123', amount: 99.99 },
+      });
+    });
+
+    it('should track events without attributes', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackEvent('user.login');
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Metric event tracked', {
+        event: 'user.login',
+        attributes: undefined,
+      });
+    });
+  });
+
+  describe('trackFunnelStep', () => {
+    it('should track funnel progression as metrics', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 });
+      metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 });
+
+      expect(mockLogger.info).toHaveBeenCalledTimes(2);
+      expect(mockLogger.info).toHaveBeenCalledWith('Funnel step tracked', {
+        funnel: 'checkout',
+        status: 'started',
+        attributes: { cartValue: 99.99 },
+      });
+    });
+
+    it('should track funnel abandonment', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackFunnelStep('checkout', 'abandoned', { reason: 'timeout' });
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Funnel step tracked', {
+        funnel: 'checkout',
+        status: 'abandoned',
+        attributes: { reason: 'timeout' },
+      });
+    });
+  });
+
+  describe('trackOutcome', () => {
+    it('should track successful outcomes as metrics', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackOutcome('payment.process', 'success', {
+        amount: 99.99,
+      });
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Outcome tracked', {
+        operation: 'payment.process',
+        status: 'success',
+        attributes: { amount: 99.99 },
+      });
+    });
+
+    it('should track failed outcomes', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackOutcome('payment.process', 'failure', {
+        error: 'insufficient_funds',
+      });
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Outcome tracked', {
+        operation: 'payment.process',
+        status: 'failure',
+        attributes: { error: 'insufficient_funds' },
+      });
+    });
+
+    it('should track partial outcomes', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackOutcome('batch.process', 'partial', {
+        successCount: 8,
+        failureCount: 2,
+      });
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Outcome tracked', {
+        operation: 'batch.process',
+        status: 'partial',
+        attributes: { successCount: 8, failureCount: 2 },
+      });
+    });
+  });
+
+  describe('trackValue', () => {
+    it('should track revenue metrics', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackValue('order.revenue', 149.99, {
+        currency: 'USD',
+        productCategory: 'electronics',
+      });
+
+      expect(mockLogger.debug).toHaveBeenCalledWith('Value metric tracked', {
+        metric: 'order.revenue',
+        value: 149.99,
+        attributes: { currency: 'USD', productCategory: 'electronics' },
+      });
+    });
+
+    it('should track processing time', () => {
+      const metrics = new Metric('test-service', { logger: mockLogger });
+
+      metrics.trackValue('application.processing_time', 2500, {
+        unit: 'ms',
+      });
+
+      expect(mockLogger.debug).toHaveBeenCalledWith('Value metric tracked', {
+        metric: 'application.processing_time',
+        value: 2500,
+        attributes: { unit: 'ms' },
+      });
+    });
+  });
+
+  describe('getMetrics', () => {
+    it('should return singleton instance', () => {
+      const metrics1 = getMetrics('test-service');
+      const metrics2 = getMetrics('test-service');
+
+      expect(metrics1).toBe(metrics2);
+    });
+
+    it('should return different instances for different services', () => {
+      const metrics1 = getMetrics('service-1');
+      const metrics2 = getMetrics('service-2');
+
+      expect(metrics1).not.toBe(metrics2);
+    });
+
+    it('should reset instances', () => {
+      const metrics1 = getMetrics('test-service');
+      resetMetrics();
+      const metrics2 = getMetrics('test-service');
+
+      expect(metrics1).not.toBe(metrics2);
+    });
+  });
+
+  describe('real-world usage example', () => {
+    it('should track checkout flow', () => {
+      const metrics = new Metric('checkout', { logger: mockLogger });
+
+      // User starts checkout
+      metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 });
+
+      // Order completed
+      metrics.trackEvent('order.completed', {
+        orderId: 'ord_123',
+        amount: 99.99,
+      });
+      metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 });
+
+      // Payment processed successfully
+      metrics.trackOutcome('payment.process', 'success', {
+        amount: 99.99,
+      });
+
+      // Track revenue
+      metrics.trackValue('revenue', 99.99, { currency: 'USD' });
+
+      expect(mockLogger.info).toHaveBeenCalledTimes(4);
+      expect(mockLogger.debug).toHaveBeenCalledTimes(1);
+    });
+  });
+});