@avtechno/sfr 1.0.18 → 2.0.0

package/src/observability/middleware/mq.mts

@@ -0,0 +1,187 @@
+/**
+ * SFR MQ Telemetry Instrumentation
+ * 
+ * Instruments AMQP/RabbitMQ with tracing and metrics.
+ */
+
+import type { Channel, ConsumeMessage, Options } from "amqplib";
+import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+import { get_tracer, with_span, get_trace_context } from "../tracer.mjs";
+import { get_sfr_metrics, record_mq_message } from "../metrics.mjs";
+import { sfr_logger } from "../logger.mjs";
+
+/**
+ * Wraps an MQ message handler with tracing and metrics.
+ * Extracts trace context from message headers for distributed tracing.
+ * 
+ * @param queue - The queue name
+ * @param pattern - The communication pattern (e.g., "Point-to-Point", "Fanout")
+ * @param handler - The original handler function
+ * @returns Instrumented handler function
+ */
+export function wrap_mq_handler(
+  queue: string,
+  pattern: string,
+  handler: (msg: ParsedMessage) => void | Promise<void>
+): (msg: ParsedMessage) => Promise<void> {
+  return async (msg: ParsedMessage) => {
+    const start_time = Date.now();
+    const tracer = get_tracer();
+    const metrics = get_sfr_metrics();
+
+    // Extract trace context from message headers if present
+    const headers = (msg.properties?.headers ?? {}) as Record<string, string>;
+    const parent_context = propagation.extract(context.active(), headers);
+
+    const span = tracer.startSpan(
+      `MQ ${pattern} ${queue}`,
+      {
+        kind: SpanKind.CONSUMER,
+        attributes: {
+          "sfr.protocol": "MQ",
+          "messaging.system": "rabbitmq",
+          "messaging.destination": queue,
+          "messaging.operation": "receive",
+          "messaging.message_id": msg.properties?.messageId ?? "unknown",
+          "messaging.correlation_id": msg.properties?.correlationId ?? "unknown",
+          "sfr.mq.pattern": pattern
+        }
+      },
+      parent_context
+    );
+
+    const ctx = trace.setSpan(parent_context, span);
+
+    // Record received metric
+    if (metrics) {
+      metrics.mq_messages_received.add(1, { queue, pattern });
+    }
+
+    try {
+      await context.with(ctx, async () => {
+        await handler(msg);
+      });
+
+      span.setStatus({ code: SpanStatusCode.OK });
+
+      const duration = Date.now() - start_time;
+      if (metrics) {
+        record_mq_message({
+          queue,
+          pattern,
+          duration_ms: duration
+        });
+      }
+
+      sfr_logger.debug(`[MQ] Message processed: ${queue}`, {
+        queue,
+        pattern,
+        duration_ms: duration,
+        message_id: msg.properties?.messageId
+      });
+
+    } catch (error) {
+      const duration = Date.now() - start_time;
+
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : "Unknown error"
+      });
+      span.recordException(error as Error);
+
+      if (metrics) {
+        record_mq_message({
+          queue,
+          pattern,
+          duration_ms: duration,
+          error: true
+        });
+      }
+
+      sfr_logger.error(`[MQ] Message error: ${queue}`, {
+        queue,
+        pattern,
+        duration_ms: duration,
+        error: error instanceof Error ? error.message : "Unknown error"
+      });
+
+      throw error;
+    } finally {
+      span.end();
+    }
+  };
+}
+
+/**
+ * Injects trace context into MQ message headers for distributed tracing.
+ * Call this before publishing a message to propagate the trace.
+ * 
+ * @param options - The publish options object (will be modified)
+ * @returns The options object with trace context in headers
+ * 
+ * @example
+ * ```typescript
+ * const options = inject_mq_trace_context({});
+ * channel.publish(exchange, routingKey, content, options);
+ * ```
+ */
+export function inject_mq_trace_context(options: Options.Publish = {}): Options.Publish {
+  const headers = (options.headers ?? {}) as Record<string, string>;
+  propagation.inject(context.active(), headers);
+
+  return {
+    ...options,
+    headers
+  };
+}
+
+/**
+ * Records an MQ publish event for metrics.
+ */
+export function record_mq_publish(exchange: string, pattern: string): void {
+  const metrics = get_sfr_metrics();
+  if (metrics) {
+    metrics.mq_messages_published.add(1, { exchange, pattern });
+  }
+
+  sfr_logger.debug(`[MQ] Message published: ${exchange}`, {
+    exchange,
+    pattern
+  });
+}
+
+/**
+ * Records an MQ message acknowledgment.
+ */
+export function record_mq_ack(queue: string, pattern: string): void {
+  const metrics = get_sfr_metrics();
+  if (metrics) {
+    metrics.mq_messages_acked.add(1, { queue, pattern });
+  }
+}
+
+/**
+ * Records an MQ message rejection.
+ */
+export function record_mq_reject(queue: string, pattern: string, requeue: boolean): void {
+  const metrics = get_sfr_metrics();
+  if (metrics) {
+    metrics.mq_messages_rejected.add(1, { queue, pattern, requeue: String(requeue) });
+  }
+
+  sfr_logger.warn(`[MQ] Message rejected: ${queue}`, {
+    queue,
+    pattern,
+    requeue
+  });
+}
+
+/**
+ * Extracts trace context from the current span for manual propagation.
+ */
+export function get_mq_trace_headers(): Record<string, string> {
+  const headers: Record<string, string> = {};
+  propagation.inject(context.active(), headers);
+  return headers;
+}
+

