autotel 2.1.0

package/src/logger.ts

@@ -0,0 +1,246 @@
+/**
+ * Logger types and utilities for autotel
+ *
+ * **Recommended Approach:** Bring your own logger (Pino, Winston, Bunyan, etc.)
+ *
+ * Simply create your logger instance and pass it to `init()`.
+ * Autotel automatically instruments Pino and Winston to:
+ * - Inject trace context (traceId, spanId) into log records
+ * - Record errors in the active span
+ * - Bridge logs to OpenTelemetry Logs API for OTLP export
+ *
+ * @example Using Pino (recommended, auto-instrumented)
+ * ```typescript
+ * import pino from 'pino';  // npm install pino
+ * import { init } from 'autotel';
+ *
+ * const logger = pino({ level: 'info' });
+ * init({ service: 'my-app', logger });
+ *
+ * // Logs automatically include traceId/spanId and export via OTLP!
+ * logger.info('User created', { userId: '123' });
+ * ```
+ *
+ * @example Using Winston (auto-instrumented)
+ * ```typescript
+ * import winston from 'winston';  // npm install winston
+ * import { init } from 'autotel';
+ *
+ * const logger = winston.createLogger({
+ *   level: 'info',
+ *   format: winston.format.json(),
+ *   transports: [new winston.transports.Console()]
+ * });
+ * init({ service: 'my-app', logger });
+ * ```
+ *
+ * @example Using Bunyan (manual instrumentation)
+ * ```typescript
+ * import bunyan from 'bunyan';  // npm install bunyan @opentelemetry/instrumentation-bunyan
+ * import { init } from 'autotel';
+ * import { BunyanInstrumentation } from '@opentelemetry/instrumentation-bunyan';
+ *
+ * const logger = bunyan.createLogger({ name: 'my-app' });
+ * init({
+ *   service: 'my-app',
+ *   logger,
+ *   instrumentations: [new BunyanInstrumentation()]
+ * });
+ * ```
+ *
+ * @example Custom logger (any logger with 4 methods)
+ * ```typescript
+ * const logger = {
+ *   info: (msg, extra) => console.log(msg, extra),
+ *   warn: (msg, extra) => console.warn(msg, extra),
+ *   error: (msg, err, extra) => console.error(msg, err, extra),
+ *   debug: (msg, extra) => console.debug(msg, extra),
+ * };
+ * init({ service: 'my-app', logger });
+ * ```
+ */
+
+import { SpanStatusCode } from '@opentelemetry/api';
+import { getConfig } from './config';
+
+// ============================================================================
+// Logger Types
+// ============================================================================
+
+/**
+ * Log level constants
+ */
+export const LOG_LEVEL = {
+  DEBUG: 'debug',
+  INFO: 'info',
+  WARN: 'warn',
+  ERROR: 'error',
+} as const;
+
+export type LogLevel = (typeof LOG_LEVEL)[keyof typeof LOG_LEVEL];
+
+/**
+ * Logger configuration (for reference - not needed with BYOL approach)
+ */
+export interface LoggerConfig {
+  service: string;
+  level?: LogLevel;
+  pretty?: boolean;
+  redact?: string[] | false;
+}
+
+/**
+ * Simple logger interface - minimal contract for any logger
+ *
+ * Bring your own Pino, Winston, or any logger with these 4 methods.
+ * Autotel automatically instruments Pino and Winston loggers to:
+ * - Inject trace context (traceId, spanId) into log records
+ * - Record errors in the active span
+ * - Bridge logs to OpenTelemetry Logs API for OTLP export
+ *
+ * @example Using Pino
+ * ```typescript
+ * import pino from 'pino';
+ * const logger = pino({ level: 'info' });
+ * init({ service: 'my-app', logger });
+ * ```
+ *
+ * @example Using Winston
+ * ```typescript
+ * import winston from 'winston';
+ * const logger = winston.createLogger({ level: 'info' });
+ * init({ service: 'my-app', logger });
+ * ```
+ */
+export interface Logger {
+  info(message: string, extra?: Record<string, unknown>): void;
+  warn(message: string, extra?: Record<string, unknown>): void;
+  error(message: string, error?: Error, extra?: Record<string, unknown>): void;
+  debug(message: string, extra?: Record<string, unknown>): void;
+}
+
+/**
+ * Alias for Logger interface (backwards compatibility)
+ * @deprecated Use Logger instead
+ */
+export type ILogger = Logger;
+
+/**
+ * Pino logger type - re-exported for convenience
+ *
+ * Note: This is a type-only export. To use Pino, install it as a peer dependency:
+ * `npm install pino`
+ */
+export type { Logger as PinoLogger } from 'pino';
+
+// ============================================================================
+// LoggedOperation Decorator
+// ============================================================================
+
+export interface LoggedOperationOptions {
+  /** Operation name for tracing (e.g., 'user.createUser') */
+  operationName: string;
+}
+
+/**
+ * TS5+ Standard Decorator for logging and tracing operations
+ * Uses TC39 Stage 3 decorator syntax
+ *
+ * This is the traditional per-method decorator approach.
+ * For zero-boilerplate solution, see @Instrumented class decorator.
+ *
+ * @example
+ * // Simple usage
+ * class OrderService {
+ *   constructor(private readonly deps: { log: Logger }) {}
+ *
+ *   @LoggedOperation('order.create')
+ *   async createOrder(data: CreateOrderData) {
+ *     this.deps.logger.info('Creating order', data)
+ *   }
+ * }
+ *
+ * // Advanced usage (future-proof for options)
+ * @LoggedOperation({ operationName: 'order.create' })
+ * async createOrder(data: CreateOrderData) { }
+ */
+export function LoggedOperation(
+  operationNameOrOptions: string | LoggedOperationOptions,
+) {
+  const operationName =
+    typeof operationNameOrOptions === 'string'
+      ? operationNameOrOptions
+      : operationNameOrOptions.operationName;
+
+  return function <This, Args extends unknown[], Return>(
+    originalMethod: (this: This, ...args: Args) => Promise<Return>,
+    context: ClassMethodDecoratorContext<
+      This,
+      (this: This, ...args: Args) => Promise<Return>
+    >,
+  ) {
+    const methodName = String(context.name);
+
+    return async function (this: This, ...args: Args): Promise<Return> {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const log = (this as any).deps?.log;
+      const startTime = performance.now();
+
+      const config = getConfig();
+      const tracer = config.tracer;
+
+      return tracer.startActiveSpan(operationName, async (span) => {
+        try {
+          log?.info('Operation started', {
+            operation: operationName,
+            method: methodName,
+            args,
+          });
+
+          const result = await originalMethod.apply(this, args);
+
+          const duration = performance.now() - startTime;
+          log?.info('Operation completed', {
+            operation: operationName,
+            method: methodName,
+            duration,
+          });
+
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.setAttributes({
+            'operation.name': operationName,
+            'operation.method': methodName,
+            'operation.duration': duration,
+            'operation.success': true,
+          });
+
+          return result;
+        } catch (error) {
+          const duration = performance.now() - startTime;
+          log?.error(
+            'Operation failed',
+            error instanceof Error ? error : undefined,
+            { operation: operationName, method: methodName, duration },
+          );
+
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : 'Unknown error',
+          });
+          span.setAttributes({
+            'operation.name': operationName,
+            'operation.method': methodName,
+            'operation.duration': duration,
+            'operation.success': false,
+            'error.type':
+              error instanceof Error ? error.constructor.name : 'Unknown',
+          });
+
+          throw error;
+        } finally {
+          span.end();
+        }
+      });
+    };
+  };
+}

