mcp-server-framework 1.0.0

package/build/telemetry/sdk.js

@@ -0,0 +1,547 @@
+/**
+ * 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
+ */
+import { METRIC_NAMES } from "./core/constants.js";
+import { logger as baseLogger } from "../logger/index.js";
+import { setTraceContextExtractor } from "../logger/core/index.js";
+import { getTelemetryConfig, TELEMETRY_LOG_COMPONENTS, SdkLogMessages, frameworkDiagLogger } from "./core/index.js";
+let otelModules = null;
+let otelModulesPromise = null;
+/**
+ * Dynamically loads all @opentelemetry/* packages needed for SDK initialization.
+ * Called once on first `initializeTelemetry()` invocation when OTEL is enabled.
+ * Cached for subsequent calls. Uses promise caching to prevent double-loading
+ * if called concurrently.
+ */
+async function loadOtelModules() {
+    if (otelModules)
+        return otelModules;
+    if (otelModulesPromise)
+        return otelModulesPromise;
+    otelModulesPromise = loadOtelModulesImpl();
+    try {
+        otelModules = await otelModulesPromise;
+        return otelModules;
+    }
+    catch (err) {
+        // Reset cached promise so a subsequent call can retry (e.g., after
+        // installing missing OTEL packages in development).
+        otelModulesPromise = null;
+        throw err;
+    }
+}
+async function loadOtelModulesImpl() {
+    const [sdkNode, sdkMetrics, traceOtlpHttp, metricsOtlpHttp, prometheus, sdkTraceBase, instrHttp, instrExpress, resources, semconv,] = await Promise.all([
+        import("@opentelemetry/sdk-node"),
+        import("@opentelemetry/sdk-metrics"),
+        import("@opentelemetry/exporter-trace-otlp-http"),
+        import("@opentelemetry/exporter-metrics-otlp-http"),
+        import("@opentelemetry/exporter-prometheus"),
+        import("@opentelemetry/sdk-trace-base"),
+        import("@opentelemetry/instrumentation-http"),
+        import("@opentelemetry/instrumentation-express"),
+        import("@opentelemetry/resources"),
+        import("@opentelemetry/semantic-conventions"),
+    ]);
+    return {
+        NodeSDK: sdkNode.NodeSDK,
+        PeriodicExportingMetricReader: sdkMetrics.PeriodicExportingMetricReader,
+        ConsoleMetricExporter: sdkMetrics.ConsoleMetricExporter,
+        AggregationType: sdkMetrics.AggregationType,
+        OTLPTraceExporter: traceOtlpHttp.OTLPTraceExporter,
+        OTLPMetricExporter: metricsOtlpHttp.OTLPMetricExporter,
+        PrometheusExporter: prometheus.PrometheusExporter,
+        ConsoleSpanExporter: sdkTraceBase.ConsoleSpanExporter,
+        HttpInstrumentation: instrHttp.HttpInstrumentation,
+        ExpressInstrumentation: instrExpress.ExpressInstrumentation,
+        envDetector: resources.envDetector,
+        resourceFromAttributes: resources.resourceFromAttributes,
+        ATTR_SERVICE_NAME: semconv.ATTR_SERVICE_NAME,
+        ATTR_SERVICE_VERSION: semconv.ATTR_SERVICE_VERSION,
+    };
+}
+const logger = baseLogger.child({ component: TELEMETRY_LOG_COMPONENTS.SDK });
+/**
+ * Framework infrastructure routes excluded from HTTP trace instrumentation.
+ *
+ * These paths handle liveness/readiness probes and metrics scraping.
+ * They fire at high frequency (every 10–30s in Kubernetes) and would
+ * flood traces with low-value spans. Filtering is applied via
+ * {@link HttpInstrumentation}'s `ignoreIncomingRequestHook`.
+ */
+const TRACE_IGNORED_ROUTES = new Set(["/health", "/ready", "/metrics"]);
+/** SDK instance — null when not initialized */
+let sdk = null;
+/**
+ * Prometheus exporter instance — null when OTEL is disabled or
+ * 'prometheus' is not in OTEL_METRICS_EXPORTER.
+ *
+ * Always created with `preventServerStart: true` (embedded mode).
+ * The `/metrics` Express route delegates to this exporter via
+ * {@link getPrometheusExporter}.
+ */
+let prometheusExporter = null;
+/**
+ * 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 async function initializeTelemetry(onBeforeInit) {
+    const config = getTelemetryConfig();
+    if (!config.enabled) {
+        logger.debug(SdkLogMessages.INIT_SKIPPED);
+        return false;
+    }
+    logger.info(SdkLogMessages.INIT_START);
+    // ── Step 0: Framework DiagLogger Setup ───────────────────────────────
+    // Load @opentelemetry/api early (lightweight, ~200 KB — not a heavy SDK package).
+    // Set frameworkDiagLogger as the default DiagLogger to route OTEL SDK
+    // diagnostics through the framework's logging pipeline (→ stderr).
+    // Consume OTEL_LOG_LEVEL from process.env to prevent the NodeSDK
+    // constructor from calling diag.setLogger(new DiagConsoleLogger(), level)
+    // which would write to stdout and corrupt MCP stdio transport.
+    const api = await import("@opentelemetry/api");
+    const diagLevelStr = process.env["OTEL_LOG_LEVEL"]?.toUpperCase();
+    delete process.env["OTEL_LOG_LEVEL"];
+    const diagLevelMap = {
+        NONE: api.DiagLogLevel.NONE,
+        ERROR: api.DiagLogLevel.ERROR,
+        WARN: api.DiagLogLevel.WARN,
+        INFO: api.DiagLogLevel.INFO,
+        DEBUG: api.DiagLogLevel.DEBUG,
+        VERBOSE: api.DiagLogLevel.VERBOSE,
+        ALL: api.DiagLogLevel.ALL,
+    };
+    const diagLevel = diagLevelStr ? (diagLevelMap[diagLevelStr] ?? api.DiagLogLevel.INFO) : api.DiagLogLevel.INFO;
+    api.diag.setLogger(frameworkDiagLogger, {
+        logLevel: diagLevel,
+        suppressOverrideMessage: true,
+    });
+    // ── Step 1: Power-User Pre-Init Hook ─────────────────────────────────
+    // Called after default DiagLogger setup. Power users can override
+    // the DiagLogger via diag.setLogger(), register instrumentations,
+    // or configure propagators here.
+    if (onBeforeInit) {
+        onBeforeInit();
+    }
+    // ── Step 2: Lazy-load OTEL packages ──────────────────────────────────
+    // All heavy @opentelemetry/* modules are loaded here, not at module parse
+    // time. This saves ~15-20 MB when OTEL is disabled (see DD-020).
+    // Since OTEL packages are optionalDependencies, gracefully handle the case
+    // where they are not installed despite OTEL_ENABLED=true.
+    let otel;
+    try {
+        otel = await loadOtelModules();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        logger.warn(SdkLogMessages.INIT_PACKAGES_MISSING, reason);
+        return false;
+    }
+    // ── Step 3: Env-Var Sync ─────────────────────────────────────────────
+    // The NodeSDK reads standard OTEL env vars (OTEL_TRACES_EXPORTER,
+    // OTEL_LOGS_EXPORTER, etc.) directly from process.env for its internal
+    // auto-configuration.  Our config system merges config-file values
+    // into the Zod parse source but does NOT mutate process.env (12-Factor:
+    // real env vars must always win).  This means config-file-only settings
+    // would be invisible to the SDK's internal env-var checks.
+    //
+    // syncOtelEnvironment() bridges this gap by writing config values to
+    // process.env for keys that are NOT already set, preserving 12-Factor
+    // priority (env var > config file > default).
+    syncOtelEnvironment(config);
+    // ── Step 4: Build Resource & Exporters ───────────────────────────────
+    // Resource: service identity attributes.
+    // Additional attributes can be set via OTEL_RESOURCE_ATTRIBUTES (env only).
+    const resource = otel.resourceFromAttributes({
+        [otel.ATTR_SERVICE_NAME]: config.serviceName,
+        [otel.ATTR_SERVICE_VERSION]: config.serviceVersion,
+    });
+    // Build trace exporter from config.
+    // Defaults to OTLP when not explicitly set.
+    const traceExporter = buildTraceExporter(config, otel);
+    // Build metric readers from OTEL_METRICS_EXPORTER.
+    const metricReaders = buildMetricReaders(config, otel);
+    logger.info(SdkLogMessages.METRICS_EXPORTERS_CONFIGURED, config.metricsExporters.join(", "));
+    // ── Step 5: Construct & Start SDK ────────────────────────────────────
+    // - resourceDetectors: Only OTEL_RESOURCE_ATTRIBUTES (env) is respected.
+    //   Host/process/OS auto-detectors are disabled to keep target_info lean.
+    // - views: Custom histogram buckets for HTTP and MCP duration metrics.
+    //   Default OTEL SDK emits 16 bucket boundaries — reduced to MCP-relevant ranges.
+    sdk = new otel.NodeSDK({
+        resource,
+        ...(traceExporter !== undefined && { traceExporter }),
+        metricReaders,
+        resourceDetectors: [otel.envDetector],
+        views: buildMetricViews(otel),
+        instrumentations: [
+            new otel.HttpInstrumentation({
+                // Suppress trace spans for framework infrastructure routes
+                // (health probes, readiness checks, Prometheus scrapes).
+                // These fire frequently and produce low-value trace data.
+                ignoreIncomingRequestHook: (request) => {
+                    const path = (request.url?.split("?")[0] ?? "").replace(/\/+$/, "");
+                    return TRACE_IGNORED_ROUTES.has(path);
+                },
+            }),
+            new otel.ExpressInstrumentation(),
+        ],
+    });
+    sdk.start();
+    // Register OTEL trace context extractor in the logger.
+    // Uses the plugin interface (DD-023) — the logger has no OTEL dependency.
+    // Must happen AFTER sdk.start() so that the API has a registered TracerProvider.
+    const otelExtractor = {
+        extract() {
+            const span = api.trace.getActiveSpan();
+            if (!span)
+                return undefined;
+            const ctx = span.spanContext();
+            if (!api.isSpanContextValid(ctx))
+                return undefined;
+            return { traceId: ctx.traceId, spanId: ctx.spanId };
+        },
+    };
+    setTraceContextExtractor(otelExtractor);
+    logger.info(SdkLogMessages.INIT_SUCCESS, config.serviceName, config.endpoint);
+    return true;
+}
+/**
+ * Shutdown the OpenTelemetry SDK.
+ * Call this during application shutdown.
+ *
+ * @returns Promise that resolves when shutdown is complete
+ */
+export async function shutdownTelemetry() {
+    if (!sdk) {
+        logger.debug(SdkLogMessages.SHUTDOWN_SKIPPED);
+        return;
+    }
+    logger.info(SdkLogMessages.SHUTDOWN_START);
+    try {
+        await sdk.shutdown();
+        sdk = null;
+        prometheusExporter = null;
+        logger.info(SdkLogMessages.SHUTDOWN_SUCCESS);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(SdkLogMessages.SHUTDOWN_ERROR, errorMessage);
+        throw error;
+    }
+}
+/**
+ * Check if the SDK is currently initialized.
+ *
+ * @returns true if SDK is initialized
+ */
+export function isSdkInitialized() {
+    return sdk !== null;
+}
+/**
+ * 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 function getPrometheusExporter() {
+    return prometheusExporter;
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Synchronize framework config values to `process.env` for the NodeSDK.
+ *
+ * The framework's config system resolves values from env vars, config files,
+ * and defaults into a unified `TelemetryConfig` but deliberately does NOT
+ * mutate `process.env` (12-Factor compliance). However, the NodeSDK reads
+ * several `OTEL_*` env vars directly from `process.env` for its internal
+ * auto-configuration (e.g., log exporter, trace exporter selection).
+ *
+ * This function bridges the gap by writing config values to `process.env`
+ * **only for keys that are not already set**. This preserves 12-Factor
+ * priority: real env vars always override config file values.
+ *
+ * Synchronized variables:
+ * - `OTEL_TRACES_EXPORTER` — Prevents SDK from auto-enabling OTLP traces
+ * - `OTEL_LOGS_EXPORTER` — Prevents SDK from auto-enabling OTLP logs
+ * - `OTEL_SERVICE_NAME` — Ensures SDK resource matches framework config
+ * - `OTEL_EXPORTER_OTLP_ENDPOINT` — Ensures OTLP endpoint is consistent
+ *
+ * **Note**: `OTEL_LOG_LEVEL` is intentionally NOT synced here. It is
+ * consumed (deleted) in Step 1 of {@link initializeTelemetry} to prevent
+ * the NodeSDK constructor from setting DiagConsoleLogger (→ stdout).
+ *
+ * @param config - Resolved telemetry configuration
+ */
+function syncOtelEnvironment(config) {
+    // Helper: only set env var if not already defined by the environment.
+    // This preserves 12-Factor priority (real env var > config file > default).
+    const setIfAbsent = (key, value) => {
+        if (value !== undefined && !process.env[key]) {
+            process.env[key] = value;
+        }
+    };
+    // Trace exporter: prevents "OTEL_TRACES_EXPORTER is empty" warning
+    setIfAbsent("OTEL_TRACES_EXPORTER", config.tracesExporter);
+    // Log exporter: prevents SDK from auto-enabling OTLP log export.
+    // Framework default is 'none' (own logger handles all logging).
+    setIfAbsent("OTEL_LOGS_EXPORTER", config.logsExporter);
+    // Service name: ensures SDK resource detection matches framework config
+    setIfAbsent("OTEL_SERVICE_NAME", config.serviceName);
+    // OTLP endpoint: ensures exporters use the config-file endpoint
+    setIfAbsent("OTEL_EXPORTER_OTLP_ENDPOINT", config.endpoint);
+}
+/**
+ * Build the trace exporter from config.
+ *
+ * - `'none'` — No trace export (returns undefined)
+ * - `'console'` — ConsoleSpanExporter (for debugging)
+ * - `'otlp'` or unset — OTLPTraceExporter with optional endpoint
+ *
+ * @param config - Telemetry configuration
+ * @param otel - Lazily loaded OTEL modules
+ * @returns SpanExporter instance or undefined (no tracing)
+ */
+function buildTraceExporter(config, otel) {
+    const exporter = config.tracesExporter?.toLowerCase() ?? "otlp";
+    switch (exporter) {
+        case "none":
+            logger.debug(SdkLogMessages.TRACE_EXPORTER_CONFIGURED, "none");
+            return undefined;
+        case "console":
+            logger.debug(SdkLogMessages.TRACE_EXPORTER_CONFIGURED, "console");
+            return new otel.ConsoleSpanExporter();
+        case "otlp":
+        default: {
+            if (exporter !== "otlp") {
+                logger.warn(SdkLogMessages.UNKNOWN_TRACE_EXPORTER, exporter);
+            }
+            // OTLPTraceExporter reads OTEL_EXPORTER_OTLP_ENDPOINT from env natively,
+            // but we pass the config value explicitly to support config-file-based setup.
+            const url = `${config.endpoint}/v1/traces`;
+            logger.debug(SdkLogMessages.TRACE_EXPORTER_CONFIGURED, `otlp (endpoint: ${url})`);
+            return new otel.OTLPTraceExporter({ url });
+        }
+    }
+}
+/**
+ * Build metric readers from the configured exporter list.
+ *
+ * Supported values in `OTEL_METRICS_EXPORTER`:
+ * - `'otlp'` — OTLP/HTTP metric export
+ * - `'prometheus'` — Embedded Prometheus exporter at `/metrics`
+ * - `'console'` — Console metric exporter (for debugging)
+ * - `'none'` — No metrics export
+ *
+ * Unknown values are silently ignored.
+ *
+ * @param config - Telemetry configuration
+ * @param otel - Lazily loaded OTEL modules
+ * @returns Array of MetricReader instances
+ */
+function buildMetricReaders(config, otel) {
+    const readers = [];
+    for (const exporterName of config.metricsExporters) {
+        switch (exporterName) {
+            case "otlp": {
+                // OTLPMetricExporter reads endpoint from env natively,
+                // but we pass it explicitly to support config-file-based setup.
+                const url = `${config.endpoint}/v1/metrics`;
+                const otlpReader = new otel.PeriodicExportingMetricReader({
+                    exporter: new otel.OTLPMetricExporter({ url }),
+                    ...(config.metricExportInterval && {
+                        exportIntervalMillis: config.metricExportInterval,
+                    }),
+                });
+                readers.push(otlpReader);
+                break;
+            }
+            case "prometheus": {
+                // Embedded mode: preventServerStart stops PrometheusExporter from
+                // binding its own HTTP server. Metrics are served by the Express
+                // /metrics route via getPrometheusExporter().
+                prometheusExporter = new otel.PrometheusExporter({
+                    preventServerStart: true,
+                });
+                readers.push(prometheusExporter);
+                logger.debug(SdkLogMessages.PROMETHEUS_EXPORTER_ADDED);
+                break;
+            }
+            case "console": {
+                const consoleReader = new otel.PeriodicExportingMetricReader({
+                    exporter: new otel.ConsoleMetricExporter(),
+                    ...(config.metricExportInterval && {
+                        exportIntervalMillis: config.metricExportInterval,
+                    }),
+                });
+                readers.push(consoleReader);
+                break;
+            }
+            case "none":
+                // Explicit no-op — skip metric export entirely
+                break;
+            default:
+                logger.warn(SdkLogMessages.UNKNOWN_METRIC_EXPORTER, exporterName);
+                break;
+        }
+    }
+    return readers;
+}
+// ============================================================================
+// Metric Views
+// ============================================================================
+/**
+ * Reduced histogram bucket boundaries for HTTP request duration (OLD semconv).
+ *
+ * Metric: `http.server.duration` (milliseconds).
+ * Default OTEL SDK has 16 boundaries (0, 5, 10, 25, 50, 75, 100, 250, 500,
+ * 750, 1000, 2500, 5000, 7500, 10000). For MCP servers, 9 buckets covering
+ * the common response time range (5ms–10s) are sufficient.
+ *
+ * Active when `OTEL_SEMCONV_STABILITY_OPT_IN` is unset or contains `http/dup`.
+ */
+const HTTP_DURATION_BUCKETS_MS = [5, 10, 25, 50, 100, 250, 500, 1000, 5000];
+/**
+ * Histogram bucket boundaries for HTTP request duration (stable semconv).
+ *
+ * Metric: `http.server.request.duration` (seconds).
+ * Active when `OTEL_SEMCONV_STABILITY_OPT_IN` contains `http` or `http/dup`.
+ * Values are the same ranges as {@link HTTP_DURATION_BUCKETS_MS} converted to
+ * seconds, with finer sub-10ms resolution added.
+ */
+const HTTP_DURATION_BUCKETS_S = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 5];
+/**
+ * Histogram bucket boundaries for MCP request duration.
+ *
+ * MCP tool handlers typically respond in 1ms–5s. Finer granularity at the
+ * low end (1–50ms) captures fast tools; the tail (1s–10s) covers API calls.
+ */
+const MCP_DURATION_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000, 5000];
+/**
+ * Builds OpenTelemetry metric views with custom histogram bucket boundaries.
+ *
+ * Overrides the default OTEL bucket set (16 boundaries) with MCP-relevant
+ * ranges for both HTTP and MCP duration histograms, reducing Prometheus
+ * cardinality while preserving useful percentile resolution.
+ *
+ * Two HTTP views are registered to cover both semconv variants:
+ * - `http.server.duration` (OLD, milliseconds) — default behavior
+ * - `http.server.request.duration` (stable, seconds) — active when
+ *   `OTEL_SEMCONV_STABILITY_OPT_IN` includes `http` or `http/dup`
+ *
+ * Both views are always registered; the SDK only applies a view when
+ * its `instrumentName` matches an actually emitted metric.
+ *
+ * @returns Array of ViewOptions for NodeSDK configuration
+ */
+function buildMetricViews(otel) {
+    return [
+        // OLD semconv: http.server.duration (milliseconds)
+        {
+            instrumentName: "http.server.duration",
+            aggregation: {
+                type: otel.AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+                options: { boundaries: HTTP_DURATION_BUCKETS_MS },
+            },
+        },
+        // Stable semconv: http.server.request.duration (seconds)
+        // Active when OTEL_SEMCONV_STABILITY_OPT_IN=http or http/dup
+        {
+            instrumentName: "http.server.request.duration",
+            aggregation: {
+                type: otel.AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+                options: { boundaries: HTTP_DURATION_BUCKETS_S },
+            },
+        },
+        {
+            instrumentName: METRIC_NAMES.REQUEST_DURATION,
+            aggregation: {
+                type: otel.AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+                options: { boundaries: MCP_DURATION_BUCKETS },
+            },
+        },
+    ];
+}
+//# sourceMappingURL=sdk.js.map

