mcp-server-framework 1.0.0

package/build/telemetry/metrics.d.ts

@@ -0,0 +1,127 @@
+/**
+ * OpenTelemetry Metrics for Server State
+ *
+ * Provides metrics collection for the MCP Server including:
+ * - Server uptime and startup time
+ * - Active sessions and connections
+ * - Request counts and latencies
+ * - Memory and resource usage
+ * - Connection state transitions
+ *
+ * @module server/telemetry/metrics
+ */
+import { type ServerMetrics, type ServerStats } from "./core/index.js";
+/**
+ * Server Metrics Manager
+ *
+ * Collects and exports metrics about server state and performance.
+ * Uses OpenTelemetry metrics API when available, falls back to in-memory tracking.
+ */
+declare class ServerMetricsManager implements ServerMetrics {
+    private readonly startTime;
+    private totalRequests;
+    private failedRequests;
+    private activeHttpSessions;
+    private activeSseSessions;
+    private connectionStateChanges;
+    private instruments;
+    /** Resolves when OTEL instruments are initialized (or immediately if OTEL is disabled) */
+    private readonly ready;
+    private otelInitialized;
+    private otelDropWarningLogged;
+    constructor();
+    /**
+     * Wait for OTEL instrument initialization to complete.
+     *
+     * Not required for normal operation — in-memory counters work immediately.
+     * Useful when the caller needs to ensure OTEL metrics are captured from
+     * the very first request (e.g. in integration tests).
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Log a one-time debug warning when OTEL metrics are dropped
+     * because instruments aren't initialized yet.
+     */
+    private warnOtelNotReady;
+    /**
+     * Initialize OpenTelemetry metrics instruments.
+     * Async because @opentelemetry/api is lazy-loaded.
+     */
+    private initializeMetrics;
+    /**
+     * Record a request (tool invocation).
+     */
+    recordRequest(toolName: string, durationMs: number, success: boolean): void;
+    /**
+     * Record an active session change.
+     * @param transport - Transport type ('http' or 'sse')
+     * @param delta - Change in session count (+1 for new, -1 for closed)
+     */
+    recordSessionChange(transport: string, delta: number): void;
+    /**
+     * Record a connection state change.
+     */
+    recordConnectionStateChange(previousState: string, newState: string): void;
+    /**
+     * Record an error.
+     */
+    recordError(errorType: string, component: string): void;
+    /**
+     * Get current server statistics.
+     */
+    getStats(): ServerStats;
+    /**
+     * Reset all statistics.
+     * Useful for testing.
+     */
+    reset(): void;
+}
+/**
+ * Create a new ServerMetricsManager instance.
+ *
+ * Use this factory function for testing or when you need
+ * an independent metrics instance.
+ *
+ * @returns A new ServerMetricsManager instance
+ *
+ * @example
+ * ```typescript
+ * // For testing - create isolated instance
+ * const metrics = createServerMetrics();
+ * metrics.recordRequest('test-tool', 100, true);
+ * ```
+ */
+export declare function createServerMetrics(): ServerMetricsManager;
+/**
+ * Get the singleton ServerMetricsManager instance.
+ *
+ * This is the recommended way to access metrics in production code.
+ * The instance is lazily initialized on first access.
+ *
+ * @returns The singleton ServerMetricsManager instance
+ *
+ * @example
+ * ```typescript
+ * import { getServerMetrics } from './telemetry/metrics.js';
+ *
+ * const metrics = getServerMetrics();
+ * metrics.recordRequest('tool_name', 150, true);
+ * ```
+ */
+export declare function getServerMetrics(): ServerMetricsManager;
+/**
+ * Reset the singleton instance.
+ *
+ * **Warning**: Only use this for testing purposes.
+ * This will reset all tracked metrics. A fresh instance with new OTEL
+ * instruments will be created on the next `getServerMetrics()` call.
+ *
+ * Note: OTEL metric instruments are cumulative by design — resetting
+ * in-memory counters does not affect already-exported metric data points.
+ * The new instance re-creates instruments from the global MeterProvider.
+ *
+ * @internal
+ */
+export declare function resetServerMetrics(): void;
+export { ServerMetricsManager };
+//# sourceMappingURL=metrics.d.ts.map