package/src/metric-helpers.ts

@@ -0,0 +1,47 @@
+import type {
+  Counter,
+  Histogram,
+  Meter,
+  ObservableGauge,
+  UpDownCounter,
+} from '@opentelemetry/api';
+import { getConfig } from './config';
+
+function getActiveMeter(): Meter {
+  const config = getConfig();
+  return config.meter;
+}
+
+export function getMeter(): Meter {
+  return getActiveMeter();
+}
+
+type CounterOptions = Parameters<Meter['createCounter']>[1];
+type HistogramOptions = Parameters<Meter['createHistogram']>[1];
+type UpDownCounterOptions = Parameters<Meter['createUpDownCounter']>[1];
+type ObservableGaugeOptions = Parameters<Meter['createObservableGauge']>[1];
+
+export function createCounter(name: string, options?: CounterOptions): Counter {
+  return getActiveMeter().createCounter(name, options);
+}
+
+export function createHistogram(
+  name: string,
+  options?: HistogramOptions,
+): Histogram {
+  return getActiveMeter().createHistogram(name, options);
+}
+
+export function createUpDownCounter(
+  name: string,
+  options?: UpDownCounterOptions,
+): UpDownCounter {
+  return getActiveMeter().createUpDownCounter(name, options);
+}
+
+export function createObservableGauge(
+  name: string,
+  options?: ObservableGaugeOptions,
+): ObservableGauge {
+  return getActiveMeter().createObservableGauge(name, options);
+}

package/src/metric-testing.ts

