@avtechno/sfr 1.0.17 → 2.0.0

package/dist/observability/middleware/mq.mjs

@@ -0,0 +1,156 @@
+/**
+ * SFR MQ Telemetry Instrumentation
+ *
+ * Instruments AMQP/RabbitMQ with tracing and metrics.
+ */
+import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+import { get_tracer } 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, pattern, handler) {
+    return async (msg) => {
+        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 ?? {});
+        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);
+            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 = {}) {
+    const headers = (options.headers ?? {});
+    propagation.inject(context.active(), headers);
+    return {
+        ...options,
+        headers
+    };
+}
+/**
+ * Records an MQ publish event for metrics.
+ */
+export function record_mq_publish(exchange, pattern) {
+    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, pattern) {
+    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, pattern, requeue) {
+    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() {
+    const headers = {};
+    propagation.inject(context.active(), headers);
+    return headers;
+}

package/dist/observability/middleware/rest.mjs

@@ -0,0 +1,120 @@
+/**
+ * SFR REST Telemetry Middleware
+ *
+ * Express middleware that instruments REST handlers with tracing and metrics.
+ */
+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, res, next) => {
+        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);
+        // 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.sfr_trace = get_trace_context();
+        req.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 (body) {
+                if (body) {
+                    response_body_size = Buffer.byteLength(JSON.stringify(body), "utf8");
+                }
+                return original_json.call(this, body);
+            };
+            res.end = function (...args) {
+                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);
+            };
+            next();
+        });
+    };
+}
+/**
+ * Extracts the SFR span from a request.
+ * Useful for adding custom attributes or events within handlers.
+ */
+export function get_request_span(req) {
+    return req.sfr_span;
+}
+/**
+ * Extracts the trace context from a request.
+ */
+export function get_request_trace(req) {
+    return req.sfr_trace ?? null;
+}

package/dist/observability/middleware/ws.mjs

@@ -0,0 +1,135 @@
+/**
+ * SFR WebSocket Telemetry Instrumentation
+ *
+ * Instruments Socket.IO with tracing and metrics.
+ */
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { get_tracer, 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) {
+    const metrics = get_sfr_metrics();
+    io.on("connection", (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.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, event, handler) {
+    return async (...args) => {
+        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);
+            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) {
+    return socket.sfr_trace ?? null;
+}

package/dist/observability/tracer.mjs

@@ -0,0 +1,163 @@
+/**
+ * SFR Tracing Module
+ *
+ * Provides utilities for creating and managing OpenTelemetry spans.
+ */
+import { trace, context, SpanStatusCode, SpanKind, propagation } from "@opentelemetry/api";
+const TRACER_NAME = "@avtechno/sfr";
+const TRACER_VERSION = "1.0.0";
+/**
+ * Gets the SFR tracer instance.
+ */
+export function get_tracer() {
+    return trace.getTracer(TRACER_NAME, TRACER_VERSION);
+}
+/**
+ * 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(options, fn) {
+    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);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Synchronous version of with_span for non-async operations.
+ */
+export function with_span_sync(options, fn) {
+    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);
+        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() {
+    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) {
+    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) {
+    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) {
+    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, attributes) {
+    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) {
+    const span = trace.getActiveSpan();
+    if (span) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error.message
+        });
+        span.recordException(error);
+    }
+}
+// Re-export SpanKind for convenience
+export { SpanKind };