package/build/telemetry/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAwCzB;;;;;GAKG;AACH,cAAM,oBAAqB,YAAW,aAAa;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAO;IACjC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,sBAAsB,CAAK;IAGnC,OAAO,CAAC,WAAW,CAAyB;IAE5C,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,qBAAqB,CAAS;;IAoBtC;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IASxB;;;OAGG;YACW,iBAAiB;IAwE/B;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IA0B3E;;;;OAIG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAwB3D;;OAEG;IACH,2BAA2B,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAe1E;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAavD;;OAEG;IACH,QAAQ,IAAI,WAAW;IAgBvB;;;OAGG;IACH,KAAK,IAAI,IAAI;CAOd;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,IAAI,oBAAoB,CAE1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,IAAI,oBAAoB,CAKvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAGD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/build/telemetry/metrics.js

@@ -0,0 +1,337 @@
+/**
+ * OpenTelemetry Metrics for Server State
+ *
+ * Provides metrics collection for the MCP Server including:
+ * - Server uptime and startup time
+ * - Active sessions and connections
+ * - Request counts and latencies
+ * - Memory and resource usage
+ * - Connection state transitions
+ *
+ * @module server/telemetry/metrics
+ */
+import { getTelemetryConfig, METRIC_ATTRIBUTES, METRIC_NAMES, METRIC_DESCRIPTIONS, METRIC_UNITS, TRANSPORT_TYPES, TELEMETRY_LOG_COMPONENTS, } from "./core/index.js";
+import { logger as baseLogger } from "../logger/index.js";
+const logger = baseLogger.child({
+    component: TELEMETRY_LOG_COMPONENTS.METRICS,
+});
+/**
+ * Lazily loads and caches the `metrics` namespace from `@opentelemetry/api`.
+ * Returns null if the import fails (shouldn't happen in production).
+ */
+let metricsApi = null;
+async function getMetricsApi() {
+    if (metricsApi)
+        return metricsApi;
+    const api = await import("@opentelemetry/api");
+    metricsApi = api.metrics;
+    return metricsApi;
+}
+/** @internal Log messages for metrics recording */
+const LogMessages = {
+    METRIC_REQUEST_FAILED: "Failed to record request metric: %s",
+    METRIC_SESSION_FAILED: "Failed to record session metric: %s",
+    METRIC_CONNECTION_STATE_FAILED: "Failed to record connection state metric: %s",
+    METRIC_ERROR_FAILED: "Failed to record error metric: %s",
+};
+/**
+ * Server Metrics Manager
+ *
+ * Collects and exports metrics about server state and performance.
+ * Uses OpenTelemetry metrics API when available, falls back to in-memory tracking.
+ */
+class ServerMetricsManager {
+    startTime;
+    totalRequests = 0;
+    failedRequests = 0;
+    activeHttpSessions = 0;
+    activeSseSessions = 0;
+    connectionStateChanges = 0;
+    // OpenTelemetry instruments
+    instruments = {};
+    /** Resolves when OTEL instruments are initialized (or immediately if OTEL is disabled) */
+    ready;
+    otelInitialized = false;
+    otelDropWarningLogged = false;
+    constructor() {
+        this.startTime = new Date();
+        // OTEL instruments are initialized asynchronously because the
+        // @opentelemetry/api import is lazy-loaded (see DD-020). The async
+        // init is fire-and-forget — in-memory counters always work regardless.
+        // In production the lazy singleton (`getServerMetrics()`) is created
+        // after `initializeTelemetry()`, so the await resolves near-instantly
+        // (module already cached).
+        this.ready = this.initializeMetrics()
+            .then(() => {
+            this.otelInitialized = true;
+        })
+            .catch((error) => {
+            const reason = error instanceof Error ? error.message : String(error);
+            logger.warn("OTEL metrics initialization failed: %s (in-memory metrics still active)", reason);
+        });
+    }
+    /**
+     * Wait for OTEL instrument initialization to complete.
+     *
+     * Not required for normal operation — in-memory counters work immediately.
+     * Useful when the caller needs to ensure OTEL metrics are captured from
+     * the very first request (e.g. in integration tests).
+     */
+    async waitForReady() {
+        await this.ready;
+    }
+    /**
+     * Log a one-time debug warning when OTEL metrics are dropped
+     * because instruments aren't initialized yet.
+     */
+    warnOtelNotReady() {
+        if (!this.otelDropWarningLogged && getTelemetryConfig().enabled) {
+            this.otelDropWarningLogged = true;
+            logger.debug("OTEL metrics instruments not yet initialized — OTEL metric dropped (in-memory counter still recorded)");
+        }
+    }
+    /**
+     * Initialize OpenTelemetry metrics instruments.
+     * Async because @opentelemetry/api is lazy-loaded.
+     */
+    async initializeMetrics() {
+        const config = getTelemetryConfig();
+        if (!config.enabled) {
+            return; // Skip OTEL setup if disabled
+        }
+        const metricsNamespace = await getMetricsApi();
+        const meter = metricsNamespace.getMeter(config.serviceName, config.serviceVersion);
+        // Request counter
+        this.instruments.requestCounter = meter.createCounter(METRIC_NAMES.REQUESTS_TOTAL, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.REQUESTS_TOTAL],
+            unit: METRIC_UNITS.COUNT,
+        });
+        // Request duration histogram
+        this.instruments.requestDuration = meter.createHistogram(METRIC_NAMES.REQUEST_DURATION, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.REQUEST_DURATION],
+            unit: METRIC_UNITS.MILLISECONDS,
+        });
+        // Session gauge (up/down counter for active sessions)
+        this.instruments.sessionGauge = meter.createUpDownCounter(METRIC_NAMES.SESSIONS_ACTIVE, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.SESSIONS_ACTIVE],
+            unit: METRIC_UNITS.COUNT,
+        });
+        // Connection state change counter
+        this.instruments.connectionStateCounter = meter.createCounter(METRIC_NAMES.CONNECTION_STATE_CHANGES, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.CONNECTION_STATE_CHANGES],
+            unit: METRIC_UNITS.COUNT,
+        });
+        // Error counter
+        this.instruments.errorCounter = meter.createCounter(METRIC_NAMES.ERRORS_TOTAL, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.ERRORS_TOTAL],
+            unit: METRIC_UNITS.COUNT,
+        });
+        // Observable gauges for system metrics
+        meter
+            .createObservableGauge(METRIC_NAMES.UPTIME, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.UPTIME],
+            unit: METRIC_UNITS.SECONDS,
+        })
+            .addCallback((result) => {
+            const uptimeSeconds = (Date.now() - this.startTime.getTime()) / 1000;
+            result.observe(uptimeSeconds);
+        });
+        meter
+            .createObservableGauge(METRIC_NAMES.MEMORY_HEAP_USED, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.MEMORY_HEAP_USED],
+            unit: METRIC_UNITS.BYTES,
+        })
+            .addCallback((result) => {
+            const memUsage = process.memoryUsage();
+            result.observe(memUsage.heapUsed);
+        });
+        meter
+            .createObservableGauge(METRIC_NAMES.MEMORY_RSS, {
+            description: METRIC_DESCRIPTIONS[METRIC_NAMES.MEMORY_RSS],
+            unit: METRIC_UNITS.BYTES,
+        })
+            .addCallback((result) => {
+            const memUsage = process.memoryUsage();
+            result.observe(memUsage.rss);
+        });
+    }
+    /**
+     * Record a request (tool invocation).
+     */
+    recordRequest(toolName, durationMs, success) {
+        this.totalRequests++;
+        if (!success) {
+            this.failedRequests++;
+        }
+        if (!this.otelInitialized) {
+            this.warnOtelNotReady();
+            return;
+        }
+        try {
+            const attributes = {
+                [METRIC_ATTRIBUTES.TOOL_NAME]: toolName,
+                [METRIC_ATTRIBUTES.SUCCESS]: String(success),
+            };
+            this.instruments.requestCounter?.add(1, attributes);
+            this.instruments.requestDuration?.record(durationMs, attributes);
+        }
+        catch (error) {
+            /* v8 ignore next 3 - OTEL error handling */
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(LogMessages.METRIC_REQUEST_FAILED, message);
+        }
+    }
+    /**
+     * Record an active session change.
+     * @param transport - Transport type ('http' or 'sse')
+     * @param delta - Change in session count (+1 for new, -1 for closed)
+     */
+    recordSessionChange(transport, delta) {
+        let actualDelta = delta;
+        if (transport === TRANSPORT_TYPES.HTTP) {
+            const previous = this.activeHttpSessions;
+            this.activeHttpSessions = Math.max(0, previous + delta);
+            actualDelta = this.activeHttpSessions - previous;
+        }
+        else if (transport === TRANSPORT_TYPES.SSE) {
+            const previous = this.activeSseSessions;
+            this.activeSseSessions = Math.max(0, previous + delta);
+            actualDelta = this.activeSseSessions - previous;
+        }
+        try {
+            this.instruments.sessionGauge?.add(actualDelta, {
+                [METRIC_ATTRIBUTES.TRANSPORT]: transport,
+            });
+        }
+        catch (error) {
+            /* v8 ignore next 3 - OTEL error handling */
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(LogMessages.METRIC_SESSION_FAILED, message);
+        }
+    }
+    /**
+     * Record a connection state change.
+     */
+    recordConnectionStateChange(previousState, newState) {
+        this.connectionStateChanges++;
+        try {
+            this.instruments.connectionStateCounter?.add(1, {
+                [METRIC_ATTRIBUTES.PREVIOUS_STATE]: previousState,
+                [METRIC_ATTRIBUTES.CURRENT_STATE]: newState,
+            });
+        }
+        catch (error) {
+            /* v8 ignore next 3 - OTEL error handling */
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(LogMessages.METRIC_CONNECTION_STATE_FAILED, message);
+        }
+    }
+    /**
+     * Record an error.
+     */
+    recordError(errorType, component) {
+        try {
+            this.instruments.errorCounter?.add(1, {
+                [METRIC_ATTRIBUTES.ERROR_TYPE]: errorType,
+                [METRIC_ATTRIBUTES.COMPONENT]: component,
+            });
+        }
+        catch (error) {
+            /* v8 ignore next 3 - OTEL error handling */
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(LogMessages.METRIC_ERROR_FAILED, message);
+        }
+    }
+    /**
+     * Get current server statistics.
+     */
+    getStats() {
+        const memUsage = process.memoryUsage();
+        return {
+            uptimeMs: Date.now() - this.startTime.getTime(),
+            startTime: this.startTime,
+            totalRequests: this.totalRequests,
+            failedRequests: this.failedRequests,
+            activeHttpSessions: this.activeHttpSessions,
+            activeSseSessions: this.activeSseSessions,
+            connectionStateChanges: this.connectionStateChanges,
+            memoryUsageBytes: memUsage.rss,
+            heapUsedBytes: memUsage.heapUsed,
+        };
+    }
+    /**
+     * Reset all statistics.
+     * Useful for testing.
+     */
+    reset() {
+        this.totalRequests = 0;
+        this.failedRequests = 0;
+        this.activeHttpSessions = 0;
+        this.activeSseSessions = 0;
+        this.connectionStateChanges = 0;
+    }
+}
+// ============================================================================
+// Factory & Singleton
+// ============================================================================
+/** Singleton instance - lazily initialized */
+let instance = null;
+/**
+ * Create a new ServerMetricsManager instance.
+ *
+ * Use this factory function for testing or when you need
+ * an independent metrics instance.
+ *
+ * @returns A new ServerMetricsManager instance
+ *
+ * @example
+ * ```typescript
+ * // For testing - create isolated instance
+ * const metrics = createServerMetrics();
+ * metrics.recordRequest('test-tool', 100, true);
+ * ```
+ */
+export function createServerMetrics() {
+    return new ServerMetricsManager();
+}
+/**
+ * Get the singleton ServerMetricsManager instance.
+ *
+ * This is the recommended way to access metrics in production code.
+ * The instance is lazily initialized on first access.
+ *
+ * @returns The singleton ServerMetricsManager instance
+ *
+ * @example
+ * ```typescript
+ * import { getServerMetrics } from './telemetry/metrics.js';
+ *
+ * const metrics = getServerMetrics();
+ * metrics.recordRequest('tool_name', 150, true);
+ * ```
+ */
+export function getServerMetrics() {
+    if (!instance) {
+        instance = new ServerMetricsManager();
+    }
+    return instance;
+}
+/**
+ * Reset the singleton instance.
+ *
+ * **Warning**: Only use this for testing purposes.
+ * This will reset all tracked metrics. A fresh instance with new OTEL
+ * instruments will be created on the next `getServerMetrics()` call.
+ *
+ * Note: OTEL metric instruments are cumulative by design — resetting
+ * in-memory counters does not affect already-exported metric data points.
+ * The new instance re-creates instruments from the global MeterProvider.
+ *
+ * @internal
+ */
+export function resetServerMetrics() {
+    instance = null;
+}
+// Export the class for testing
+export { ServerMetricsManager };
+//# sourceMappingURL=metrics.js.map