@@ -0,0 +1,197 @@
+/**
+ * Testing utilities for Metrics
+ *
+ * Provides in-memory collection of metrics for testing purposes.
+ */
+
+import type {
+  EventAttributes,
+  FunnelStatus,
+  OutcomeStatus,
+} from './event-subscriber';
+
+export interface MetricsEvent {
+  event: string;
+  attributes?: EventAttributes;
+  service: string;
+  timestamp: number;
+}
+
+export interface MetricsFunnelStep {
+  funnel: string;
+  status: FunnelStatus;
+  attributes?: EventAttributes;
+  service: string;
+  timestamp: number;
+}
+
+export interface MetricsOutcome {
+  operation: string;
+  status: OutcomeStatus;
+  attributes?: EventAttributes;
+  service: string;
+  timestamp: number;
+}
+
+export interface MetricsValue {
+  metric: string;
+  value: number;
+  attributes?: EventAttributes;
+  service: string;
+  timestamp: number;
+}
+
+/**
+ * In-memory metrics collector for testing
+ */
+export interface MetricsCollector {
+  /** Get all collected events */
+  getEvents(): MetricsEvent[];
+  /** Get all collected funnel steps */
+  getFunnelSteps(): MetricsFunnelStep[];
+  /** Get all collected outcomes */
+  getOutcomes(): MetricsOutcome[];
+  /** Get all collected values */
+  getValues(): MetricsValue[];
+  /** Clear all collected metrics */
+  clear(): void;
+  /** Record an event (internal use) */
+  recordEvent(event: MetricsEvent): void;
+  /** Record a funnel step (internal use) */
+  recordFunnelStep(step: MetricsFunnelStep): void;
+  /** Record an outcome (internal use) */
+  recordOutcome(outcome: MetricsOutcome): void;
+  /** Record a value (internal use) */
+  recordValue(value: MetricsValue): void;
+}
+
+/**
+ * Create an in-memory metrics collector for testing
+ *
+ * @example
+ * ```typescript
+ * const collector = createMetricsCollector()
+ *
+ * const metrics = new Metric('test-service', { collector })
+ * metrics.trackEvent('order.completed', { orderId: '123' })
+ *
+ * const event =collector.getEvents()
+ * expect(events).toHaveLength(1)
+ * expect(events[0].event).toBe('order.completed')
+ * ```
+ */
+export function createMetricsCollector(): MetricsCollector {
+  const events: MetricsEvent[] = [];
+  const funnelSteps: MetricsFunnelStep[] = [];
+  const outcomes: MetricsOutcome[] = [];
+  const values: MetricsValue[] = [];
+
+  return {
+    getEvents(): MetricsEvent[] {
+      return [...events];
+    },
+
+    getFunnelSteps(): MetricsFunnelStep[] {
+      return [...funnelSteps];
+    },
+
+    getOutcomes(): MetricsOutcome[] {
+      return [...outcomes];
+    },
+
+    getValues(): MetricsValue[] {
+      return [...values];
+    },
+
+    clear(): void {
+      events.length = 0;
+      funnelSteps.length = 0;
+      outcomes.length = 0;
+      values.length = 0;
+    },
+
+    recordEvent(event: MetricsEvent): void {
+      events.push(event);
+    },
+
+    recordFunnelStep(step: MetricsFunnelStep): void {
+      funnelSteps.push(step);
+    },
+
+    recordOutcome(outcome: MetricsOutcome): void {
+      outcomes.push(outcome);
+    },
+
+    recordValue(value: MetricsValue): void {
+      values.push(value);
+    },
+  };
+}
+
+/**
+ * Assert that a metric event was tracked
+ *
+ * @example
+ * ```typescript
+ * assertEventTracked({
+ *   collector,
+ *   eventName: 'order.completed',
+ *   attributes: { orderId: '123' }
+ * })
+ * ```
+ */
+export function assertEventTracked(options: {
+  collector: MetricsCollector;
+  eventName: string;
+  attributes?: Record<string, unknown>;
+}): void {
+  const events = options.collector.getEvents();
+  const matching = events.filter((e) => e.event === options.eventName);
+
+  if (matching.length === 0) {
+    throw new Error(`No events found with name: ${options.eventName}`);
+  }
+
+  if (options.attributes) {
+    const matchingWithAttrs = matching.filter((e) =>
+      Object.entries(options.attributes!).every(
+        ([key, value]) => e.attributes && e.attributes[key] === value,
+      ),
+    );
+
+    if (matchingWithAttrs.length === 0) {
+      throw new Error(
+        `Event ${options.eventName} found but attributes don't match: ${JSON.stringify(options.attributes)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Assert that an outcome was tracked
+ *
+ * @example
+ * ```typescript
+ * assertOutcomeTracked({
+ *   collector,
+ *   operation: 'payment.process',
+ *   status: 'success'
+ * })
+ * ```
+ */
+export function assertOutcomeTracked(options: {
+  collector: MetricsCollector;
+  operation: string;
+  status: 'success' | 'failure' | 'partial';
+}): void {
+  const outcomes = options.collector.getOutcomes();
+  const matching = outcomes.filter(
+    (o) => o.operation === options.operation && o.status === options.status,
+  );
+
+  if (matching.length === 0) {
+    throw new Error(
+      `No outcomes found with operation: ${options.operation} and status: ${options.status}`,
+    );
+  }
+}