package/src/observability/middleware/rest.mts

@@ -0,0 +1,143 @@
+/**
+ * SFR REST Telemetry Middleware
+ * 
+ * Express middleware that instruments REST handlers with tracing and metrics.
+ */
+
+import type { Request, Response, NextFunction } from "express";
+import { SpanKind, SpanStatusCode, trace, context } from "@opentelemetry/api";
+import { get_tracer, get_trace_context, extract_trace_context } from "../tracer.mjs";
+import { get_sfr_metrics, record_rest_request } from "../metrics.mjs";
+import { sfr_logger } from "../logger.mjs";
+
+/**
+ * Express middleware that adds OpenTelemetry instrumentation to REST handlers.
+ * 
+ * Features:
+ * - Creates spans for each request
+ * - Extracts trace context from incoming headers (distributed tracing)
+ * - Records request/response metrics
+ * - Logs HTTP traffic with trace correlation
+ * 
+ * @example
+ * ```typescript
+ * app.use(sfr_rest_telemetry());
+ * ```
+ */
+export function sfr_rest_telemetry() {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const tracer = get_tracer();
+    const start_time = Date.now();
+
+    // Extract trace context from incoming headers for distributed tracing
+    const parent_context = extract_trace_context(req.headers as Record<string, string>);
+
+    // Determine route pattern (use matched route if available, fallback to path)
+    const route = req.route?.path ?? req.path;
+
+    const span = tracer.startSpan(
+      `HTTP ${req.method} ${route}`,
+      {
+        kind: SpanKind.SERVER,
+        attributes: {
+          "http.method": req.method,
+          "http.url": req.originalUrl,
+          "http.target": req.path,
+          "http.host": req.get("host") ?? "unknown",
+          "http.scheme": req.protocol,
+          "http.user_agent": req.get("user-agent") ?? "unknown",
+          "http.request_content_length": req.get("content-length") ?? 0,
+          "sfr.protocol": "REST",
+          "sfr.route": route
+        }
+      },
+      parent_context
+    );
+
+    // Make the span active and attach trace context to request
+    const ctx = trace.setSpan(parent_context, span);
+
+    // Attach trace context to request for handler access
+    (req as any).sfr_trace = get_trace_context();
+    (req as any).sfr_span = span;
+
+    // Run the rest of the middleware chain within this span's context
+    context.with(ctx, () => {
+      // Capture response by wrapping res.end
+      const original_end = res.end;
+      const original_json = res.json;
+
+      let response_body_size = 0;
+
+      // Wrap res.json to capture response size
+      res.json = function (this: Response, body: any) {
+        if (body) {
+          response_body_size = Buffer.byteLength(JSON.stringify(body), "utf8");
+        }
+        return original_json.call(this, body);
+      } as typeof res.json;
+
+      res.end = function (...args: any[]) {
+        const duration = Date.now() - start_time;
+        const status_code = res.statusCode;
+
+        // Set span attributes
+        span.setAttribute("http.status_code", status_code);
+        span.setAttribute("http.response_content_length", response_body_size || res.get("content-length") || 0);
+
+        // Set span status based on HTTP status code
+        if (status_code >= 500) {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: `HTTP ${status_code}` });
+        } else if (status_code >= 400) {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: `HTTP ${status_code}` });
+        } else {
+          span.setStatus({ code: SpanStatusCode.OK });
+        }
+
+        // Record metrics
+        const metrics = get_sfr_metrics();
+        if (metrics) {
+          record_rest_request({
+            method: req.method,
+            route,
+            status_code,
+            duration_ms: duration,
+            request_size: parseInt(req.get("content-length") || "0", 10),
+            response_size: response_body_size
+          });
+        }
+
+        // Log the request
+        const log_level = status_code >= 500 ? "error" : status_code >= 400 ? "warn" : "http";
+        sfr_logger[log_level](`${req.method} ${req.path} ${status_code}`, {
+          duration_ms: duration,
+          status_code,
+          method: req.method,
+          path: req.path,
+          route
+        });
+
+        span.end();
+        return original_end.apply(res, args);
+      } as typeof res.end;
+
+      next();
+    });
+  };
+}
+
+/**
+ * Extracts the SFR span from a request.
+ * Useful for adding custom attributes or events within handlers.
+ */
+export function get_request_span(req: Request) {
+  return (req as any).sfr_span;
+}
+
+/**
+ * Extracts the trace context from a request.
+ */
+export function get_request_trace(req: Request): { trace_id: string; span_id: string } | null {
+  return (req as any).sfr_trace ?? null;
+}
+

