@juspay/neurolink 12.58.1 → 13.0.0

package/dist/services/server/ai/observability/instrumentation.js

@@ -1,1332 +1,285 @@
-/**
- * OpenTelemetry Instrumentation for Langfuse v4
- *
- * Configures OpenTelemetry TracerProvider with LangfuseSpanProcessor to capture
- * traces from Vercel AI SDK's experimental_telemetry feature.
- *
- * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
- */
-import { metrics, SpanStatusCode, trace, } from "@opentelemetry/api";
-import { AsyncLocalStorage } from "async_hooks";
-import { extractMcpErrorText } from "../../../../utils/mcpErrorText.js";
+import { propagateAttributes, setLangfuseTracerProvider, } from "@langfuse/tracing";
+import { context, createContextKey, metrics, ProxyTracerProvider, trace, } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { OTEL_LOG_PREFIX, TRACE_METADATA_CONTEXT_KEY, } from "../../../../constants/telemetry.js";
+import { getExporterRegistry } from "../../../../observability/exporterRegistry.js";
+import { ExporterSpanProcessor } from "../../../../observability/exporterSpanProcessor.js";
+import { LangfuseExporter } from "../../../../observability/exporters/langfuseExporter.js";
+import { spanJsonAttribute } from "../../../../telemetry/attributes.js";
 import { logger } from "../../../../utils/logger.js";
-import { tryImport } from "../../../../utils/tryImport.js";
-import { LANGFUSE_ATTR } from "../../../../telemetry/attributes.js";
-const LOG_PREFIX = "[OpenTelemetry]";
-async function createOtelResource(config, serviceName) {
-    const [{ resourceFromAttributes }, { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION },] = await Promise.all([
-        import("@opentelemetry/resources"),
-        import("@opentelemetry/semantic-conventions"),
-    ]);
-    return resourceFromAttributes({
-        [ATTR_SERVICE_NAME]: serviceName,
-        [ATTR_SERVICE_VERSION]: config.release || "v1.0.0",
-        "deployment.environment": config.environment || "dev",
-    });
-}
-/**
- * Configure OTLP metrics and logs with bounded serialization batches for
- * request-serving processes. Initialization awaits this so a caller may flush
- * or shut down immediately after it returns without racing providers that have
- * not been constructed yet. Signal-specific failures stay non-fatal here.
- */
-async function initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName) {
-    if (!otlpEndpoint) {
-        return;
-    }
-    try {
-        const [{ OTLPMetricExporter }, { MeterProvider, PeriodicExportingMetricReader },] = await Promise.all([
-            import("@opentelemetry/exporter-metrics-otlp-http"),
-            import("@opentelemetry/sdk-metrics"),
-        ]);
-        const metricExporter = new OTLPMetricExporter({
-            url: `${otlpEndpoint}/v1/metrics`,
-        });
-        const metricReader = new PeriodicExportingMetricReader({
-            exporter: metricExporter,
-            exportIntervalMillis: 15000,
-            exportTimeoutMillis: 10000,
-        });
-        meterProvider = new MeterProvider({
-            resource,
-            readers: [metricReader],
-        });
-        metrics.setGlobalMeterProvider(meterProvider);
-        logger.info(`${LOG_PREFIX} OTLP metric exporter added — MeterProvider registered globally`, {
-            endpoint: `${otlpEndpoint}/v1/metrics`,
-            exportIntervalMs: 15000,
-            serviceName,
-            meterProviderType: meterProvider.constructor.name,
-        });
-    }
-    catch (metricsError) {
-        logger.warn(`${LOG_PREFIX} Failed to create OTLP metric exporter (non-fatal)`, {
-            error: metricsError instanceof Error
-                ? metricsError.message
-                : String(metricsError),
-            endpoint: otlpEndpoint,
-        });
-    }
-    try {
-        const [{ OTLPLogExporter }, { BatchLogRecordProcessor, LoggerProvider }] = await Promise.all([
-            import("@opentelemetry/exporter-logs-otlp-http"),
-            import("@opentelemetry/sdk-logs"),
-        ]);
-        const logExporter = new OTLPLogExporter({
-            url: `${otlpEndpoint}/v1/logs`,
-        });
-        const logProcessor = new BatchLogRecordProcessor(logExporter, {
-            maxQueueSize: 2048,
-            // Body logs contain up to 16 KB each. Bound exporter JSON work to
-            // roughly 1 MB per batch instead of an 8 MB main-thread serialization.
-            maxExportBatchSize: 64,
-            scheduledDelayMillis: 2000,
-            exportTimeoutMillis: 30000,
-        });
-        loggerProvider = new LoggerProvider({
-            resource,
-            processors: [logProcessor],
-        });
-        logger.info(`${LOG_PREFIX} OTLP log exporter added — LoggerProvider created`, {
-            endpoint: `${otlpEndpoint}/v1/logs`,
-            serviceName,
-        });
-    }
-    catch (logsError) {
-        logger.warn(`${LOG_PREFIX} Failed to create OTLP log exporter (non-fatal)`, {
-            error: logsError instanceof Error ? logsError.message : String(logsError),
-            endpoint: otlpEndpoint,
-        });
-    }
-}
-const contextStorage = new AsyncLocalStorage();
+import { createLangfuseExporter, isLangfuseEnabled } from "./langfuseSetup.js";
+import { createOtlpMeterProvider, createOtlpSpanProcessor, } from "./otlpSetup.js";
+const MAX_PROPAGATED_CHARS = 200;
+const LANGFUSE_EXPORTER_NAME = "langfuse";
+const TRACE_METADATA_KEY = createContextKey(TRACE_METADATA_CONTEXT_KEY);
 let tracerProvider = null;
 let meterProvider = null;
-let loggerProvider = null;
-let langfuseProcessor = null;
-let isInitialized = false;
-let initializationPromise = null;
-let shutdownPromise = null;
-let isCredentialsValid = false;
-let currentConfig = null;
+let langfuseExporter = null;
 let usingExternalProvider = false;
