@aichatwar/shared 1.0.145 → 1.0.147

package/build/index.d.ts

@@ -8,6 +8,11 @@ export * from "./middlewares/error-handler";
 export * from "./middlewares/jwt-extractor";
 export * from "./middlewares/login-required";
 export * from "./middlewares/validate-request";
+export * from "./observability/logger";
+export * from "./observability/correlation";
+export * from "./observability/express";
+export * from "./observability/tracing";
+export * from "./observability/third-party-logging";
 export * from "./events/nats/baseListener";
 export * from "./events/nats/basePublisher";
 export * from "./events/kafka/baseListener";

package/build/index.js

@@ -24,6 +24,12 @@ __exportStar(require("./middlewares/error-handler"), exports);
 __exportStar(require("./middlewares/jwt-extractor"), exports);
 __exportStar(require("./middlewares/login-required"), exports);
 __exportStar(require("./middlewares/validate-request"), exports);
+// Observability (Phase 1)
+__exportStar(require("./observability/logger"), exports);
+__exportStar(require("./observability/correlation"), exports);
+__exportStar(require("./observability/express"), exports);
+__exportStar(require("./observability/tracing"), exports);
+__exportStar(require("./observability/third-party-logging"), exports);
 __exportStar(require("./events/nats/baseListener"), exports);
 __exportStar(require("./events/nats/basePublisher"), exports);
 __exportStar(require("./events/kafka/baseListener"), exports);

package/build/middlewares/error-handler.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.errorHandler = void 0;
 const customError_1 = require("../errors/customError");