package/src/observability/middleware/ws.mts

@@ -0,0 +1,162 @@
+/**
+ * SFR WebSocket Telemetry Instrumentation
+ * 
+ * Instruments Socket.IO with tracing and metrics.
+ */
+
+import type { Server, Socket } from "socket.io";
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { get_tracer, with_span, get_trace_context } from "../tracer.mjs";
+import { get_sfr_metrics, record_ws_event } from "../metrics.mjs";
+import { sfr_logger } from "../logger.mjs";
+
+/**
+ * Instruments a Socket.IO server with OpenTelemetry tracing and metrics.
+ * 
+ * Features:
+ * - Tracks active connections
+ * - Creates spans for each event
+ * - Records event metrics
+ * - Logs connection lifecycle with trace correlation
+ * 
+ * @param io - The Socket.IO server instance
+ */
+export function instrument_socket_io(io: Server): void {
+  const metrics = get_sfr_metrics();
+
+  io.on("connection", (socket: Socket) => {
+    const namespace = socket.nsp.name;
+    const socket_id = socket.id;
+
+    // Record connection metrics
+    if (metrics) {
+      metrics.ws_connections_active.add(1, { namespace });
+      metrics.ws_connections_total.add(1, { namespace });
+    }
+
+    sfr_logger.info("[WS] Client connected", {
+      socket_id,
+      namespace,
+      remote_address: socket.handshake.address
+    });
+
+    // Attach trace context to socket for access in handlers
+    (socket as any).sfr_trace = get_trace_context();
+
+    socket.on("disconnect", (reason) => {
+      if (metrics) {
+        metrics.ws_connections_active.add(-1, { namespace });
+      }
+
+      sfr_logger.info("[WS] Client disconnected", {
+        socket_id,
+        namespace,
+        reason
+      });
+    });
+
+    socket.on("error", (error) => {
+      if (metrics) {
+        metrics.ws_errors_total.add(1, { namespace, event: "connection" });
+      }
+
+      sfr_logger.error("[WS] Socket error", {
+        socket_id,
+        namespace,
+        error: error.message
+      });
+    });
+  });
+}
+
+/**
+ * Wraps a WebSocket event handler with tracing and metrics.
+ * Used internally by SFR to instrument registered handlers.
+ * 
+ * @param namespace - The Socket.IO namespace
+ * @param event - The event name
+ * @param handler - The original handler function
+ * @returns Instrumented handler function
+ */
+export function wrap_ws_handler(
+  namespace: string,
+  event: string,
+  handler: (...args: any[]) => void | Promise<void>
+): (...args: any[]) => Promise<void> {
+  return async (...args: any[]) => {
+    const start_time = Date.now();
+    const tracer = get_tracer();
+    const metrics = get_sfr_metrics();
+
+    const span = tracer.startSpan(`WS ${namespace}/${event}`, {
+      kind: SpanKind.SERVER,
+      attributes: {
+        "sfr.protocol": "WS",
+        "ws.namespace": namespace,
+        "ws.event": event
+      }
+    });
+
+    const ctx = trace.setSpan(context.active(), span);
+
+    try {
+      await context.with(ctx, async () => {
+        await handler(...args);
+      });
+
+      span.setStatus({ code: SpanStatusCode.OK });
+
+      const duration = Date.now() - start_time;
+      if (metrics) {
+        record_ws_event({
+          namespace,
+          event,
+          duration_ms: duration
+        });
+      }
+
+      sfr_logger.debug(`[WS] Event handled: ${event}`, {
+        namespace,
+        event,
+        duration_ms: duration
+      });
+
+    } catch (error) {
+      const duration = Date.now() - start_time;
+
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : "Unknown error"
+      });
+      span.recordException(error as Error);
+
+      if (metrics) {
+        record_ws_event({
+          namespace,
+          event,
+          duration_ms: duration,
+          error: true
+        });
+      }
+
+      sfr_logger.error(`[WS] Event error: ${event}`, {
+        namespace,
+        event,
+        duration_ms: duration,
+        error: error instanceof Error ? error.message : "Unknown error"
+      });
+
+      throw error;
+    } finally {
+      span.end();
+    }
+  };
+}
+
+/**
+ * Gets the trace context attached to a socket.
+ */
+export function get_socket_trace(socket: Socket): { trace_id: string; span_id: string } | null {
+  return (socket as any).sfr_trace ?? null;
+}
+