package/build/telemetry/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"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"}

package/build/telemetry/tracing.d.ts

@@ -0,0 +1,78 @@
+/**
+ * OpenTelemetry Tracing Utilities
+ *
+ * Provides convenient helpers for creating and managing spans.
+ * All OTEL imports are lazy-loaded (see DD-020). Synchronous functions
+ * gracefully no-op when the API hasn't been loaded yet.
+ *
+ * @module server/telemetry/tracing
+ */
+import type { Span, Attributes, Tracer } from "@opentelemetry/api";
+import { type SpanOptions, type TraceContext, type SpanCallback, type AsyncSpanCallback } from "./core/index.js";
+/** @public SpanKind constants — numeric-compatible with `@opentelemetry/api.SpanKind` */
+export declare const FrameworkSpanKind: {
+    readonly INTERNAL: 0;
+    readonly SERVER: 1;
+    readonly CLIENT: 2;
+    readonly PRODUCER: 3;
+    readonly CONSUMER: 4;
+};
+/** @public SpanStatusCode constants — numeric-compatible with `@opentelemetry/api.SpanStatusCode` */
+export declare const FrameworkSpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+/**
+ * Get the tracer instance for the MCP Server.
+ * Returns a noop tracer proxy when the OTEL API hasn't been loaded yet.
+ */
+export declare function getTracer(): Tracer;
+/**
+ * Execute a function within a new span.
+ * Automatically handles errors and sets span status.
+ *
+ * @param name - Name of the span
+ * @param fn - Function to execute within the span
+ * @param options - Span options
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withSpan('processRequest', async (span) => {
+ *   span.setAttribute('request.id', requestId);
+ *   return await processRequest();
+ * });
+ * ```
+ */
+export declare function withSpan<T>(name: string, fn: AsyncSpanCallback<T>, options?: SpanOptions): Promise<T>;
+/**
+ * Execute a synchronous function within a new span.
+ *
+ * @param name - Name of the span
+ * @param fn - Function to execute within the span
+ * @param options - Span options
+ * @returns The result of the function
+ */
+export declare function withSpanSync<T>(name: string, fn: SpanCallback<T>, options?: SpanOptions): T;
+/**
+ * Get the currently active span.
+ * Returns undefined if no span is active or OTEL API is not loaded.
+ */
+export declare function getActiveSpan(): Span | undefined;
+/**
+ * Add attributes to the active span.
+ * Does nothing if no span is active.
+ */
+export declare function addSpanAttributes(attributes: Attributes): void;
+/**
+ * Add an event to the active span.
+ * Does nothing if no span is active.
+ */
+export declare function addSpanEvent(name: string, attributes?: Attributes): void;
+/**
+ * Get the current trace context for propagation.
+ * Useful for passing context to external services.
+ */
+export declare function getTraceContext(): TraceContext | undefined;
+//# sourceMappingURL=tracing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/telemetry/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AA+CzB,yFAAyF;AACzF,eAAO,MAAM,iBAAiB;;;;;;CAMpB,CAAC;AAEX,qGAAqG;AACrG,eAAO,MAAM,uBAAuB;;;;CAI1B,CAAC;AAEX;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAclC;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAuC/G;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,WAAgB,GAAG,CAAC,CA4C/F;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAIhD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAK9D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAKxE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,SAAS,CAW1D"}