package/build/telemetry/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,wBAAwB,GAGzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;IAC9B,SAAS,EAAE,wBAAwB,CAAC,OAAO;CAC5C,CAAC,CAAC;AAEH;;;GAGG;AACH,IAAI,UAAU,GAAuD,IAAI,CAAC;AAE1E,KAAK,UAAU,aAAa;IAC1B,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAC/C,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC;IACzB,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,mDAAmD;AACnD,MAAM,WAAW,GAAG;IAClB,qBAAqB,EAAE,qCAAqC;IAC5D,qBAAqB,EAAE,qCAAqC;IAC5D,8BAA8B,EAAE,8CAA8C;IAC9E,mBAAmB,EAAE,mCAAmC;CAChD,CAAC;AAcX;;;;;GAKG;AACH,MAAM,oBAAoB;IACP,SAAS,CAAO;IACzB,aAAa,GAAG,CAAC,CAAC;IAClB,cAAc,GAAG,CAAC,CAAC;IACnB,kBAAkB,GAAG,CAAC,CAAC;IACvB,iBAAiB,GAAG,CAAC,CAAC;IACtB,sBAAsB,GAAG,CAAC,CAAC;IAEnC,4BAA4B;IACpB,WAAW,GAAsB,EAAE,CAAC;IAE5C,0FAA0F;IACzE,KAAK,CAAgB;IAC9B,eAAe,GAAG,KAAK,CAAC;IACxB,qBAAqB,GAAG,KAAK,CAAC;IAEtC;QACE,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAC5B,8DAA8D;QAC9D,mEAAmE;QACnE,uEAAuE;QACvE,qEAAqE;QACrE,sEAAsE;QACtE,2BAA2B;QAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,iBAAiB,EAAE;aAClC,IAAI,CAAC,GAAG,EAAE;YACT,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC9B,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtE,MAAM,CAAC,IAAI,CAAC,yEAAyE,EAAE,MAAM,CAAC,CAAC;QACjG,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED;;;OAGG;IACK,gBAAgB;QACtB,IAAI,CAAC,IAAI,CAAC,qBAAqB,IAAI,kBAAkB,EAAE,CAAC,OAAO,EAAE,CAAC;YAChE,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;YAClC,MAAM,CAAC,KAAK,CACV,uGAAuG,CACxG,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,iBAAiB;QAC7B,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;QAEpC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,8BAA8B;QACxC,CAAC;QAED,MAAM,gBAAgB,GAAG,MAAM,aAAa,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;QAEnF,kBAAkB;QAClB,IAAI,CAAC,WAAW,CAAC,cAAc,GAAG,KAAK,CAAC,aAAa,CAAC,YAAY,CAAC,cAAc,EAAE;YACjF,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,cAAc,CAAC;YAC7D,IAAI,EAAE,YAAY,CAAC,KAAK;SACzB,CAAC,CAAC;QAEH,6BAA6B;QAC7B,IAAI,CAAC,WAAW,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC,YAAY,CAAC,gBAAgB,EAAE;YACtF,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,gBAAgB,CAAC;YAC/D,IAAI,EAAE,YAAY,CAAC,YAAY;SAChC,CAAC,CAAC;QAEH,sDAAsD;QACtD,IAAI,CAAC,WAAW,CAAC,YAAY,GAAG,KAAK,CAAC,mBAAmB,CAAC,YAAY,CAAC,eAAe,EAAE;YACtF,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,eAAe,CAAC;YAC9D,IAAI,EAAE,YAAY,CAAC,KAAK;SACzB,CAAC,CAAC;QAEH,kCAAkC;QAClC,IAAI,CAAC,WAAW,CAAC,sBAAsB,GAAG,KAAK,CAAC,aAAa,CAAC,YAAY,CAAC,wBAAwB,EAAE;YACnG,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,wBAAwB,CAAC;YACvE,IAAI,EAAE,YAAY,CAAC,KAAK;SACzB,CAAC,CAAC;QAEH,gBAAgB;QAChB,IAAI,CAAC,WAAW,CAAC,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC,YAAY,CAAC,YAAY,EAAE;YAC7E,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,YAAY,CAAC;YAC3D,IAAI,EAAE,YAAY,CAAC,KAAK;SACzB,CAAC,CAAC;QAEH,uCAAuC;QACvC,KAAK;aACF,qBAAqB,CAAC,YAAY,CAAC,MAAM,EAAE;YAC1C,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,MAAM,CAAC;YACrD,IAAI,EAAE,YAAY,CAAC,OAAO;SAC3B,CAAC;aACD,WAAW,CAAC,CAAC,MAAM,EAAE,EAAE;YACtB,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;YACrE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;QAEL,KAAK;aACF,qBAAqB,CAAC,YAAY,CAAC,gBAAgB,EAAE;YACpD,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,gBAAgB,CAAC;YAC/D,IAAI,EAAE,YAAY,CAAC,KAAK;SACzB,CAAC;aACD,WAAW,CAAC,CAAC,MAAM,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YACvC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QAEL,KAAK;aACF,qBAAqB,CAAC,YAAY,CAAC,UAAU,EAAE;YAC9C,WAAW,EAAE,mBAAmB,CAAC,YAAY,CAAC,UAAU,CAAC;YACzD,IAAI,EAAE,YAAY,CAAC,KAAK;SACzB,CAAC;aACD,WAAW,CAAC,CAAC,MAAM,EAAE,EAAE;YACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YACvC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB,EAAE,UAAkB,EAAE,OAAgB;QAClE,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,UAAU,GAAe;gBAC7B,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,QAAQ;gBACvC,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;aAC7C,CAAC;YAEF,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YACpD,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QACnE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4CAA4C;YAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,SAAiB,EAAE,KAAa;QAClD,IAAI,WAAW,GAAG,KAAK,CAAC;QAExB,IAAI,SAAS,KAAK,eAAe,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC;YACzC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;YACxD,WAAW,GAAG,IAAI,CAAC,kBAAkB,GAAG,QAAQ,CAAC;QACnD,CAAC;aAAM,IAAI,SAAS,KAAK,eAAe,CAAC,GAAG,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC;YACxC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;YACvD,WAAW,GAAG,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAC;QAClD,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,WAAW,EAAE;gBAC9C,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,SAAS;aACzC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4CAA4C;YAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;OAEG;IACH,2BAA2B,CAAC,aAAqB,EAAE,QAAgB;QACjE,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAE9B,IAAI,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC,EAAE;gBAC9C,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,aAAa;gBACjD,CAAC,iBAAiB,CAAC,aAAa,CAAC,EAAE,QAAQ;aAC5C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4CAA4C;YAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,8BAA8B,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,SAAiB,EAAE,SAAiB;QAC9C,IAAI,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,EAAE;gBACpC,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;gBACzC,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,SAAS;aACzC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4CAA4C;YAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QAEvC,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE;YAC/C,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;YAC3C,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,sBAAsB,EAAE,IAAI,CAAC,sBAAsB;YACnD,gBAAgB,EAAE,QAAQ,CAAC,GAAG;YAC9B,aAAa,EAAE,QAAQ,CAAC,QAAQ;SACjC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,sBAAsB,GAAG,CAAC,CAAC;IAClC,CAAC;CACF;AAED,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,8CAA8C;AAC9C,IAAI,QAAQ,GAAgC,IAAI,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,oBAAoB,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,GAAG,IAAI,oBAAoB,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB;IAChC,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,+BAA+B;AAC/B,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/build/telemetry/sdk.d.ts