package/src/observability/tracer.mts

@@ -0,0 +1,205 @@
+/**
+ * SFR Tracing Module
+ * 
+ * Provides utilities for creating and managing OpenTelemetry spans.
+ */
+
+import { 
+  trace, 
+  context, 
+  SpanStatusCode, 
+  SpanKind, 
+  propagation,
+  type Span, 
+  type Tracer,
+  type Context
+} from "@opentelemetry/api";
+
+const TRACER_NAME = "@avtechno/sfr";
+const TRACER_VERSION = "1.0.0";
+
+/**
+ * Gets the SFR tracer instance.
+ */
+export function get_tracer(): Tracer {
+  return trace.getTracer(TRACER_NAME, TRACER_VERSION);
+}
+
+export interface SpanOptions {
+  /** Name of the span */
+  name: string;
+  /** Kind of span (default: INTERNAL) */
+  kind?: SpanKind;
+  /** Initial attributes to set on the span */
+  attributes?: Record<string, string | number | boolean>;
+  /** Parent context (optional, uses active context if not provided) */
+  parent_context?: Context;
+}
+
+/**
+ * Wraps an async function with a span for automatic tracing.
+ * Handles errors, sets status, and ensures span is ended.
+ * 
+ * @example
+ * ```typescript
+ * const result = await with_span({
+ *   name: "db:fetch_user",
+ *   attributes: { "user.id": userId }
+ * }, async (span) => {
+ *   span.setAttribute("custom.attr", "value");
+ *   return await db.users.findById(userId);
+ * });
+ * ```
+ */
+export async function with_span<T>(
+  options: SpanOptions,
+  fn: (span: Span) => Promise<T>
+): Promise<T> {
+  const tracer = get_tracer();
+  const parent = options.parent_context ?? context.active();
+
+  return tracer.startActiveSpan(
+    options.name,
+    { 
+      kind: options.kind ?? SpanKind.INTERNAL,
+      attributes: options.attributes
+    },
+    parent,
+    async (span) => {
+      try {
+        const result = await fn(span);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (error) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: error instanceof Error ? error.message : "Unknown error"
+        });
+        span.recordException(error as Error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    }
+  );
+}
+
+/**
+ * Synchronous version of with_span for non-async operations.
+ */
+export function with_span_sync<T>(
+  options: SpanOptions,
+  fn: (span: Span) => T
+): T {
+  const tracer = get_tracer();
+  const parent = options.parent_context ?? context.active();
+  const span = tracer.startSpan(options.name, {
+    kind: options.kind ?? SpanKind.INTERNAL,
+    attributes: options.attributes
+  }, parent);
+
+  try {
+    const result = context.with(trace.setSpan(parent, span), () => fn(span));
+    span.setStatus({ code: SpanStatusCode.OK });
+    return result;
+  } catch (error) {
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error instanceof Error ? error.message : "Unknown error"
+    });
+    span.recordException(error as Error);
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+
+/**
+ * Gets the current trace context (trace_id, span_id) if available.
+ * Useful for correlating logs and external systems.
+ */
+export function get_trace_context(): { trace_id: string; span_id: string; trace_flags: number } | null {
+  const span = trace.getActiveSpan();
+  if (!span) return null;
+
+  const ctx = span.spanContext();
+  return {
+    trace_id: ctx.traceId,
+    span_id: ctx.spanId,
+    trace_flags: ctx.traceFlags
+  };
+}
+
+/**
+ * Injects the current trace context into a carrier object (e.g., HTTP headers, MQ message properties).
+ * Used for distributed trace propagation.
+ * 
+ * @example
+ * ```typescript
+ * const headers = {};
+ * inject_trace_context(headers);
+ * // headers now contains traceparent, tracestate, etc.
+ * ```
+ */
+export function inject_trace_context(carrier: Record<string, string>): void {
+  propagation.inject(context.active(), carrier);
+}
+
+/**
+ * Extracts trace context from a carrier object and returns the context.
+ * Used to continue a distributed trace from an incoming request/message.
+ * 
+ * @example
+ * ```typescript
+ * const parent_ctx = extract_trace_context(req.headers);
+ * await with_span({ name: "handler", parent_context: parent_ctx }, async (span) => {
+ *   // This span is a child of the extracted context
+ * });
+ * ```
+ */
+export function extract_trace_context(carrier: Record<string, string>): Context {
+  return propagation.extract(context.active(), carrier);
+}
+
+/**
+ * Adds attributes to the current active span.
+ * No-op if no span is active.
+ */
+export function add_span_attributes(attributes: Record<string, string | number | boolean>): void {
+  const span = trace.getActiveSpan();
+  if (span) {
+    Object.entries(attributes).forEach(([key, value]) => {
+      span.setAttribute(key, value);
+    });
+  }
+}
+
+/**
+ * Records an event on the current active span.
+ * No-op if no span is active.
+ */
+export function add_span_event(name: string, attributes?: Record<string, string | number | boolean>): void {
+  const span = trace.getActiveSpan();
+  if (span) {
+    span.addEvent(name, attributes);
+  }
+}
+
+/**
+ * Sets an error status on the current active span.
+ * No-op if no span is active.
+ */
+export function set_span_error(error: Error): void {
+  const span = trace.getActiveSpan();
+  if (span) {
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error.message
+    });
+    span.recordException(error);
+  }
+}
+
+// Re-export SpanKind for convenience
+export { SpanKind };
+