+const correlation_1 = require("../observability/correlation");
+const logger_1 = require("../observability/logger");
 `common structure for errors:
 {
   errors:{
@@ -10,7 +12,15 @@ const customError_1 = require("../errors/customError");
 }
 `;
 const errorHandler = (err, req, res, next) => {
-    console.log("Error:", err);
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    (0, logger_1.logger)().error({
+        correlationId,
+        err,
+        http: {
+            method: req.method,
+            path: req.originalUrl || req.url,
+        },
+    }, "request.error");
     if (err instanceof customError_1.CustomError) {
         return res.status(err.statusCode).send({ errors: err.serializeDetails() });
     }

package/build/observability/correlation.d.ts

@@ -0,0 +1,6 @@
+export type CorrelationContext = {
+    correlationId: string;
+};
+export declare function runWithCorrelationId<T>(correlationId: string | undefined, fn: () => T): T;
+export declare function getCorrelationId(): string | undefined;
+export declare function getOrCreateCorrelationId(incoming?: string): string;

package/build/observability/correlation.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithCorrelationId = runWithCorrelationId;
+exports.getCorrelationId = getCorrelationId;
+exports.getOrCreateCorrelationId = getOrCreateCorrelationId;
+const async_hooks_1 = require("async_hooks");
+const crypto_1 = __importDefault(require("crypto"));
+const storage = new async_hooks_1.AsyncLocalStorage();
+function newCorrelationId() {
+    // Prefer Node's built-in UUID when available.
+    const anyCrypto = crypto_1.default;
+    if (typeof anyCrypto.randomUUID === 'function') {
+        return anyCrypto.randomUUID();
+    }
+    return crypto_1.default.randomBytes(16).toString('hex');
+}
+function runWithCorrelationId(correlationId, fn) {
+    const cid = correlationId && String(correlationId).trim() ? String(correlationId).trim() : newCorrelationId();
+    return storage.run({ correlationId: cid }, fn);
+}
+function getCorrelationId() {
+    var _a;
+    return (_a = storage.getStore()) === null || _a === void 0 ? void 0 : _a.correlationId;
+}
+function getOrCreateCorrelationId(incoming) {
+    const existing = getCorrelationId();
+    if (existing)
+        return existing;
+    return (incoming && String(incoming).trim()) || newCorrelationId();
+}

package/build/observability/express.d.ts

@@ -0,0 +1,3 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare function correlationIdMiddleware(req: Request, res: Response, next: NextFunction): void;
+export declare function requestLoggingMiddleware(req: Request, res: Response, next: NextFunction): void;

package/build/observability/express.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.correlationIdMiddleware = correlationIdMiddleware;
+exports.requestLoggingMiddleware = requestLoggingMiddleware;
+const correlation_1 = require("./correlation");
+const logger_1 = require("./logger");
+function correlationIdMiddleware(req, res, next) {
+    const incoming = req.headers['x-correlation-id'] || req.headers['x-request-id'];
+    (0, correlation_1.runWithCorrelationId)(incoming, () => {
+        const cid = (0, correlation_1.getCorrelationId)();
+        if (cid) {
+            res.setHeader('x-correlation-id', cid);
+        }
+        next();
+    });
+}
+function requestLoggingMiddleware(req, res, next) {
+    const start = Date.now();
+    const cid = () => (0, correlation_1.getCorrelationId)();
+    // Log at finish so that downstream middleware (e.g. JWT extractors) can attach context to req.
+    res.on('finish', () => {
+        const durationMs = Date.now() - start;
+        const statusCode = res.statusCode;
+        const level = statusCode >= 500 ? 'error' : statusCode >= 400 ? 'warn' : 'info';
+        const jwtPayload = req.jwtPayload;
+        const userId = (jwtPayload === null || jwtPayload === void 0 ? void 0 : jwtPayload.id) ? String(jwtPayload.id) : undefined;
+        (0, logger_1.logger)()[level]({
+            correlationId: cid(),
+            http: {
+                method: req.method,
+                path: req.originalUrl || req.url,
+                statusCode,
+                durationMs,
+            },
+            userId,
+        }, 'http.request');
+    });
+    next();
+}

package/build/observability/logger.d.ts

@@ -0,0 +1,2 @@
+import { type Logger } from 'pino';
+export declare function logger(): Logger;

package/build/observability/logger.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = logger;
+const pino_1 = __importDefault(require("pino"));
+let _logger = null;
+function buildLogger() {
+    const isDev = (process.env.NODE_ENV || '').toLowerCase() !== 'production';
+    const base = {
+        service: process.env.SERVICE_NAME,
+        environment: process.env.NODE_ENV,
+        version: process.env.APP_VERSION,
+    };
+    // Keep redaction broad and safe. Services can add more redaction upstream.
+    const redactPaths = [
+        'req.headers.authorization',
+        'req.headers.cookie',
+        'req.headers["set-cookie"]',
+        'req.headers["x-api-key"]',
+        'password',
+        'token',
+        'accessToken',
+        'refreshToken',
+        'apiKey',
+        'authorization',
+        'cookie',
+    ];
+    return (0, pino_1.default)({
+        level: process.env.LOG_LEVEL || (isDev ? 'debug' : 'info'),
+        timestamp: pino_1.default.stdTimeFunctions.isoTime,
+        base,
+        redact: { paths: redactPaths, remove: true },
+        formatters: {
+            level: (label) => ({ level: label }),
+        },
+        serializers: {
+            err: pino_1.default.stdSerializers.err,
+            req: pino_1.default.stdSerializers.req,
+            res: pino_1.default.stdSerializers.res,
+        },
+    });
+}
+function logger() {
+    if (!_logger)
+        _logger = buildLogger();
+    return _logger;
+}

package/build/observability/third-party-logging.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Standardized logging for 3rd-party API calls
+ *
+ * This module provides helpers for logging:
+ * - Retry attempts (WARN level)
+ * - Final failures (ERROR level)
+ * - Rate limits (WARN/ERROR based on impact)
+ * - Unmasked error details (stack traces, status codes, request IDs)
+ * - Correlation IDs for traceability
+ *
+ * Best practices:
+ * - Each retry: log as WARN with attempt, backoff, reason
+ * - Final failure: log as ERROR with full error context
+ * - Rate limits: log as WARN or ERROR depending on user impact
+ */
+export interface ThirdPartyErrorContext {
+    /** Provider name (e.g., 'openai', 'anthropic', 'cohere') */
+    provider: string;
+    /** Operation name (e.g., 'generateResponse', 'createAgent') */
+    operation: string;
+    /** HTTP status code if available */
+    statusCode?: number;
+    /** Error type/class */
+    errorType?: string;
+    /** Error message */
+    errorMessage: string;
+    /** Full error object (for stack trace) */
+    error: any;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** Request ID from upstream service if available */
+    requestId?: string;
+    /** Rate limit headers if available */
+    rateLimitHeaders?: {
+        limit?: string;
+        remaining?: string;
+        reset?: string;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+export interface RetryAttemptContext {
+    /** Provider name */
+    provider: string;
+    /** Operation name */
+    operation: string;
+    /** Current attempt number (1-indexed) */
+    attempt: number;
+    /** Maximum number of attempts */
+    maxAttempts: number;
+    /** Backoff delay in milliseconds */
+    backoffMs: number;
+    /** Reason for retry */
+    reason: string;
+    /** Previous error that triggered retry */
+    previousError?: any;
+    /** HTTP status code from previous attempt */
+    previousStatusCode?: number;
+}
+/**
+ * Log a retry attempt for a 3rd-party API call
+ *
+ * This should be called BEFORE each retry attempt.
+ * Logs at WARN level as per observability best practices.
+ *
+ * @param context Retry attempt context
+ */
+export declare function logRetryAttempt(context: RetryAttemptContext): void;
+/**
+ * Log a final failure for a 3rd-party API call
+ *
+ * This should be called when all retries are exhausted or when a non-retryable error occurs.
+ * Logs at ERROR level with full unmasked error details.
+ *
+ * @param context Error context
+ */
+export declare function logThirdPartyError(context: ThirdPartyErrorContext): void;
+/**
+ * Log a successful 3rd-party API call
+ *
+ * @param provider Provider name
+ * @param operation Operation name
+ * @param durationMs Duration in milliseconds
+ * @param metadata Additional metadata (e.g., token usage, request ID)
+ */
+export declare function logThirdPartySuccess(provider: string, operation: string, durationMs: number, metadata?: Record<string, any>): void;
+/**
+ * Extract error context from a caught error
+ *
+ * Handles various error types:
+ * - Axios errors (with response.status, response.data)
+ * - OpenAI SDK errors (with status, message)
+ * - Anthropic SDK errors (with status, message)
+ * - Generic errors
+ *
+ * @param error Error object
+ * @param provider Provider name
+ * @param operation Operation name
+ * @returns Error context
+ */
+export declare function extractErrorContext(error: any, provider: string, operation: string): ThirdPartyErrorContext;

package/build/observability/third-party-logging.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Standardized logging for 3rd-party API calls
+ *
+ * This module provides helpers for logging:
+ * - Retry attempts (WARN level)
+ * - Final failures (ERROR level)
+ * - Rate limits (WARN/ERROR based on impact)
+ * - Unmasked error details (stack traces, status codes, request IDs)
+ * - Correlation IDs for traceability
+ *
+ * Best practices:
+ * - Each retry: log as WARN with attempt, backoff, reason
+ * - Final failure: log as ERROR with full error context
+ * - Rate limits: log as WARN or ERROR depending on user impact
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logRetryAttempt = logRetryAttempt;
+exports.logThirdPartyError = logThirdPartyError;
+exports.logThirdPartySuccess = logThirdPartySuccess;
+exports.extractErrorContext = extractErrorContext;
+const logger_1 = require("./logger");
+const correlation_1 = require("./correlation");
+const tracing_1 = require("./tracing");
+/**
+ * Log a retry attempt for a 3rd-party API call
+ *
+ * This should be called BEFORE each retry attempt.
+ * Logs at WARN level as per observability best practices.
+ *
+ * @param context Retry attempt context
+ */
+function logRetryAttempt(context) {
+    var _a, _b, _c, _d, _e, _f;
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    (0, logger_1.logger)().warn({
+        message: '3rd-party API retry attempt',
+        provider: context.provider,
+        operation: context.operation,
+        attempt: context.attempt,
+        maxAttempts: context.maxAttempts,
+        backoffMs: context.backoffMs,
+        reason: context.reason,
+        previousStatusCode: context.previousStatusCode,
+        correlationId,
+        // Include previous error details (unmasked) for debugging
+        previousError: context.previousError ? {
+            type: ((_b = (_a = context.previousError) === null || _a === void 0 ? void 0 : _a.constructor) === null || _b === void 0 ? void 0 : _b.name) || typeof context.previousError,
+            message: (_c = context.previousError) === null || _c === void 0 ? void 0 : _c.message,
+            status: ((_d = context.previousError) === null || _d === void 0 ? void 0 : _d.status) || ((_e = context.previousError) === null || _e === void 0 ? void 0 : _e.statusCode),
+            code: (_f = context.previousError) === null || _f === void 0 ? void 0 : _f.code,
+            // Don't include full stack in retry log (will be in final error log)
+        } : undefined,
+    });
+    // Add retry attempt to span
+    (0, tracing_1.addSpanAttributes)({
+        [`${context.provider}.retry.attempt`]: context.attempt,
+        [`${context.provider}.retry.reason`]: context.reason,
+    });
+}
+/**
+ * Log a final failure for a 3rd-party API call
+ *
+ * This should be called when all retries are exhausted or when a non-retryable error occurs.
+ * Logs at ERROR level with full unmasked error details.
+ *
+ * @param context Error context
+ */
+function logThirdPartyError(context) {
+    var _a, _b, _c;
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    // Determine log level: ERROR for failures, WARN for rate limits that don't block user
+    const isRateLimit = context.statusCode === 429;
+    const logLevel = isRateLimit && !context.retryable ? 'warn' : 'error';
+    // Build error log entry with unmasked details
+    const errorLog = Object.assign({ message: `3rd-party API ${context.operation} failed`, provider: context.provider, operation: context.operation, errorType: context.errorType || ((_b = (_a = context.error) === null || _a === void 0 ? void 0 : _a.constructor) === null || _b === void 0 ? void 0 : _b.name) || 'UnknownError', errorMessage: context.errorMessage, statusCode: context.statusCode, retryable: context.retryable, correlationId, 
+        // Include full error object for stack trace (unmasked)
+        err: context.error, 
+        // Include request ID if available (for upstream debugging)
+        requestId: context.requestId, 
+        // Include rate limit headers if available
+        rateLimit: context.rateLimitHeaders }, (context.metadata || {}));
+    // Log at appropriate level
+    if (logLevel === 'error') {
+        (0, logger_1.logger)().error(errorLog);
+    }
+    else {
+        (0, logger_1.logger)().warn(errorLog);
+    }
+    // Record exception in OpenTelemetry span
+    if (context.error instanceof Error) {
+        (0, tracing_1.recordSpanException)(context.error);
+    }
+    else {
+        // Create Error object if not already one
+        const errorObj = new Error(context.errorMessage);
+        if ((_c = context.error) === null || _c === void 0 ? void 0 : _c.stack) {
+            errorObj.stack = context.error.stack;
+        }
+        (0, tracing_1.recordSpanException)(errorObj);
+    }
+    // Add error attributes to span
+    (0, tracing_1.addSpanAttributes)({
+        [`${context.provider}.error`]: true,
+        [`${context.provider}.error.type`]: context.errorType || 'UnknownError',
+        [`${context.provider}.error.status_code`]: context.statusCode || 0,
+        [`${context.provider}.error.retryable`]: context.retryable || false,
+    });
+}
+/**
+ * Log a successful 3rd-party API call
+ *
+ * @param provider Provider name
+ * @param operation Operation name
+ * @param durationMs Duration in milliseconds
+ * @param metadata Additional metadata (e.g., token usage, request ID)
+ */
+function logThirdPartySuccess(provider, operation, durationMs, metadata) {
+    const correlationId = (0, correlation_1.getCorrelationId)();
+    (0, logger_1.logger)().info(Object.assign({ message: `3rd-party API ${operation} succeeded`, provider,
+        operation, duration_ms: durationMs, correlationId }, (metadata || {})));
+    // Add success attributes to span
+    (0, tracing_1.addSpanAttributes)({
+        [`${provider}.success`]: true,
+        [`${provider}.duration_ms`]: durationMs,
+    });
+}
+/**
+ * Extract error context from a caught error
+ *
+ * Handles various error types:
+ * - Axios errors (with response.status, response.data)
+ * - OpenAI SDK errors (with status, message)
+ * - Anthropic SDK errors (with status, message)
+ * - Generic errors
+ *
+ * @param error Error object
+ * @param provider Provider name
+ * @param operation Operation name
+ * @returns Error context
+ */
+function extractErrorContext(error, provider, operation) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    // Extract status code from various error formats
+    let statusCode;
+    let requestId;
+    let rateLimitHeaders;
+    // Handle Axios errors
+    if (error.response) {
+        statusCode = error.response.status;
+        requestId = ((_a = error.response.headers) === null || _a === void 0 ? void 0 : _a['x-request-id']) || ((_b = error.response.headers) === null || _b === void 0 ? void 0 : _b['request-id']);
+        rateLimitHeaders = {
+            limit: (_c = error.response.headers) === null || _c === void 0 ? void 0 : _c['x-ratelimit-limit'],
+            remaining: (_d = error.response.headers) === null || _d === void 0 ? void 0 : _d['x-ratelimit-remaining'],
+            reset: (_e = error.response.headers) === null || _e === void 0 ? void 0 : _e['x-ratelimit-reset'],
+        };
+    }
+    // Handle OpenAI/Anthropic SDK errors
+    else if (error.status) {
+        statusCode = error.status;
+        requestId = error.request_id || error.requestId;
+    }
+    // Handle HTTP errors with statusCode
+    else if (error.statusCode) {
+        statusCode = error.statusCode;
+    }
+    // Determine if error is retryable
+    const retryable = isRetryableError(statusCode, error.code);
+    // Extract error message
+    const errorMessage = error.message ||
+        ((_h = (_g = (_f = error.response) === null || _f === void 0 ? void 0 : _f.data) === null || _g === void 0 ? void 0 : _g.error) === null || _h === void 0 ? void 0 : _h.message) ||
+        ((_k = (_j = error.response) === null || _j === void 0 ? void 0 : _j.data) === null || _k === void 0 ? void 0 : _k.message) ||
+        'Unknown error';
+    return {
+        provider,
+        operation,
+        statusCode,
+        errorType: ((_l = error.constructor) === null || _l === void 0 ? void 0 : _l.name) || error.type || 'UnknownError',
+        errorMessage,
+        error,
+        retryable,
+        requestId,
+        rateLimitHeaders,
+        metadata: {
+            code: error.code,
+            type: error.type,
+        },
+    };
+}
+/**
+ * Determine if an error is retryable based on status code and error code
+ *
+ * @param statusCode HTTP status code
+ * @param errorCode Error code (e.g., 'ECONNREFUSED', 'ETIMEDOUT')
+ * @returns true if error is retryable
+ */
+function isRetryableError(statusCode, errorCode) {
+    // Retryable HTTP status codes
+    if (statusCode === 429 || statusCode === 500 || statusCode === 502 || statusCode === 503 || statusCode === 504) {
+        return true;
+    }
+    // Retryable network errors
+    if (errorCode === 'ECONNREFUSED' || errorCode === 'ETIMEDOUT' || errorCode === 'ENOTFOUND') {
+        return true;
+    }
+    // Non-retryable: authentication, invalid requests, not found
+    if (statusCode === 401 || statusCode === 400 || statusCode === 404) {
+        return false;
+    }
+    // Default to retryable for unknown errors (conservative approach)
+    return true;
+}

package/build/observability/tracing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OpenTelemetry tracing setup with Azure Monitor exporter
+ *
+ * This module initializes OpenTelemetry SDK with:
+ * - Azure Monitor exporter for Application Insights
+ * - Auto-instrumentation for HTTP, MongoDB, Redis, Kafka
+ * - Correlation ID propagation
+ * - Service name and version from environment
+ */
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { Span } from '@opentelemetry/api';
+/**
+ * Initialize OpenTelemetry SDK with Azure Monitor exporter
+ *
+ * Environment variables:
+ * - APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Application Insights connection string
+ * - SERVICE_NAME: Service name (default: 'unknown-service')
+ * - APP_VERSION: Service version (default: 'unknown')
+ * - OTEL_SERVICE_NAME: OpenTelemetry service name (falls back to SERVICE_NAME)
+ * - OTEL_LOG_LEVEL: OpenTelemetry log level (default: 'info')
+ *
+ * @returns NodeSDK instance or null if initialization fails
+ */
+export declare function initializeTracing(): NodeSDK | null;
+/**
+ * Shutdown OpenTelemetry SDK gracefully
+ * Call this during service shutdown
+ */
+export declare function shutdownTracing(): Promise<void>;
+/**
+ * Get the current active span
+ * @returns Active span or undefined
+ */
+export declare function getActiveSpan(): Span | undefined;
+/**
+ * Create a new span for an operation
+ * @param name Span name
+ * @param fn Function to execute within the span
+ * @returns Result of the function
+ */
+export declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T> | T): Promise<T>;
+/**
+ * Add attributes to the current active span
+ * @param attributes Key-value pairs to add
+ */
+export declare function addSpanAttributes(attributes: Record<string, string | number | boolean>): void;
+/**
+ * Record an exception on the current active span
+ * @param error Error to record
+ */
+export declare function recordSpanException(error: Error): void;

package/build/observability/tracing.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * OpenTelemetry tracing setup with Azure Monitor exporter
+ *
+ * This module initializes OpenTelemetry SDK with:
+ * - Azure Monitor exporter for Application Insights
+ * - Auto-instrumentation for HTTP, MongoDB, Redis, Kafka
+ * - Correlation ID propagation
+ * - Service name and version from environment
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeTracing = initializeTracing;
+exports.shutdownTracing = shutdownTracing;
+exports.getActiveSpan = getActiveSpan;
+exports.withSpan = withSpan;
+exports.addSpanAttributes = addSpanAttributes;
+exports.recordSpanException = recordSpanException;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const monitor_opentelemetry_exporter_1 = require("@azure/monitor-opentelemetry-exporter");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const api_1 = require("@opentelemetry/api");
+const correlation_1 = require("./correlation");
+const logger_1 = require("./logger");
+let sdk = null;
+/**
+ * Initialize OpenTelemetry SDK with Azure Monitor exporter
+ *
+ * Environment variables:
+ * - APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Application Insights connection string
+ * - SERVICE_NAME: Service name (default: 'unknown-service')
+ * - APP_VERSION: Service version (default: 'unknown')
+ * - OTEL_SERVICE_NAME: OpenTelemetry service name (falls back to SERVICE_NAME)
+ * - OTEL_LOG_LEVEL: OpenTelemetry log level (default: 'info')
+ *
+ * @returns NodeSDK instance or null if initialization fails
+ */
+function initializeTracing() {
+    // Skip if already initialized
+    if (sdk) {
+        (0, logger_1.logger)().warn({ message: 'OpenTelemetry SDK already initialized' });
+        return sdk;
+    }
+    const connectionString = process.env.APPLICATIONINSIGHTS_CONNECTION_STRING;
+    const serviceName = process.env.OTEL_SERVICE_NAME || process.env.SERVICE_NAME || 'unknown-service';
+    const serviceVersion = process.env.APP_VERSION || 'unknown';
+    // If no connection string, skip initialization (useful for local dev)
+    if (!connectionString) {
+        (0, logger_1.logger)().warn({
+            message: 'OpenTelemetry initialization skipped: APPLICATIONINSIGHTS_CONNECTION_STRING not set',
+            serviceName,
+        });
+        return null;
+    }
+    try {
+        // Create Azure Monitor trace exporter
+        const traceExporter = new monitor_opentelemetry_exporter_1.AzureMonitorTraceExporter({
+            connectionString,
+        });
+        // Create resource with service metadata
+        const resource = (0, resources_1.resourceFromAttributes)({
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_VERSION]: serviceVersion,
+            [semantic_conventions_1.SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
+        });
+        // Initialize SDK with auto-instrumentation
+        sdk = new sdk_node_1.NodeSDK({
+            resource,
+            traceExporter,
+            instrumentations: [
+                (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)({
+                    // Enable HTTP instrumentation (Express, etc.)
+                    '@opentelemetry/instrumentation-http': {
+                        enabled: true,
+                    },
+                    // Enable MongoDB instrumentation
+                    '@opentelemetry/instrumentation-mongodb': {
+                        enabled: true,
+                    },
+                    // Enable Redis instrumentation (if using ioredis or node-redis)
+                    '@opentelemetry/instrumentation-redis': {
+                        enabled: true,
+                    },
+                    // Enable Kafka instrumentation
+                    '@opentelemetry/instrumentation-kafkajs': {
+                        enabled: true,
+                    },
+                    // Disable fs instrumentation (too noisy)
+                    '@opentelemetry/instrumentation-fs': {
+                        enabled: false,
+                    },
+                }),
+            ],
+        });
+        // Start the SDK
+        sdk.start();
+        (0, logger_1.logger)().info({
+            message: 'OpenTelemetry SDK initialized successfully',
+            serviceName,
+            serviceVersion,
+            exporter: 'AzureMonitor',
+        });
+        return sdk;
+    }
+    catch (error) {
+        (0, logger_1.logger)().error({
+            err: error,
+            message: 'Failed to initialize OpenTelemetry SDK',
+            serviceName,
+        });
+        return null;
+    }
+}
+/**
+ * Shutdown OpenTelemetry SDK gracefully
+ * Call this during service shutdown
+ */
+function shutdownTracing() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (sdk) {
+            try {
+                yield sdk.shutdown();
+                (0, logger_1.logger)().info({ message: 'OpenTelemetry SDK shut down successfully' });
+                sdk = null;
+            }
+            catch (error) {
+                (0, logger_1.logger)().error({
+                    err: error,
+                    message: 'Error shutting down OpenTelemetry SDK',
+                });
+            }
+        }
+    });
+}
+/**
+ * Get the current active span
+ * @returns Active span or undefined
+ */
+function getActiveSpan() {
+    return api_1.trace.getActiveSpan();
+}
+/**
+ * Create a new span for an operation
+ * @param name Span name
+ * @param fn Function to execute within the span
+ * @returns Result of the function
+ */
+function withSpan(name, fn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const tracer = api_1.trace.getTracer(process.env.SERVICE_NAME || 'unknown-service', process.env.APP_VERSION || 'unknown');
+        return tracer.startActiveSpan(name, (span) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                // Add correlation ID to span attributes
+                const correlationId = (0, correlation_1.getCorrelationId)();
+                if (correlationId) {
+                    span.setAttribute('correlation.id', correlationId);
+                }
+                const result = yield fn(span);
+                span.setStatus({ code: api_1.SpanStatusCode.OK });
+                return result;
+            }
+            catch (error) {
+                span.setStatus({
+                    code: api_1.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                span.recordException(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        }));
+    });
+}
+/**
+ * Add attributes to the current active span
+ * @param attributes Key-value pairs to add
+ */
+function addSpanAttributes(attributes) {
+    const span = getActiveSpan();
+    if (span) {
+        Object.entries(attributes).forEach(([key, value]) => {
+            span.setAttribute(key, value);
+        });
+    }
+}
+/**
+ * Record an exception on the current active span
+ * @param error Error to record
+ */
+function recordSpanException(error) {
+    const span = getActiveSpan();
+    if (span) {
+        span.recordException(error);
+        span.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aichatwar/shared",
-  "version": "1.0.145",
+  "version": "1.0.147",
   "main": "./build/index.js",
   "typs": "./build/index.d.ts",
   "files": [
@@ -28,9 +28,16 @@
     "express-validator": "^7.2.1"
   },
   "dependencies": {
+    "@azure/monitor-opentelemetry-exporter": "^1.0.0-beta.32",
+    "@opentelemetry/api": "^1.8.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.69.0",
+    "@opentelemetry/resources": "^2.5.1",
+    "@opentelemetry/semantic-conventions": "^1.24.0",
+    "@opentelemetry/sdk-node": "^0.212.0",
     "jsonwebtoken": "^9.0.2",
     "kafkajs": "^2.2.4",
     "mongoose-update-if-current": "^1.4.0",
-    "node-nats-streaming": "^0.3.2"
+    "node-nats-streaming": "^0.3.2",
+    "pino": "^9.9.0"
   }
 }