-let cachedContextEnricher = null;
-/**
- * Check if a real TracerProvider (not ProxyTracerProvider) is already registered
- *
- * IMPORTANT: This function checks the @opentelemetry/api global state as seen by THIS
- * module's bundled copy of @opentelemetry/api. If Neurolink is bundled with its own
- * copy of @opentelemetry/api (which is common in bundled libraries), this function
- * will NOT detect TracerProviders registered by the host application on their
- * @opentelemetry/api instance. Use `useExternalTracerProvider: true` or
- * `autoDetectExternalProvider: true` to explicitly signal external provider usage.
- *
- * @returns true if an external TracerProvider is detected in this module's OTEL instance
- */
-function _hasExternalTracerProvider() {
-    try {
-        const provider = trace.getTracerProvider();
-        if (!provider) {
-            return false;
-        }
-        // ProxyTracerProvider is the default "no-op" provider
-        // Any other provider means someone else registered one
-        const providerName = provider.constructor?.name || "";
-        const isProxy = providerName === "ProxyTracerProvider" ||
-            providerName === "NoopTracerProvider";
-        if (!isProxy) {
-            logger.debug(`${LOG_PREFIX} Detected external TracerProvider: ${providerName}`);
-        }
-        return !isProxy;
-    }
-    catch (error) {
-        logger.warn(`${LOG_PREFIX} Error checking for external TracerProvider`, {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        return false;
-    }
+let started = false;
+let initialized = false;
+let ignoredConfigLogged = false;
+let initializationError = null;
+let terminated = false;
+let terminationLogged = false;
+let unconfiguredLogged = false;
+let holders = 0;
+function hasHostTracerProvider() {
+    const global = trace.getTracerProvider();
+    if (!(global instanceof ProxyTracerProvider)) {
+        return true;
+    }
+    return global.getDelegateTracer("ai") !== undefined;
 }
-/**
- * Parse `ai.toolCall.result` on a Vercel AI SDK tool span and surface any
- * embedded MCP `{ isError: true }` as a Langfuse ERROR + status message.
- */
-function applyToolCallIsErrorStatus(attrs) {
-    const resultAttr = attrs["ai.toolCall.result"];
-    if (typeof resultAttr !== "string" || resultAttr.length === 0) {
-        return;
+function registerLangfuseExporter(config) {
+    const registry = getExporterRegistry();
+    const existing = registry.get(LANGFUSE_EXPORTER_NAME);
+    if (existing) {
+        return existing instanceof LangfuseExporter ? existing : null;
     }
-    let parsed;
-    try {
-        parsed = JSON.parse(resultAttr);
-    }
-    catch {
-        return;
+    const exporter = createLangfuseExporter(config);
+    if (exporter) {
+        registry.register(exporter);
     }
-    if (!parsed ||
-        typeof parsed !== "object" ||
-        parsed.isError !== true) {
-        return;
-    }
-    attrs["langfuse.level"] = "ERROR";
-    // Always set a status_message, even when the MCP payload has non-text or
-    // empty content. Without a fallback the Curator P0-1 gap reappears for
-    // those failures (level=ERROR but statusMessage=null).
-    const errorText = extractMcpErrorText(parsed);
-    const toolName = typeof attrs["ai.toolCall.name"] === "string"
-        ? attrs["ai.toolCall.name"]
-        : "tool";
-    attrs["langfuse.status_message"] =
-        errorText || `MCP ${toolName} returned isError=true`;
+    return exporter;
 }
-/**
- * Map non-ERROR span conditions (content-filter, length, client abort, SDK
- * timeout, empty output) onto Langfuse WARNING/ERROR levels. Mutates `attrs`.
- */
-function applyNonErrorLangfuseLevel(attrs) {
-    const finishReason = attrs["ai.finishReason"] ?? attrs["gen_ai.response.finish_reasons"];
-    const reasonStr = Array.isArray(finishReason)
-        ? finishReason.join(",")
-        : String(finishReason ?? "");
-    if (reasonStr.includes("content-filter") || reasonStr === "length") {
-        attrs["langfuse.level"] = "WARNING";
-        attrs["langfuse.status_message"] =
-            `Generation stopped: finishReason=${reasonStr}`;
-        return;
-    }
-    if (attrs["neurolink.no_output"] === true) {
-        attrs["langfuse.level"] = "WARNING";
-        // Preserve any enriched status message StreamHandler already set
-        // (carries finishReason / token counts via buildNoOutputStatusMessage).
-        // Only fall back to the generic message when none was set upstream.
-        if (typeof attrs["langfuse.status_message"] !== "string") {
-            attrs["langfuse.status_message"] =
-                "Stream produced no output (NoOutputGeneratedError)";
-        }
-        return;
-    }
-    if (reasonStr === "aborted") {
-        attrs["langfuse.level"] = "WARNING";
-        attrs["langfuse.status_message"] = "Generation aborted by client";
-    }
-}
-/**
- * Span processor that enriches spans with user and session context from AsyncLocalStorage
- * Also extracts GenAI semantic convention attributes for Langfuse integration
- *
- * Key features:
- * - Enriches spans with userId, sessionId, conversationId, requestId
- * - Auto-detects operation names from Vercel AI SDK span names
- * - Builds formatted trace names for Langfuse (e.g., "user@email.com:ai.streamText")
- * - Supports custom trace name formats via configuration
- * - Handles wrapper spans by detecting operations from child spans and updating trace name in onEnd()
- */
-class ContextEnricher {
-    /**
-     * Maximum number of detected operations to track to prevent memory leaks.
-     * Once this limit is reached, oldest entries are evicted (FIFO).
-     */
-    static MAX_DETECTED_OPERATIONS = 10000;
-    /**
-     * Track detected operations per trace for wrapper span support.
-     * When a host app creates a wrapper span before AI operations, the wrapper's
-     * onStart() runs before the AI SDK child span exists. We store detected
-     * operations here so we can update the trace name in onEnd().
-     */
-    detectedOperations = new Map();
-    onStart(span, parentContext) {
-        const context = contextStorage.getStore();
-        const userId = context?.userId ?? currentConfig?.userId ?? "guest";
-        const sessionId = context?.sessionId ?? currentConfig?.sessionId;
-        // Get span name for operation auto-detection
-        // (sdk-trace-base's Span type includes the ReadableSpan members)
-        const spanName = span.name;
-        // Determine if auto-detection is enabled for this context
-        const autoDetect = this.shouldAutoDetectOperationName(context);
-        // Resolve operation name: explicit > auto-detected > undefined
-        const operationName = this.resolveOperationName(context?.operationName, spanName, autoDetect);
-        // Store detected AI operations for wrapper span support (optional, defensive).
-        // When a host app creates a wrapper span before calling AI operations,
-        // this allows us to update the trace name in onEnd() with the operation.
-        // Only store the first detected operation for each trace (subsequent operations are ignored).
-        try {
-            if (operationName && spanName?.startsWith("ai.")) {
-                const traceId = span.spanContext?.()?.traceId;
-                if (traceId && !this.detectedOperations.has(traceId)) {
-                    // Evict oldest entry if at capacity to prevent memory leak
-                    if (this.detectedOperations.size >=
-                        ContextEnricher.MAX_DETECTED_OPERATIONS) {
-                        const firstKey = this.detectedOperations.keys().next().value;
-                        if (firstKey) {
-                            this.detectedOperations.delete(firstKey);
-                        }
-                    }
-                    this.detectedOperations.set(traceId, operationName);
-                }
-            }
-        }
-        catch {
-            // Wrapper span support is optional - don't fail if spanContext isn't available
-        }
-        // Build trace name based on priority:
-        // 1. Explicit traceName (100% backward compatible)
-        // 2. Formatted name with userId + operationName
-        // 3. userId only (legacy fallback)
-        const traceName = this.buildTraceName(context?.traceName, userId, operationName);
-        // Apply custom attributes FIRST so internal attributes always take precedence
-        // and cannot be accidentally overwritten by user-provided values
-        if (context?.customAttributes) {
-            for (const [key, value] of Object.entries(context.customAttributes)) {
-                span.setAttribute(key, value);
-            }
-        }
-        // Set user and session attributes (internal - always override custom)
-        if (userId && userId !== "guest") {
-            span.setAttribute("user.id", userId);
-        }
-        if (sessionId) {
-            span.setAttribute("session.id", sessionId);
-        }
-        // Add extended context fields
-        if (context?.conversationId) {
-            span.setAttribute("conversation.id", context.conversationId);
-        }
-        if (context?.requestId) {
-            span.setAttribute("request.id", context.requestId);
-        }
-        const isRootSpan = !trace.getSpan(parentContext);
-        if (traceName && isRootSpan) {
-            span.setAttribute("langfuse.trace.name", traceName);
-            span.setAttribute("trace.name", traceName);
-        }
-        if (isRootSpan && context?.tags && context.tags.length > 0) {
-            span.setAttribute("langfuse.trace.tags", [...context.tags]);
-        }
-        // Set operation name as separate attribute for filtering/analytics
-        if (operationName) {
-            span.setAttribute("gen_ai.operation.name", operationName);
-        }
-        // Add custom metadata as span attributes
-        const metadata = context?.metadata;
-        if (metadata && typeof metadata === "object") {
-            for (const [key, value] of Object.entries(metadata)) {
-                if (value !== undefined && value !== null) {
-                    // Preserve primitive types that OTEL supports natively
-                    if (typeof value === "string" ||
-                        typeof value === "number" ||
-                        typeof value === "boolean") {
-                        if (metadata && isRootSpan) {
-                            span.setAttribute("langfuse.trace.metadata", JSON.stringify(metadata));
-                        }
-                    }
-                    else if (Array.isArray(value) &&
-                        value.every((v) => typeof v === "string" ||
-                            typeof v === "number" ||
-                            typeof v === "boolean")) {
-                        // OTEL supports homogeneous arrays of primitives
-                        span.setAttribute(`metadata.${key}`, JSON.stringify(value));
-                    }
-                    else {
-                        // Fall back to JSON string for complex types
-                        span.setAttribute(`metadata.${key}`, JSON.stringify(value));
-                    }
-                }
-            }
-        }
-    }
-    /**
-     * Determine if auto-detection should be used for operation names
-     */
-    shouldAutoDetectOperationName(context) {
-        // Context-level override takes precedence
-        if (context?.autoDetectOperationName !== undefined) {
-            return context.autoDetectOperationName;
-        }
-        // Fall back to global config (default: true)
-        return currentConfig?.autoDetectOperationName !== false;
-    }
-    /**
-     * Resolve operation name from explicit setting, auto-detection, or undefined
-     */
-    resolveOperationName(explicit, spanName, autoDetect) {
-        // Explicit operation name takes precedence
-        if (explicit) {
-            return explicit;
-        }
-        // Auto-detect from span name if enabled
-        if (autoDetect && spanName) {
-            // Detect Vercel AI SDK operation spans (ai.streamText, ai.generateText, etc.)
-            if (spanName.startsWith("ai.")) {
-                return spanName;
-            }
-            // Detect OpenTelemetry GenAI convention spans (chat, embeddings, text_completion)
-            if (spanName === "chat" ||
-                spanName === "embeddings" ||
-                spanName === "text_completion") {
-                return spanName;
-            }
+function initialize(config) {
+    const langfuse = isLangfuseEnabled(config);
+    const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (!langfuse && !otlpEndpoint) {
+        if (!unconfiguredLogged) {
+            unconfiguredLogged = true;
+            logger.debug(`${OTEL_LOG_PREFIX} Langfuse and OTLP not configured; skipping`);
         }
-        return undefined;
+        return config?.langfuse === false;
     }
-    /**
-     * Build trace name based on format configuration and available data
-     */
-    buildTraceName(explicitTraceName, userId, operationName) {
-        // 1. Explicit traceName always wins (100% backward compatibility)
-        if (explicitTraceName) {
-            return explicitTraceName;
-        }
-        // 2. Build formatted trace name based on config
-        const format = currentConfig?.traceNameFormat ?? "userId:operationName";
-        // Handle custom function format
-        if (typeof format === "function") {
-            return format({ userId, operationName });
+    if (hasHostTracerProvider()) {
+        usingExternalProvider = true;
+        initialized = true;
+        langfuseExporter = langfuse ? registerLangfuseExporter(config) : null;
+        if (langfuseExporter) {
+            logger.info(`${OTEL_LOG_PREFIX} Host TracerProvider detected; Langfuse exporter registered. Add \`createExporterSpanProcessor()\` to the host provider to export NeuroLink spans to it.`);
         }
-        // Handle predefined string formats
-        switch (format) {
-            case "userId:operationName":
-                return operationName ? `${userId}:${operationName}` : userId;
-            case "operationName:userId":
-                return operationName ? `${operationName}:${userId}` : userId;
-            case "operationName":
-                return operationName || userId;
-            case "userId":
-            default:
-                return userId;
+        else {
+            logger.info(`${OTEL_LOG_PREFIX} Host TracerProvider detected; NeuroLink registers no provider and no exporter.`);
         }
+        return true;
     }
-    /**
-     * Called when span ends - extracts GenAI semantic convention attributes
-     * from Vercel AI SDK spans and enriches them for Langfuse.
-     *
-     * Also handles wrapper span support: when a host app creates a wrapper/trace-root
-     * span before AI operations, we update the trace name here with the detected operation.
-     */
-    onEnd(span) {
-        try {
-            // Get span attributes (sdk-trace-base's Span type includes the
-            // ReadableSpan members, so attributes/name/status are directly typed).
-            // Keep the {} fallback: this processor can be attached to an external
-            // app-owned TracerProvider whose span implementation may omit attributes.
-            const attributes = span.attributes ?? {};
-            // Handle wrapper/trace-root spans: update trace name with detected operation
-            // This supports host apps (like Curator) that create wrapper spans before AI calls
-            // This is optional - if spanContext fails, we skip wrapper span support
-            try {
-                const traceId = span.spanContext?.()?.traceId;
-                if (traceId) {
-                    const isTraceRoot = attributes["langfuse.span.type"] === "trace-root";
-                    const detectedOp = this.detectedOperations.get(traceId);
-                    if (isTraceRoot && detectedOp) {
-                        const context = contextStorage.getStore();
-                        const userId = attributes["user.id"] ||
-                            context?.userId ||
-                            currentConfig?.userId ||
-                            "guest";
-                        // Only update if there's no explicit traceName set
-                        const existingTraceName = attributes["langfuse.trace.name"];
-                        const hasExplicitTraceName = context?.traceName ||
-                            (existingTraceName && existingTraceName !== userId);
-                        if (!hasExplicitTraceName) {
-                            const newTraceName = this.buildTraceName(null, userId, detectedOp);
-                            // Update the trace name attribute
-                            span.setAttribute("langfuse.trace.name", newTraceName);
-                            span.setAttribute("trace.name", newTraceName);
-                            span.setAttribute("gen_ai.operation.name", detectedOp);
-                            logger.debug(`${LOG_PREFIX} Updated trace-root span with detected operation`, {
-                                traceId,
-                                operation: detectedOp,
-                                newTraceName,
-                            });
-                        }
-                        // Cleanup the detected operation
-                        this.detectedOperations.delete(traceId);
-                    }
-                }
-            }
-            catch {
-                // Wrapper span support is optional - don't fail if spanContext isn't available
-            }
-            // Check if this is a GenAI span (from Vercel AI SDK)
-            const isGenAISpan = attributes["gen_ai.system"] ||
-                attributes["ai.model.id"] ||
-                attributes["gen_ai.request.model"];
-            if (isGenAISpan) {
-                const model = attributes["gen_ai.request.model"] ||
-                    attributes["ai.model.id"];
-                const provider = attributes["gen_ai.system"] ||
-                    attributes["ai.model.provider"];
-                logger.debug(`${LOG_PREFIX} GenAI span detected`, {
-                    spanName: span.name,
-                    model,
-                    provider,
-                });
-                // L4/L6 fix: Set explicit Langfuse observation attributes so
-                // cost dashboards and model analytics work correctly.
-                try {
-                    const mAttrs = span.attributes;
-                    // L6: Model identity
-                    if (model) {
-                        mAttrs["gen_ai.response.model"] = model;
-                    }
-                    // L4: Usage details — aggregate from AI SDK attributes into a
-                    // structured JSON object that Langfuse can parse for cost analysis.
-                    const inputTokens = attributes["gen_ai.usage.input_tokens"] ??
-                        attributes["ai.usage.promptTokens"];
-                    const outputTokens = attributes["gen_ai.usage.output_tokens"] ??
-                        attributes["ai.usage.completionTokens"];
-                    const totalTokens = attributes["gen_ai.usage.total_tokens"] ??
-                        (inputTokens !== undefined && outputTokens !== undefined
-                            ? inputTokens + outputTokens
-                            : undefined);
-                    const reasoningTokens = attributes["gen_ai.usage.reasoning_tokens"] ??
-                        attributes["ai.usage.reasoningTokens"];
-                    const cachedTokens = attributes["gen_ai.usage.input_cached_tokens"];
-                    if (inputTokens !== undefined || outputTokens !== undefined) {
-                        const usageDetails = {};
-                        if (inputTokens !== undefined) {
-                            usageDetails.input = inputTokens;
-                        }
-                        if (outputTokens !== undefined) {
-                            usageDetails.output = outputTokens;
-                        }
-                        if (totalTokens !== undefined) {
-                            usageDetails.total = totalTokens;
-                        }
-                        if (reasoningTokens !== undefined) {
-                            usageDetails.reasoning_tokens = reasoningTokens;
-                        }
-                        if (cachedTokens !== undefined) {
-                            usageDetails.input_cached_tokens = cachedTokens;
-                        }
-                        mAttrs["langfuse.usage_details"] = JSON.stringify(usageDetails);
-                        logger.debug(`${LOG_PREFIX} Token usage captured`, {
-                            inputTokens,
-                            outputTokens,
-                            totalTokens,
-                        });
-                    }
-                    // L7: Model parameters — surface temperature and max_tokens for
-                    // generation tuning visibility.
-                    const temperature = attributes["gen_ai.request.temperature"] ??
-                        attributes["ai.settings.temperature"];
-                    const maxTokens = attributes["gen_ai.request.max_tokens"] ??
-                        attributes["ai.settings.maxTokens"];
-                    const topP = attributes["gen_ai.request.top_p"] ??
-                        attributes["ai.settings.topP"];
-                    if (temperature !== undefined ||
-                        maxTokens !== undefined ||
-                        topP !== undefined) {
-                        const params = {};
-                        if (temperature !== undefined) {
-                            params.temperature = temperature;
-                        }
-                        if (maxTokens !== undefined) {
-                            params.max_tokens = maxTokens;
-                        }
-                        if (topP !== undefined) {
-                            params.top_p = topP;
-                        }
-                        mAttrs["gen_ai.request.model_parameters"] = JSON.stringify(params);
-                    }
-                }
-                catch {
-                    // Read-only attributes — cannot enrich; Pipeline A will still
-                    // export the raw GenAI attributes that Langfuse can parse.
-                }
-            }
-            // P8 fix: Propagate error status to Langfuse-consumable attributes.
-            // OTel ReadableSpan attributes may be readonly at onEnd() time; the type
-            // cast attempts late mutation. LangfuseSpanProcessor runs after
-            // ContextEnricher in the spanProcessors array and reads these attributes,
-            // so setting them here allows Langfuse to surface the correct level and
-            // status message on the trace/generation.
-            const readableStatus = span.status;
-            try {
-                const mutableAttrs = span.attributes;
-                // Curator P0-1/P0-2: detect MCP isError pattern on AI SDK tool call spans.
-                // The AI SDK's `ai.toolCall` span stays status=UNSET when the tool
-                // *returns* { isError:true } (no exception thrown), so Langfuse sees
-                // level=DEFAULT and no status message. Parse the stringified result
-                // and surface the embedded error text.
-                if (span.name === "ai.toolCall" &&
-                    readableStatus?.code !== SpanStatusCode.ERROR) {
-                    applyToolCallIsErrorStatus(mutableAttrs);
-                }
-                if (readableStatus?.code === SpanStatusCode.ERROR) {
-                    mutableAttrs["langfuse.level"] = "ERROR";
-                    if (readableStatus.message) {
-                        mutableAttrs["langfuse.status_message"] = readableStatus.message;
-                    }
-                }
-                else if (mutableAttrs["langfuse.level"] === undefined) {
-                    applyNonErrorLangfuseLevel(mutableAttrs);
-                }
-            }
-            catch {
-                // Readonly enforcement by OTel SDK — mutation not possible; log at debug.
-                logger.debug(`${LOG_PREFIX} Could not set langfuse.level on span (read-only attributes)`);
-            }
-        }
-        catch (error) {
-            // Don't fail span processing on errors
-            logger.debug(`${LOG_PREFIX} Error reading span attributes`, {
-                error: error instanceof Error ? error.message : String(error),
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "ai-service",
+    });
+    const exporter = langfuse ? registerLangfuseExporter(config) : null;
+    const otlpProcessor = otlpEndpoint
+        ? createOtlpSpanProcessor(otlpEndpoint)
+        : null;
+    const spanProcessors = [
+        new ExporterSpanProcessor(getExporterRegistry()),
+    ];
+    if (otlpProcessor) {
+        spanProcessors.push(otlpProcessor);
+    }
+    const provider = new NodeTracerProvider({ resource, spanProcessors });
+    provider.register({ propagator: new W3CTraceContextPropagator() });
+    setLangfuseTracerProvider(provider);
+    tracerProvider = provider;
+    langfuseExporter = exporter;
+    meterProvider = otlpEndpoint
+        ? createOtlpMeterProvider(otlpEndpoint, resource)
+        : null;
+    usingExternalProvider = false;
+    initialized = true;
+    logger.info(`${OTEL_LOG_PREFIX} Observability initialized`, {
+        langfuseEnabled: exporter !== null,
+        otlpEnabled: otlpProcessor !== null,
+    });
+    return true;
+}
+async function stop() {
+    const provider = tracerProvider;
+    const meters = meterProvider;
+    const hostExporter = usingExternalProvider ? langfuseExporter : null;
+    terminated = true;
+    tracerProvider = null;
+    meterProvider = null;
+    langfuseExporter = null;
+    usingExternalProvider = false;
+    started = false;
+    initialized = false;
+    initializationError = null;
+    if (provider) {
+        setLangfuseTracerProvider(null);
+    }
+    if (meters) {
+        metrics.disable();
+    }
+    if (hostExporter) {
+        getExporterRegistry().unregister(hostExporter.getName());
+    }
+    const results = await Promise.allSettled([
+        provider?.shutdown(),
+        hostExporter?.shutdown(),
+        meters?.shutdown(),
+    ]);
+    for (const result of results) {
+        if (result.status === "rejected") {
+            logger.error(`${OTEL_LOG_PREFIX} Shutdown failed`, {
+                error: result.reason instanceof Error
+                    ? result.reason.message
+                    : String(result.reason),
             });
         }
     }
-    shutdown() {
-        // Clean up tracked operations to prevent memory leaks
-        this.detectedOperations.clear();
-        return Promise.resolve();
-    }
-    forceFlush() {
-        return Promise.resolve();
-    }
-}
-async function createLangfuseProcessor(config) {
-    const mod = await tryImport("@langfuse/otel", "Langfuse observability");
-    return new mod.LangfuseSpanProcessor({
-        publicKey: config.publicKey,
-        secretKey: config.secretKey,
-        baseUrl: config.baseUrl || "https://cloud.langfuse.com",
-        environment: config.environment || "dev",
-        release: config.release || "v1.0.0",
-        // Curator P1-3: skip internal wrapper spans that duplicate ai.toolCall /
-        // ai.generateText observations in Langfuse. Wrappers still emit OTel spans
-        // for internal metrics; they just aren't forwarded to Langfuse.
-        shouldExportSpan: langfuseShouldExportSpan,
-    });
-}
-/**
- * True when a span is an internal NeuroLink wrapper that should NOT be sent to
- * Langfuse. Internal wrappers carry the `langfuse.internal: true` attribute.
- *
- * Exposed so host apps that bring their own `LangfuseSpanProcessor` (e.g.
- * `skipLangfuseSpanProcessor: true`, or manual registration on an existing
- * TracerProvider) can apply the same filter and avoid duplicate observations.
- */
-export function isLangfuseInternalSpan(span) {
-    return span.attributes?.["langfuse.internal"] === true;
 }
 /**
- * Drop-in `shouldExportSpan` predicate for a `LangfuseSpanProcessor` that
- * filters out NeuroLink internal wrapper spans.
- *
- * Usage in host apps:
- * ```ts
- * import { langfuseShouldExportSpan } from "@juspay/neurolink";
- * new LangfuseSpanProcessor({ ..., shouldExportSpan: langfuseShouldExportSpan });
- * ```
+ * @description Starts NeuroLink's tracing once per process, synchronously. Every span created through the shared tracers calls it first, so direct provider calls without a NeuroLink instance are traced too. Langfuse is enabled unless `config.langfuse` is `false`, when an options object is given or `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are set; an OTLP exporter is added when `OTEL_EXPORTER_OTLP_ENDPOINT` is set. When the host already registered a TracerProvider no provider is created; the Langfuse exporter, if configured, is registered on the shared exporter registry and the host adds `createExporterSpanProcessor()` to its provider. The first call that finds tracing configured decides the setup and a later `config` is ignored; calls made before anything is configured start nothing, so a later config or environment can still start tracing, unless `langfuse: false` was passed. After `shutdownOpenTelemetry` it does nothing.
+ * @param config {ObservabilityConfig | undefined} - Observability options, honoured only when this is the first call.
+ * @returns {void} Nothing; a failed setup is logged and recorded in `getLangfuseHealthStatus`.
  */
-export function langfuseShouldExportSpan({ otelSpan, }) {
-    return !isLangfuseInternalSpan(otelSpan);
-}
-async function initializeExternalOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds) {
-    if (langfuseRequested && !hasLangfuseCreds) {
-        if (!otlpEndpoint) {
-            logger.warn(`${LOG_PREFIX} External provider mode requested Langfuse but credentials are missing, and no OTLP endpoint is configured; skipping initialization`, {
-                hasPublicKey: !!config?.publicKey,
-                hasSecretKey: !!config?.secretKey,
-            });
-            isInitialized = true;
-            isCredentialsValid = false;
-            return;
-        }
-        logger.warn(`${LOG_PREFIX} External provider mode missing Langfuse credentials; continuing with OTLP-only metrics/logs`, {
-            hasPublicKey: !!config?.publicKey,
-            hasSecretKey: !!config?.secretKey,
-            otlpEnabled: true,
-        });
-    }
-    try {
-        currentConfig = config;
-        isCredentialsValid = hasLangfuseCreds;
-        langfuseProcessor =
-            langfuseRequested && hasLangfuseCreds
-                ? await createLangfuseProcessor(config)
-                : null;
-        usingExternalProvider = true;
-        await initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName);
-        isInitialized = true;
-        try {
-            const globalProvider = trace.getTracerProvider();
-            const provider = globalProvider;
-            if (globalProvider && typeof provider.addSpanProcessor === "function") {
-                provider.addSpanProcessor(new ContextEnricher());
-                // Auto-detect: skip if consumer already registered a LangfuseSpanProcessor.
-                //
-                // Detection strategy (ordered by robustness):
-                // 1. Duck-type check for Langfuse-specific public member
-                //    (`langfuseClient` property) — survives minification.
-                // 2. `constructor.name === "LangfuseSpanProcessor"` — last resort,
-                //    brittle under minification or bundler renaming.
-                //
-                // NOTE: `_registeredSpanProcessors` is an internal OpenTelemetry field.
-                // If the OTel SDK removes or renames it, the array defaults to [] and
-                // `hasExistingLangfuse` is false — NeuroLink registers its own processor
-                // (same behavior as before this check). Consumers can always force skip
-                // via `skipLangfuseSpanProcessor: true`.
-                const existingProcessors = provider
-                    ._registeredSpanProcessors ?? [];
-                const hasExistingLangfuse = existingProcessors.some((p) => {
-                    if (p === null || p === undefined || typeof p !== "object") {
-                        return false;
-                    }
-                    // Duck-type: Langfuse processor exposes a langfuseClient property
-                    if ("langfuseClient" in p) {
-                        return true;
-                    }
-                    // Fallback: constructor name (brittle under minification)
-                    return (p.constructor?.name ===
-                        "LangfuseSpanProcessor");
-                });
-                const skipLangfuse = config.skipLangfuseSpanProcessor === true ||
-                    !langfuseProcessor ||
-                    hasExistingLangfuse;
-                if (hasExistingLangfuse && !config.skipLangfuseSpanProcessor) {
-                    logger.info(`${LOG_PREFIX} Auto-detected existing LangfuseSpanProcessor — skipping SDK registration to avoid duplicates`);
-                }
-                if (!skipLangfuse && langfuseProcessor) {
-                    provider.addSpanProcessor(langfuseProcessor);
-                }
-                logger.info(`${LOG_PREFIX} Auto-registered processors with global TracerProvider`, {
-                    processors: skipLangfuse
-                        ? ["ContextEnricher"]
-                        : ["ContextEnricher", "LangfuseSpanProcessor"],
-                    reason: "External provider mode with auto-registration",
-                    skippedLangfuseSpanProcessor: skipLangfuse,
-                });
-                return;
-            }
-            logger.info(`${LOG_PREFIX} Using external TracerProvider mode`, {
-                reason: config.useExternalTracerProvider
-                    ? "useExternalTracerProvider=true"
-                    : "autoDetectExternalProvider=true (trusting host signal)",
-                instructions: "Add span processors to your TracerProvider using getSpanProcessors()",
-            });
-            logger.info(`${LOG_PREFIX} Span processors ready for external use`, {
-                processors: langfuseProcessor
-                    ? ["ContextEnricher", "LangfuseSpanProcessor"]
-                    : ["ContextEnricher"],
-                usage: "import { getSpanProcessors } from '@juspay/neurolink'",
-            });
+export function ensureTelemetry(config) {
+    if (terminated) {
+        if (!terminationLogged) {
+            terminationLogged = true;
+            logger.debug(`${OTEL_LOG_PREFIX} Telemetry was shut down for this process; not restarting`);
         }
-        catch (autoRegisterError) {
-            logger.warn(`${LOG_PREFIX} Auto-registration failed, manual registration required`, {
-                error: autoRegisterError instanceof Error
-                    ? autoRegisterError.message
-                    : String(autoRegisterError),
-                instructions: "Add span processors to your TracerProvider using getSpanProcessors()",
-            });
-        }
-    }
-    catch (error) {
-        logger.error(`${LOG_PREFIX} Failed to create span processor for external mode`, {
-            error: error instanceof Error ? error.message : String(error),
-            stack: error instanceof Error ? error.stack : undefined,
-        });
-        isInitialized = true;
+        return;
     }
-}
-async function initializeStandaloneOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds) {
-    if ((!langfuseRequested || !hasLangfuseCreds) && !otlpEndpoint) {
-        if (langfuseRequested && !hasLangfuseCreds) {
-            logger.warn(`${LOG_PREFIX} Langfuse requested but credentials are missing, and no OTLP endpoint is configured; skipping initialization`, {
-                hasPublicKey: !!config.publicKey,
-                hasSecretKey: !!config.secretKey,
-            });
-        }
-        else {
-            logger.debug(`${LOG_PREFIX} Langfuse disabled and OTLP endpoint missing, skipping initialization`);
+    if (started) {
+        if (config && !ignoredConfigLogged) {
+            ignoredConfigLogged = true;
+            logger.debug(`${OTEL_LOG_PREFIX} Telemetry already started; ignoring observability config`);
         }
-        isInitialized = true;
         return;
     }
-    if (langfuseRequested && !hasLangfuseCreds) {
-        logger.warn(`${LOG_PREFIX} Langfuse requested but credentials are missing; continuing with OTLP-only telemetry`, {
-            hasPublicKey: !!config.publicKey,
-            hasSecretKey: !!config.secretKey,
-            otlpEnabled: !!otlpEndpoint,
-        });
-    }
+    initializationError = null;
     try {
-        currentConfig = config;
-        isCredentialsValid = hasLangfuseCreds;
-        langfuseProcessor =
-            langfuseRequested && hasLangfuseCreds
-                ? await createLangfuseProcessor(config)
-                : null;
-        logger.debug(`${LOG_PREFIX} Standalone observability mode`, {
-            langfuseEnabled: !!langfuseProcessor,
-            otlpEnabled: !!otlpEndpoint,
-            baseUrl: config.baseUrl || "https://cloud.langfuse.com",
-            environment: config.environment || "dev",
-        });
-        const spanProcessors = [new ContextEnricher()];
-        if (langfuseProcessor) {
-            spanProcessors.push(langfuseProcessor);
-        }
-        if (otlpEndpoint) {
-            try {
-                const [{ OTLPTraceExporter }, { BatchSpanProcessor }] = await Promise.all([
-                    import("@opentelemetry/exporter-trace-otlp-http"),
-                    import("@opentelemetry/sdk-trace-base"),
-                ]);
-                const otlpExporter = new OTLPTraceExporter({
-                    url: `${otlpEndpoint}/v1/traces`,
-                });
-                spanProcessors.push(new BatchSpanProcessor(otlpExporter, {
-                    maxQueueSize: 2048,
-                    maxExportBatchSize: 512,
-                    scheduledDelayMillis: 1000,
-                    exportTimeoutMillis: 30000,
-                }));
-                logger.info(`${LOG_PREFIX} OTLP trace exporter added`, {
-                    endpoint: `${otlpEndpoint}/v1/traces`,
-                    serviceName,
-                });
-            }
-            catch (otlpError) {
-                logger.warn(`${LOG_PREFIX} Failed to create OTLP exporter (non-fatal)`, {
-                    error: otlpError instanceof Error
-                        ? otlpError.message
-                        : String(otlpError),
-                    endpoint: otlpEndpoint,
-                });
-            }
-        }
-        const [{ NodeTracerProvider }, { W3CTraceContextPropagator }] = await Promise.all([
-            import("@opentelemetry/sdk-trace-node"),
-            import("@opentelemetry/core"),
-        ]);
-        tracerProvider = new NodeTracerProvider({ resource, spanProcessors });
-        tracerProvider.register({
-            propagator: new W3CTraceContextPropagator(),
-        });
-        usingExternalProvider = false;
-        await initializeOtlpMetricsAndLogs(resource, otlpEndpoint, serviceName);
-        isInitialized = true;
-        logger.info(`${LOG_PREFIX} Observability initialized`, {
-            baseUrl: config.baseUrl || "https://cloud.langfuse.com",
-            environment: config.environment || "dev",
-            release: config.release || "v1.0.0",
-            mode: "standalone",
-            langfuseEnabled: !!langfuseProcessor,
-            otlpEnabled: !!otlpEndpoint,
-            serviceName,
-        });
+        started = initialize(config);
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const isDuplicateError = errorMessage.includes("duplicate registration") ||
-            errorMessage.includes("already registered") ||
-            errorMessage.includes("already set");
-        if (isDuplicateError) {
-            logger.warn(`${LOG_PREFIX} TracerProvider already registered, switching to external mode`, {
-                error: errorMessage,
-                recommendation: "Set useExternalTracerProvider=true or autoDetectExternalProvider=true in config",
-            });
-            usingExternalProvider = true;
-            isInitialized = true;
-            return;
-        }
-        logger.error(`${LOG_PREFIX} Initialization failed`, {
-            error: errorMessage,
-            stack: error instanceof Error ? error.stack : undefined,
+        started = true;
+        initializationError =
+            error instanceof Error ? error.message : String(error);
+        logger.error(`${OTEL_LOG_PREFIX} Initialization failed`, {
+            error: initializationError,
         });
-        throw error;
     }
 }
 /**
- * Initialize OpenTelemetry once and let concurrent callers share the work.
- *
- * NeuroLink constructors intentionally start this asynchronously. Keeping the
- * in-flight promise here lets another constructor join it and lets an immediate
- * flush or shutdown wait for the same initialization before touching providers.
+ * @description Registers a holder of the process-wide telemetry and starts it if needed. Pair every call with `releaseTelemetry`.
+ * @param config {ObservabilityConfig | undefined} - Observability options forwarded to `ensureTelemetry`.
+ * @returns {void} Nothing.
  */
-export async function initializeOpenTelemetry(config) {
-    if (shutdownPromise) {
-        // A shutdown already in flight is what made isInitialized/
-        // initializationPromise true or null in the first place; either reading
-        // is stale until it actually finishes. Waiting here means this call sees
-        // the settled post-teardown state — nothing initialized, nothing
-        // pending — and falls through to build fresh providers, rather than
-        // returning early on a flag that is about to flip out from under it.
-        await shutdownPromise;
-    }
-    if (isInitialized) {
-        currentConfig = config;
-        logger.debug(`${LOG_PREFIX} Already initialized, config updated`, {
-            usingExternalProvider,
-            hasLangfuseProcessor: !!langfuseProcessor,
-            hasTraceNameFormat: typeof config.traceNameFormat === "function",
-        });
-        return;
-    }
-    if (initializationPromise) {
-        await initializationPromise;
-        currentConfig = config;
-        return;
-    }
-    const pending = initializeOpenTelemetryOnce(config);
-    initializationPromise = pending;
-    try {
-        await pending;
-    }
-    finally {
-        if (initializationPromise === pending) {
-            initializationPromise = null;
-        }
-    }
+export function acquireTelemetry(config) {
+    holders++;
+    ensureTelemetry(config);
 }
 /**
- * Initialize OpenTelemetry with Langfuse span processor
- *
- * This connects Vercel AI SDK's experimental_telemetry to Langfuse by:
- * 1. Creating LangfuseSpanProcessor with Langfuse credentials
- * 2. Creating a NodeTracerProvider with service metadata and span processor
- * 3. Registering the provider globally for AI SDK to use
- *
- * NEW: If useExternalTracerProvider is true or autoDetectExternalProvider detects
- * an existing provider, steps 2 and 3 are skipped. The span processors are still
- * created and can be retrieved via getSpanProcessors().
- *
- * @param config - Langfuse configuration passed from parent application
+ * @description Releases one holder registered by `acquireTelemetry` and flushes pending spans. The provider stays registered for the process so cached tracers keep working and later instances reuse it.
+ * @returns {Promise<void>} Resolves when pending spans are flushed.
+ * @throws {Error} When any provider fails to flush.
  */
-async function initializeOpenTelemetryOnce(config) {
-    // FIRST: Check for external provider mode - bypasses enabled check
-    // NOTE: When autoDetectExternalProvider is true, we trust the flag directly rather than
-    // calling hasExternalTracerProvider(). This is because Neurolink may bundle its own copy
-    // of @opentelemetry/api, which has a separate global state from the host application.
-    // The hasExternalTracerProvider() check would query Neurolink's bundled @opentelemetry/api
-    // global state (which has no provider registered), not the host's global state.
-    // By trusting autoDetectExternalProvider=true, we let the host application signal that
-    // it has already registered a TracerProvider.
-    const shouldUseExternal = config?.useExternalTracerProvider === true ||
-        config?.autoDetectExternalProvider === true;
-    const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
-    const langfuseRequested = config?.enabled === true;
-    const hasLangfuseCreds = !!config.publicKey && !!config.secretKey;
-    const serviceName = process.env.OTEL_SERVICE_NAME || "neurolink";
-    const resource = await createOtelResource(config, serviceName);
-    if (shouldUseExternal) {
-        await initializeExternalOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds);
-        return;
-    }
-    await initializeStandaloneOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds);
+export async function releaseTelemetry() {
+    holders = Math.max(0, holders - 1);
+    await flushOpenTelemetry();
 }
 /**
- * Flush all pending spans to Langfuse
+ * @description Exports pending spans and metrics from the providers NeuroLink owns and flushes its Langfuse exporter. A host provider is never flushed.
+ * @returns {Promise<void>} Resolves when every owned provider has flushed.
+ * @throws {Error} When any provider fails to flush.
  */
 export async function flushOpenTelemetry() {
-    if (initializationPromise) {
-        try {
-            await initializationPromise;
-        }
-        catch {
-            // Initialization owns its error logging; a failed init leaves nothing
-            // initialized, so the check below skips the flush as it always has.
-        }
-    }
-    if (!isInitialized) {
-        logger.debug(`${LOG_PREFIX} Not initialized, skipping flush`);
-        return;
-    }
-    const failures = [];
-    if (langfuseProcessor) {
-        try {
-            logger.info(`${LOG_PREFIX} Flushing Langfuse spans...`);
-            await langfuseProcessor.forceFlush();
-        }
-        catch (error) {
-            failures.push({ signal: "langfuse", error });
-            logger.error(`${LOG_PREFIX} Langfuse flush failed`, {
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-            });
-        }
-    }
-    else {
-        logger.debug(`${LOG_PREFIX} Langfuse disabled, skipping Langfuse flush`);
-    }
-    if (tracerProvider && !usingExternalProvider) {
-        try {
-            logger.info(`${LOG_PREFIX} Flushing OTLP traces...`);
-            await tracerProvider.forceFlush();
-        }
-        catch (error) {
-            failures.push({ signal: "traces", error });
-            logger.error(`${LOG_PREFIX} Trace flush failed`, {
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-            });
-        }
-    }
-    else {
-        logger.debug(`${LOG_PREFIX} No TracerProvider to flush`);
-    }
-    if (meterProvider) {
-        try {
-            logger.info(`${LOG_PREFIX} Flushing OTLP metrics...`);
-            await meterProvider.forceFlush();
-        }
-        catch (error) {
-            failures.push({ signal: "metrics", error });
-            logger.error(`${LOG_PREFIX} Metric flush failed`, {
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-            });
-        }
-    }
-    else {
-        logger.debug(`${LOG_PREFIX} No MeterProvider to flush`);
-    }
-    if (loggerProvider) {
-        try {
-            logger.info(`${LOG_PREFIX} Flushing OTLP logs...`);
-            await loggerProvider.forceFlush();
-        }
-        catch (error) {
-            failures.push({ signal: "logs", error });
-            logger.error(`${LOG_PREFIX} Log flush failed`, {
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-            });
-        }
-    }
-    else {
-        logger.debug(`${LOG_PREFIX} No LoggerProvider to flush`);
-    }
-    if (failures.length > 0) {
-        throw new Error(`${LOG_PREFIX} Flush failed for: ${failures.map((f) => f.signal).join(", ")}`);
+    const results = await Promise.allSettled([
+        tracerProvider?.forceFlush(),
+        usingExternalProvider ? langfuseExporter?.flush() : undefined,
+        meterProvider?.forceFlush(),
+    ]);
+    const failed = results.filter((result) => result.status === "rejected");
+    if (failed.length > 0) {
+        throw new Error(`${OTEL_LOG_PREFIX} Flush failed`, {
+            cause: failed.map((result) => result.reason),
+        });
     }
-    logger.info(`${LOG_PREFIX} Flush complete`);
 }
 /**
- * Shutdown OpenTelemetry and Langfuse span processor
- *
- * Concurrent callers share one in-flight teardown, the same way concurrent
- * initializers share one in-flight `initializeOpenTelemetry`: a second
- * shutdown call joins the first instead of tearing down the same provider
- * instances a second time.
+ * @description Terminally shuts down the providers NeuroLink owns once no `acquireTelemetry` holder remains; while holders remain it only flushes. Telemetry cannot be restarted in this process afterwards. A host provider is never shut down; with one, only NeuroLink's Langfuse exporter is shut down and unregistered.
+ * @returns {Promise<void>} Resolves when telemetry is flushed or shut down.
  */
 export async function shutdownOpenTelemetry() {
-    if (shutdownPromise) {
-        await shutdownPromise;
+    if (holders > 0) {
+        await flushOpenTelemetry();
         return;
     }
-    const pending = shutdownOpenTelemetryOnce();
-    shutdownPromise = pending;
-    try {
-        await pending;
-    }
-    finally {
-        if (shutdownPromise === pending) {
-            shutdownPromise = null;
-        }
-    }
-}
-async function shutdownOpenTelemetryOnce() {
-    if (initializationPromise) {
-        try {
-            await initializationPromise;
-        }
-        catch {
-            // Initialization owns its error logging. Continue so any provider it
-            // created before failing is still shut down below.
-        }
-    }
-    try {
-        // Only shutdown tracerProvider if we created it
-        if (tracerProvider && !usingExternalProvider) {
-            await tracerProvider.shutdown();
-        }
-        // Always shutdown the Langfuse processor
-        if (langfuseProcessor) {
-            await langfuseProcessor.shutdown();
-        }
-        // Shutdown cached ContextEnricher
-        if (cachedContextEnricher) {
-            await cachedContextEnricher.shutdown();
-        }
-        // Shutdown MeterProvider if we created it
-        if (meterProvider) {
-            await meterProvider.shutdown();
-        }
-        // Shutdown LoggerProvider if we created it
-        if (loggerProvider) {
-            await loggerProvider.shutdown();
-        }
-        tracerProvider = null;
-        meterProvider = null;
-        loggerProvider = null;
-        langfuseProcessor = null;
-        cachedContextEnricher = null;
-        isInitialized = false;
-        isCredentialsValid = false;
-        usingExternalProvider = false;
-        logger.debug(`${LOG_PREFIX} Shutdown complete`);
-    }
-    catch (error) {
-        logger.error(`${LOG_PREFIX} Shutdown failed`, {
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-}
-/**
- * Get the Langfuse span processor
- */
-export function getLangfuseSpanProcessor() {
-    return langfuseProcessor;
+    await stop();
 }
 /**
- * Get the tracer provider
- */
-export function getTracerProvider() {
-    return tracerProvider;
-}
-/**
- * Get the logger provider for emitting OTLP log records.
- * Returns null if OTLP is not configured or LoggerProvider was not created.
- */
-export function getLoggerProvider() {
-    return loggerProvider;
-}
-/**
- * Check if OpenTelemetry is initialized
+ * @description Reports whether NeuroLink's tracing is active, either on its own provider or alongside a host provider.
+ * @returns {boolean} `true` once `ensureTelemetry` has set tracing up.
  */
 export function isOpenTelemetryInitialized() {
-    return isInitialized;
+    return initialized;
 }
 /**
- * Get health status for Langfuse observability
- *
- * @returns Health status object with initialization and configuration details
+ * @description Summarizes the Langfuse export state for health checks.
+ * @returns {{ isHealthy: boolean; initialized: boolean; hasProcessor: boolean; usingExternalProvider: boolean; error?: string }} `isHealthy` and `hasProcessor` are `true` only while a Langfuse exporter is registered, on NeuroLink's own provider or beside a host provider (where it still needs `createExporterSpanProcessor()` on the host provider to receive spans); `error` carries the message of a failed initialization.
  */
 export function getLangfuseHealthStatus() {
     return {
-        isHealthy: !!(currentConfig?.enabled &&
-            isInitialized &&
-            isCredentialsValid &&
-            langfuseProcessor !== null),
-        initialized: isInitialized,
-        credentialsValid: isCredentialsValid,
-        enabled: currentConfig?.enabled || false,
-        hasProcessor: langfuseProcessor !== null,
+        isHealthy: initialized && langfuseExporter !== null,
+        initialized,
+        hasProcessor: langfuseExporter !== null,
         usingExternalProvider,
-        config: currentConfig
-            ? {
-                baseUrl: currentConfig.baseUrl || "https://cloud.langfuse.com",
-                environment: currentConfig.environment || "dev",
-                release: currentConfig.release || "v1.0.0",
-            }
-            : undefined,
+        ...(initializationError !== null && { error: initializationError }),
     };
 }
 /**
- * Set user and session context for Langfuse spans in the current async context
- *
- * Merges the provided context with existing AsyncLocalStorage context. If a callback is provided,
- * the context is scoped to that callback execution and returns the callback's result.
- * Without a callback, the context applies to the current execution context and its children.
- *
- * Uses AsyncLocalStorage to properly scope context per request, avoiding race conditions
- * in concurrent scenarios.
- *
- * @param context - Object containing context fields to merge with existing context
- * @param callback - Optional callback to run within the context scope. If omitted, context applies to current execution
- * @returns The callback's return value if provided, otherwise void
- *
- * @example
- * // With callback - returns the result
- * const result = await setLangfuseContext({ userId: "user123" }, async () => {
- *   return await generateText({ model: "gpt-4", prompt: "Hello" });
- * });
- *
- * @example
- * // Without callback - sets context for current execution
- * await setLangfuseContext({ sessionId: "session456", traceName: "chat-completion" });
+ * @description Reads the full trace metadata that `setLangfuseContext` stored on a context.
+ * @param ctx {Context} - Context to read, normally the active one.
+ * @returns {Record<string, SpanContent>} Metadata set by enclosing `setLangfuseContext` calls, inner keys winning; empty when none was set.
  */
-export async function setLangfuseContext(context, callback) {
-    const currentContext = contextStorage.getStore() || {};
-    const newContext = {
-        userId: context.userId !== undefined ? context.userId : currentContext.userId,
-        sessionId: context.sessionId !== undefined
-            ? context.sessionId
-            : currentContext.sessionId,
-        conversationId: context.conversationId !== undefined
-            ? context.conversationId
-            : currentContext.conversationId,
-        requestId: context.requestId !== undefined
-            ? context.requestId
-            : currentContext.requestId,
-        traceName: context.traceName !== undefined
-            ? context.traceName
-            : currentContext.traceName,
-        metadata: context.metadata !== undefined
-            ? context.metadata
-            : currentContext.metadata,
-        tags: context.tags !== undefined ? context.tags : currentContext.tags,
-        // Operation name support
-        operationName: context.operationName !== undefined
-            ? context.operationName
-            : currentContext.operationName,
-        autoDetectOperationName: context.autoDetectOperationName !== undefined
-            ? context.autoDetectOperationName
-            : currentContext.autoDetectOperationName,
-        // Custom attributes support
-        customAttributes: context.customAttributes !== undefined
-            ? context.customAttributes
-            : currentContext.customAttributes,
-    };
-    if (callback) {
-        return await contextStorage.run(newContext, callback);
-    }
-    else {
-        contextStorage.enterWith(newContext);
-    }
+export function traceMetadataFromContext(ctx) {
+    const stored = ctx.getValue(TRACE_METADATA_KEY);
+    return stored && typeof stored === "object"
+        ? stored
+        : {};
 }
 /**
- * Get the current Langfuse context from AsyncLocalStorage
- *
- * Returns the current context including userId, sessionId, conversationId,
- * requestId, traceName, and metadata. Returns undefined if no context is set.
- *
- * @returns The current LangfuseContext or undefined
- *
+ * @description Runs `fn` with trace attributes propagated to every span it creates. `conversationId` and `requestId` become metadata; empty values are dropped. Metadata values of up to 200 characters once stringified are on every observation; longer values and arrays are recorded in full on the trace only, written by the trace root.
+ * @param params {NeurolinkTraceContext} - User, session, trace name, tags and metadata for the trace.
+ * @param fn {() => T} - Work to run inside the propagated context.
+ * @returns {T} Whatever `fn` returns.
  * @example
- * const context = getLangfuseContext();
- * console.log(context?.userId, context?.sessionId);
+ * await setLangfuseContext({ userId: "u1", sessionId: "s1" }, () => neurolink.generate({ input: { text: "hi" } }));
  */
-export function getLangfuseContext() {
-    return contextStorage.getStore();
-}
-/**
- * Fill a span's Langfuse identity when the caller's context would otherwise
- * fall back to "guest". Identity (user.id / session.id) is set additively —
- * only fields ambient context didn't already provide, so a host's own context
- * is never overridden. trace.name (the title) is rescued only when no ambient
- * name source exists AND this span is the trace root, mirroring
- * ContextEnricher.onStart so a host wrapper span isn't relabelled.
- */
-export function stampGuestRescueIdentity(span, callContext, isRootSpan) {
-    const ambient = getLangfuseContext();
-    const ctx = callContext;
-    const userId = typeof ctx?.userId === "string" && ctx.userId ? ctx.userId : undefined;
-    const sessionId = typeof ctx?.sessionId === "string" && ctx.sessionId
-        ? ctx.sessionId
-        : undefined;
-    // Title: the trace name comes from traceName ?? userId, so only rescue it
-    // from "guest" when ambient has neither, and only on the trace root.
-    if (isRootSpan && !ambient?.traceName && !ambient?.userId) {
-        const traceName = typeof ctx?.traceName === "string" && ctx.traceName
-            ? ctx.traceName
-            : userId;
-        if (traceName) {
-            span.setAttribute(LANGFUSE_ATTR.TRACE_NAME, traceName);
-            span.setAttribute("trace.name", traceName);
-        }
-    }
-    // Identity: additive — set each field only where ambient didn't.
-    if (userId && !ambient?.userId) {
-        span.setAttribute("user.id", userId);
-    }
-    if (sessionId && !ambient?.sessionId) {
-        span.setAttribute("session.id", sessionId);
-    }
-}
-/**
- * Capture the current Langfuse AsyncLocalStorage context and return a wrapper
- * that re-enters that context when executing the provided callback.
- *
- * This is essential for preserving trace context across async boundaries that
- * break the automatic ALS propagation chain, such as `setImmediate()`,
- * `setTimeout()`, or event-emitter callbacks. Without this, spans created
- * inside those callbacks become orphaned traces in Langfuse.
- *
- * **How it works:**
- * 1. Captures the current ALS store at call time (synchronously).
- * 2. Returns an async function that, when invoked, re-enters the captured
- *    context via `contextStorage.run()` before executing the callback.
- * 3. If no context exists at capture time, the callback runs without
- *    ALS wrapping (no-op passthrough).
- *
- * @param fn - The async function to execute within the captured context
- * @returns A new async function that preserves the Langfuse ALS context
- *
- * @example
- * // Before (broken — setImmediate loses ALS context):
- * setImmediate(async () => {
- *   await this.checkAndSummarize(session, threshold);
- * });
- *
- * // After (fixed — context is captured and re-entered):
- * const wrappedFn = runWithCurrentLangfuseContext(async () => {
- *   await this.checkAndSummarize(session, threshold);
- * });
- * setImmediate(wrappedFn);
- */
-export function runWithCurrentLangfuseContext(fn) {
-    const capturedContext = contextStorage.getStore();
-    if (capturedContext) {
-        return () => contextStorage.run(capturedContext, fn);
-    }
-    // No context to preserve — return the function as-is
-    return fn;
-}
-/**
- * Get an OpenTelemetry Tracer for creating custom spans
- *
- * This allows applications to create their own spans that will be
- * processed by the same span processors (ContextEnricher + LangfuseSpanProcessor).
- *
- * @param name - Tracer name, defaults to "neurolink"
- * @param version - Tracer version, optional
- * @returns OpenTelemetry Tracer instance
- *
- * @example
- * const tracer = getTracer("my-app");
- * const span = tracer.startSpan("custom-operation");
- * try {
- *   // ... do work
- * } finally {
- *   span.end();
- * }
- */
-export function getTracer(name = "neurolink", version) {
-    return trace.getTracer(name, version);
-}
-/**
- * Create a new ContextEnricher span processor
- * Use this when useExternalTracerProvider is true to add to your own TracerProvider
- *
- * @returns A new ContextEnricher instance
- */
-export function createContextEnricher() {
-    return new ContextEnricher();
-}
-/**
- * Get all span processors that NeuroLink would use
- * Convenience function that returns [ContextEnricher, LangfuseSpanProcessor]
- *
- * @returns Array of span processors, or empty array if not initialized
- */
-export function getSpanProcessors() {
-    if (!isInitialized || !langfuseProcessor) {
-        logger.warn(`${LOG_PREFIX} getSpanProcessors called but not initialized`);
-        return [];
-    }
-    // Reuse cached ContextEnricher to avoid creating multiple instances
-    if (!cachedContextEnricher) {
-        cachedContextEnricher = new ContextEnricher();
-    }
-    return [cachedContextEnricher, langfuseProcessor];
-}
-/**
- * Check if using external TracerProvider mode
- *
- * @returns true if operating in external TracerProvider mode
- */
-export function isUsingExternalTracerProvider() {
-    return usingExternalProvider;
+export function setLangfuseContext(params, fn) {
+    const full = {};
+    const propagated = {};
+    for (const [key, value] of Object.entries({
+        ...params.metadata,
+        conversationId: params.conversationId,
+        requestId: params.requestId,
+    })) {
+        if (value === undefined || value === null || value === "") {
+            continue;
+        }
+        full[key] = value;
+        const text = spanJsonAttribute(value, Number.POSITIVE_INFINITY);
+        if (text.length <= MAX_PROPAGATED_CHARS) {
+            propagated[key] = text;
+        }
+    }
+    const tags = params.tags?.filter((tag) => tag.length > 0);
+    const active = context.active();
+    const withMetadata = active.setValue(TRACE_METADATA_KEY, {
+        ...traceMetadataFromContext(active),
+        ...full,
+    });
+    return context.with(withMetadata, () => propagateAttributes({
+        userId: params.userId || undefined,
+        sessionId: params.sessionId || undefined,
+        traceName: params.traceName || undefined,
+        ...(tags && tags.length > 0 && { tags }),
+        ...(Object.keys(propagated).length > 0 && { metadata: propagated }),
+    }, fn));
 }