@@ -0,0 +1,110 @@
+/**
+ * OpenTelemetry SDK Initialization
+ *
+ * Handles the lifecycle of the OpenTelemetry SDK including:
+ * - SDK initialization with targeted instrumentation
+ * - Trace and metric export via OTLP/HTTP
+ * - Prometheus metrics embedded at `/metrics` on the MCP Express server
+ * - Graceful shutdown
+ *
+ * ## Configuration
+ *
+ * All OTEL settings are routed through the config system (env vars + config file).
+ * The framework builds exporters and readers explicitly from the unified config
+ * so that both env vars and config file are respected consistently.
+ *
+ * **Framework-managed** (with defaults):
+ * - `OTEL_ENABLED` — Master toggle (default: false)
+ * - `OTEL_SERVICE_NAME` — Service name (default: 'mcp-server')
+ * - `OTEL_METRICS_EXPORTER` — Metric exporters (default: 'otlp,prometheus')
+ * - `OTEL_LOGS_EXPORTER` — Log exporter (default: 'none' — framework has own logger)
+ *
+ * **Standard OTEL (pass-through, no defaults)**:
+ * - `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL
+ * - `OTEL_TRACES_EXPORTER` — Trace exporter: otlp (default), console, none
+ * - `OTEL_LOG_LEVEL` — SDK diagnostic log level
+ * - `OTEL_METRIC_EXPORT_INTERVAL` — Periodic metric export interval (ms)
+ *
+ * ## Environment Variable Synchronization
+ *
+ * The NodeSDK reads standard OTEL env vars directly from `process.env`
+ * for internal auto-configuration. Since the framework's config system
+ * deliberately does NOT mutate `process.env` (12-Factor compliance),
+ * config-file-only values would be invisible to the SDK.
+ *
+ * {@link syncOtelEnvironment} bridges this gap by writing config values
+ * to `process.env` for keys that are NOT already set, preserving the
+ * 12-Factor priority: env var > config file > default.
+ *
+ * ## DiagLogger / OTEL_LOG_LEVEL
+ *
+ * `OTEL_LOG_LEVEL` is consumed (deleted) from `process.env` in Step 0
+ * of {@link initializeTelemetry}, BEFORE the NodeSDK constructor.
+ * Without this, the SDK calls `diag.setLogger(new DiagConsoleLogger(), level)`
+ * — writing diagnostics to stdout and corrupting the MCP stdio transport.
+ *
+ * The framework sets `frameworkDiagLogger` as default DiagLogger,
+ * which routes all OTEL diagnostics through the framework's logging
+ * pipeline (→ stderr with secret scrubbing and structured formatting).
+ * Power users can override via `onBeforeTelemetryInit` callback.
+ *
+ * ## Why exporters are built manually
+ *
+ * The SDK's env-var auto-config is bypassed when `traceExporter` or
+ * `metricReaders` are passed to the NodeSDK constructor. Since we need
+ * to build metric readers manually (for Prometheus embedded mode), AND
+ * we want config-file support for all settings, we build both trace
+ * and metric exporters explicitly from the unified config.
+ *
+ * @module server/telemetry/sdk
+ */
+/**
+ * Initialize the OpenTelemetry SDK.
+ * Call this at application startup, before any other code.
+ *
+ * All @opentelemetry/* packages are loaded dynamically on first call
+ * (see DD-020). When OTEL is disabled, no packages are loaded and
+ * the function returns immediately — saving ~15-20 MB of memory.
+ *
+ * Builds both trace and metric exporters from the unified config.
+ * Only HTTP and Express instrumentations are loaded — other
+ * auto-instrumentations are irrelevant for MCP servers.
+ *
+ * @param onBeforeInit - Optional callback invoked before SDK construction.
+ *   Power users can call `diag.setLogger()` in this callback to override the
+ *   framework's default DiagLogger. The callback runs AFTER the framework sets
+ *   `frameworkDiagLogger` as default.
+ * @returns true if OpenTelemetry was initialized, false if disabled
+ *
+ * @example
+ * ```typescript
+ * import { initializeTelemetry } from './telemetry/index.js';
+ *
+ * const enabled = await initializeTelemetry();
+ * ```
+ */
+export declare function initializeTelemetry(onBeforeInit?: () => void): Promise<boolean>;
+/**
+ * Shutdown the OpenTelemetry SDK.
+ * Call this during application shutdown.
+ *
+ * @returns Promise that resolves when shutdown is complete
+ */
+export declare function shutdownTelemetry(): Promise<void>;
+/**
+ * Check if the SDK is currently initialized.
+ *
+ * @returns true if SDK is initialized
+ */
+export declare function isSdkInitialized(): boolean;
+/**
+ * Get the Prometheus exporter instance.
+ *
+ * Returns null when telemetry is disabled, not yet initialized,
+ * or 'prometheus' is not in OTEL_METRICS_EXPORTER.
+ * Used by the `/metrics` Express route to serve Prometheus metrics.
+ *
+ * @returns PrometheusExporter instance or null
+ */
+export declare function getPrometheusExporter(): unknown;
+//# sourceMappingURL=sdk.d.ts.map

package/build/telemetry/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAqIH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAqIrF;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkBvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C"}