@juspay/neurolink 13.5.0 → 13.6.0

package/dist/proxy/proxyTracer.js

@@ -12,10 +12,12 @@
  * - calculateCost() from pricing.ts for cost tracking
  */
 import { SpanStatusCode, SpanKind, ROOT_CONTEXT, isSpanContextValid, propagation, context, metrics, trace, } from "@opentelemetry/api";
-import { setLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
-import { spanContentAttribute } from "../telemetry/attributes.js";
+import { PROXY_TRACER_SCOPE } from "../constants/telemetry.js";
+import { ensureTelemetry, setLangfuseContext, } from "../services/server/ai/observability/instrumentation.js";
+import { spanContentAttribute, withoutSpanContent, } from "../telemetry/attributes.js";
 import { observationLevel, observe, observeTrace, usageDetails, } from "../telemetry/observation.js";
 import { generationName } from "../telemetry/observationNames.js";
+import { recordAIRequest } from "../telemetry/aiMetrics.js";
 import { proxyTokenUsage } from "./proxyTokenUsage.js";
 import { calculateCost, hasPricing, isExactPricingMatch, } from "../utils/pricing.js";
 import { logger } from "../utils/logger.js";
@@ -23,11 +25,12 @@ import { registerProxyRequestTraceContext, releaseProxyRequestTraceContext, } fr
 // ---------------------------------------------------------------------------
 // OTEL Metric Instruments — lazy singleton
 //
-// The MeterProvider is registered in initializeOpenTelemetry() which runs
-// *after* module import time.  @opentelemetry/api v1.x getMeter() returns a
-// NoopMeter if called before a real MeterProvider is set.  We therefore
-// defer instrument creation until the first ProxyTracer.end() call, at which
-// point the MeterProvider is guaranteed to be registered.
+// The MeterProvider is created by ensureTelemetry() (instrumentation.ts) when
+// OTEL_EXPORTER_OTLP_ENDPOINT is set; `neurolink proxy start` calls it at
+// startup, *after* module import time.  @opentelemetry/api v1.x getMeter()
+// returns a NoopMeter if called before a real MeterProvider is set.  We
+// therefore defer instrument creation until the first ProxyTracer.end()
+// call, at which point the MeterProvider is registered.
 // ---------------------------------------------------------------------------
 let _metrics = null;
 function getProxyMetrics() {
@@ -141,7 +144,17 @@ function redactHeaders(headers) {
 }
 /** Redact sensitive JSON fields in request/response bodies before logging. */
 const SENSITIVE_BODY_KEYS = /api[_-]?key|token|secret|password|credential|authorization/i;
-const BODY_LOGGING_ENABLED = process.env.NEUROLINK_PROXY_TRACE_BODY_LOGGING === "true";
+const envFlag = (name) => process.env[name]?.trim().toLowerCase();
+/**
+ * Request and response bodies, both as observation input and output and as raw
+ * span events, are recorded only on an explicit
+ * `NEUROLINK_PROXY_TRACE_BODY_LOGGING=true`, read per call. Bodies are the
+ * most sensitive thing a proxy sees, so tracing the request alone never turns
+ * them on.
+ */
+const bodyLoggingEnabled = () => process.env.NEUROLINK_PROXY_TRACE_BODY_LOGGING === "true";
+/** `NEUROLINK_RECORD_INPUTS=false` keeps request content out of every trace. */
+const recordInputsEnabled = () => envFlag("NEUROLINK_RECORD_INPUTS") !== "false";
 const MAX_BODY_LOG_SIZE = Number.parseInt(process.env.NEUROLINK_PROXY_TRACE_BODY_LOG_BYTES ?? "8192", 10);
 const MAX_STREAM_EVENTS_TO_LOG = 200;
 function redactBodyForLogging(body, maxLen = 8192) {
@@ -205,7 +218,7 @@ function detectClientApp(userAgent) {
 class ProxyTracer {
     rootSpan;
     traceContext;
-    proxyTracer = trace.getTracer("proxy");
+    proxyTracer = trace.getTracer(PROXY_TRACER_SCOPE);
     requestId;
     /**
      * Model used for costing. Starts as the model the client asked for and is
@@ -232,6 +245,12 @@ class ProxyTracer {
     requestedModel;
     input;
     output;
+    /** The parsed response outranks the raw upstream body that arrives after it. */
+    outputIsParsed = false;
+    /** A model call made through `runModelCall` records the generation. */
+    modelCallDelegated = false;
+    /** That call's records carry no content; fixed when the call starts. */
+    modelContentWithheld = false;
     responseModel;
     finishReason;
     firstOutputAt;
@@ -255,7 +274,11 @@ class ProxyTracer {
      * will be linked to the caller's trace via the OTel propagation API.
      */
     static startRequest(ctx, incomingHeaders) {
-        const tracer = trace.getTracer("proxy");
+        // The proxy tracer is not a scrubbed tracer, so nothing else starts
+        // telemetry before its first root span; without this an embedder that only
+        // set the Langfuse keys loses that first request.
+        ensureTelemetry();
+        const tracer = trace.getTracer(PROXY_TRACER_SCOPE);
         // Extract parent context from incoming headers (Claude Code may send traceparent)
         let parentContext = context.active();
         if (incomingHeaders && !trace.getSpan(context.active())) {
@@ -270,9 +293,10 @@ class ProxyTracer {
             }
         }
         const clientApp = ctx.clientApp ?? detectClientApp(ctx.userAgent);
+        const sessionId = incomingHeaders?.["x-neurolink-session-id"] ?? ctx.sessionId;
         const traceContext = context.with(parentContext, () => setLangfuseContext({
             userId: incomingHeaders?.["x-neurolink-user-id"],
-            sessionId: incomingHeaders?.["x-neurolink-session-id"] ?? ctx.sessionId,
+            sessionId,
             conversationId: incomingHeaders?.["x-neurolink-conversation-id"],
             requestId: ctx.requestId,
             traceName: `proxy:${ctx.model}`,
@@ -282,20 +306,41 @@ class ProxyTracer {
                 toolCount: ctx.toolCount,
             },
         }, () => context.active()));
+        // Model and usage are written under the gen_ai.* names collectors read
+        // before as well as under proxy.*; Langfuse's export leaves the gen_ai.*
+        // ones off this plain span, so the generation stays the priced record.
         const rootSpan = tracer.startSpan("proxy.request", {
             attributes: {
                 "proxy.request_id": ctx.requestId,
                 "http.method": ctx.method,
                 "http.target": ctx.path,
                 "proxy.request.model": ctx.model,
+                "gen_ai.request.model": ctx.model,
                 "proxy.stream": ctx.stream,
                 "proxy.tool_count": ctx.toolCount,
                 "proxy.client_app": clientApp,
             },
         }, traceContext);
+        // Marked at the start so a model call that ends before this span (the
+        // translated path) is attached to it rather than to the span above it.
+        observe(rootSpan, "span", {});
         if (ctx.userAgent) {
             rootSpan.setAttribute("http.user_agent", ctx.userAgent);
         }
+        // Plain attributes for backends that index identity by key; Langfuse reads
+        // the propagated user and session instead.
+        for (const [key, value] of [
+            ["neurolink.user_id", incomingHeaders?.["x-neurolink-user-id"]],
+            ["neurolink.session_id", sessionId],
+            [
+                "neurolink.conversation_id",
+                incomingHeaders?.["x-neurolink-conversation-id"],
+            ],
+        ]) {
+            if (value) {
+                rootSpan.setAttribute(key, value);
+            }
+        }
         if (ctx.toolNames && ctx.toolNames.length > 0) {
             // What the caller exposed to the model (tool catalogue for this request).
             rootSpan.setAttribute("gen_ai.request.tool_names", JSON.stringify(ctx.toolNames));
@@ -345,9 +390,39 @@ class ProxyTracer {
             attributes: {
                 "proxy.request_id": this.requestId,
                 "proxy.request.model": this.model,
+                "gen_ai.request.model": this.model,
             },
         }, this.traceContext);
     }
+    /**
+     * Run a model call inside this request's trace context, so the spans it
+     * starts nest under the proxy root and carry the request's user and session.
+     * That call's generation holds usage and cost, so the root records none of
+     * its own. Its prompt and answer are request and response bodies, so its
+     * records carry them only with `NEUROLINK_PROXY_TRACE_BODY_LOGGING=true`.
+     */
+    runModelCall(fn) {
+        this.modelCallDelegated = true;
+        this.modelContentWithheld = !bodyLoggingEnabled();
+        return context.with(this.traceContext, () => this.modelContentWithheld ? withoutSpanContent(fn) : fn());
+    }
+    /**
+     * The delegated call's stream, read and closed under the same content rule:
+     * the call records its answer while the stream is consumed, which happens
+     * after `runModelCall` has returned.
+     */
+    modelStream(iterator) {
+        if (!this.modelContentWithheld) {
+            return iterator;
+        }
+        const close = iterator.return?.bind(iterator);
+        return {
+            next: (...value) => withoutSpanContent(() => iterator.next(...value)),
+            ...(close && {
+                return: (value) => withoutSpanContent(() => close(value)),
+            }),
+        };
+    }
     // -------------------------------------------------------------------------
     // Attribute setters
     // -------------------------------------------------------------------------
@@ -414,6 +489,9 @@ class ProxyTracer {
             "proxy.usage.input_tokens": totalTokens - ctx.outputTokens,
             "proxy.usage.output_tokens": ctx.outputTokens,
             "proxy.usage.total_tokens": totalTokens,
+            "gen_ai.usage.input_tokens": totalTokens - ctx.outputTokens,
+            "gen_ai.usage.output_tokens": ctx.outputTokens,
+            "gen_ai.usage.total_tokens": totalTokens,
         });
         // Prefix-inferred prices are not an observed model rate. Keep provenance,
         // but emit an amount only when this model has an exact price-table entry.
@@ -451,11 +529,17 @@ class ProxyTracer {
         this.responseModel = ctx.responseModel ?? this.responseModel;
         this.finishReason = ctx.finishReason ?? this.finishReason;
         this.firstOutputAt = ctx.firstOutputAt ?? this.firstOutputAt;
-        if (BODY_LOGGING_ENABLED && ctx.output !== undefined) {
+        // A reply parsed to nothing (no content block, or an error before any)
+        // is still parsed: the raw upstream text must not stand in for it.
+        if (ctx.output !== undefined && this.recordsBodies()) {
             this.output = ctx.output;
+            this.outputIsParsed = true;
         }
         if (ctx.responseModel) {
-            this.rootSpan.setAttribute("proxy.response.model", ctx.responseModel);
+            this.rootSpan.setAttributes({
+                "proxy.response.model": ctx.responseModel,
+                "gen_ai.response.model": ctx.responseModel,
+            });
         }
         if (ctx.finishReason) {
             this.rootSpan.setAttribute("gen_ai.response.finish_reason", ctx.finishReason);
@@ -506,6 +590,7 @@ class ProxyTracer {
             "proxy.original_model": requestedModel,
             "proxy.actual_model": actualModel,
             "proxy.response.model": actualModel,
+            "gen_ai.response.model": actualModel,
             ...(actualProvider ? { "proxy.actual_provider": actualProvider } : {}),
         });
         if (this.recordRequestMetrics) {
@@ -531,16 +616,24 @@ class ProxyTracer {
     // -------------------------------------------------------------------------
     // Log payloads as span events
     // -------------------------------------------------------------------------
+    /** Record the client request body as the input of the root and its generation. */
+    setRequestInput(body) {
+        if (this.recordsBodies() && recordInputsEnabled()) {
+            this.input = body;
+        }
+    }
     /** Log the incoming client request body (redacted). */
     logRequestBody(body) {
-        if (!BODY_LOGGING_ENABLED) {
+        if (this.recordsBodies() && recordInputsEnabled()) {
+            this.input = parseBody(body);
+        }
+        if (!bodyLoggingEnabled() || !recordInputsEnabled()) {
             this.rootSpan.addEvent("proxy.client.request_body", {
                 "proxy.body.size": body.length,
                 "proxy.body.logged": false,
             });
             return;
         }
-        this.input = parseBody(body);
         this.rootSpan.addEvent("proxy.client.request_body", {
             ...buildBodyEventAttributes(body),
         });
@@ -553,7 +646,7 @@ class ProxyTracer {
     }
     /** Log the upstream request body (redacted, as sent to Anthropic). */
     logUpstreamRequestBody(body) {
-        if (!BODY_LOGGING_ENABLED) {
+        if (!bodyLoggingEnabled() || !recordInputsEnabled()) {
             this.rootSpan.addEvent("proxy.upstream.request_body", {
                 "proxy.body.size": body.length,
                 "proxy.body.logged": false,
@@ -578,21 +671,23 @@ class ProxyTracer {
     }
     /** Log the upstream response body (redacted). */
     logUpstreamResponseBody(body) {
-        if (!BODY_LOGGING_ENABLED) {
+        if (this.recordsBodies() && !this.outputIsParsed) {
+            this.output = parseBody(body);
+        }
+        if (!bodyLoggingEnabled()) {
             this.rootSpan.addEvent("proxy.upstream.response_body", {
                 "proxy.body.size": body.length,
                 "proxy.body.logged": false,
             });
             return;
         }
-        this.output = parseBody(body);
         this.rootSpan.addEvent("proxy.upstream.response_body", {
             ...buildBodyEventAttributes(body),
         });
     }
     /** Log SSE stream events (each event has type, timestamp, data). */
     logStreamEvents(events) {
-        if (!BODY_LOGGING_ENABLED) {
+        if (!bodyLoggingEnabled()) {
             this.rootSpan.addEvent("proxy.stream.events", {
                 "proxy.stream.event_count": events.length,
                 "proxy.body.logged": false,
@@ -746,6 +841,7 @@ class ProxyTracer {
             if (cost !== undefined) {
                 m.costTotal.add(cost, tokenLabels);
             }
+            recordAIRequest(this.billingProvider, this.model, billingUsage.total, durationMs, cost);
         }
         // Error metrics
         if (this.recordRequestMetrics && responseStatus >= 400) {
@@ -764,6 +860,10 @@ class ProxyTracer {
             });
         }
     }
+    /** Bodies are only worth keeping while something is recording the span. */
+    recordsBodies() {
+        return bodyLoggingEnabled() && this.rootSpan.isRecording();
+    }
     levelFor(responseStatus) {
         if (responseStatus === 499) {
             return "WARNING";
@@ -793,7 +893,7 @@ class ProxyTracer {
             metadata: { account: this.accountEmail },
         });
         observeTrace(this.rootSpan, io);
-        if (this.upstreamStartedAt === undefined) {
+        if (this.upstreamStartedAt === undefined || this.modelCallDelegated) {
             return;
         }
         const generation = this.proxyTracer.startSpan(generationName(this.isStream ? "stream" : "generate"), {
@@ -913,6 +1013,29 @@ function trackFallbackLegHealth(legKey, status, errorMessage) {
         (errorMessage ? `; last error: ${errorMessage.slice(0, 200)}` : ""));
     reportedDeadFallbackLegs.add(legKey);
 }
+/** Leg failure classes the fallback paths put in brackets before a message. */
+const FALLBACK_ERROR_CLASSES = new Set([
+    "unknown",
+    "unavailable",
+    "rate_limit",
+    "context_overflow",
+    "empty_response",
+    "schema_mismatch",
+    "provider_quota",
+]);
+/**
+ * A metric label from a fixed set: an error message is unbounded cardinality
+ * and can echo the prompt or a credential.
+ */
+function fallbackErrorLabel(errorMessage) {
+    if (errorMessage === undefined) {
+        return "unknown";
+    }
+    const named = /^\[([a-z_]+)\]/.exec(errorMessage)?.[1];
+    return named !== undefined && FALLBACK_ERROR_CLASSES.has(named)
+        ? named
+        : "other";
+}
 export function recordFallbackAttempt(attrs) {
     // Leg health is tracked outside the metrics try/catch: a telemetry failure
     // must not be the reason an operator never hears that a leg is dead.
@@ -934,7 +1057,7 @@ export function recordFallbackAttempt(attrs) {
         else {
             m.fallbackFailureTotal.add(1, {
                 ...labels,
-                error: attrs.errorMessage?.slice(0, 100) ?? "unknown",
+                error: fallbackErrorLabel(attrs.errorMessage),
             });
         }
     }
@@ -995,6 +1118,7 @@ export { ProxyTracer };
 /** Standard SERVER span covers every proxy door, including parsing and admission failures. */
 export function startProxyHttpTrace(metadata, headers) {
     try {
+        ensureTelemetry();
         const normalizedHeaders = { ...headers };
         if (normalizedHeaders.traceparent?.includes(",")) {
             normalizedHeaders.traceparent = normalizedHeaders.traceparent
@@ -1002,7 +1126,7 @@ export function startProxyHttpTrace(metadata, headers) {
                 .trim();
         }
         const parent = propagation.extract(ROOT_CONTEXT, normalizedHeaders);
-        const span = trace.getTracer("proxy").startSpan("proxy.http.request", {
+        const span = trace.getTracer(PROXY_TRACER_SCOPE).startSpan("proxy.http.request", {
             kind: SpanKind.SERVER,
             attributes: {
                 "http.request.method": metadata.method,

package/dist/proxy/proxyTranslationEngine.js

@@ -582,9 +582,11 @@ async function* runTranslationAttempts(args) {
                 },
             });
             recordAttempt(attempt.label ?? "translation", "translation");
-            const result = await raceWithAbort(ctx.neurolink.stream(request.withVettedImages(prepared.body)), signal);
+            const modelCall = () => ctx.neurolink.stream(request.withVettedImages(prepared.body));
+            const result = await raceWithAbort(args.tracer ? args.tracer.runModelCall(modelCall) : modelCall(), signal);
             request.setResult(result);
-            const iterator = result.stream[Symbol.asyncIterator]();
+            const source = result.stream[Symbol.asyncIterator]();
+            const iterator = args.tracer ? args.tracer.modelStream(source) : source;
             request.setIterator(iterator);
             let hasText = false;
             while (true) {

package/dist/proxy/sseInterceptor.js

@@ -293,10 +293,12 @@ function processMessageDelta(acc, parsed) {
     }
     const usage = parsed.usage;
     if (usage) {
-        // message_delta provides the final output_tokens count; treat it as
-        // additive because message_start reports output_tokens: 0 for the
-        // initial placeholder.
-        acc.outputTokens += usage.output_tokens ?? 0;
+        // message_delta reports the cumulative output_tokens for the whole
+        // message, including the token message_start already counted (it reports
+        // 1, not 0), so it replaces that count rather than adding to it.
+        if (typeof usage.output_tokens === "number") {
+            acc.outputTokens = usage.output_tokens;
+        }
     }
 }
 /* eslint-enable @typescript-eslint/no-explicit-any */

package/dist/rag/chunkers/BaseChunker.js

@@ -69,6 +69,7 @@ export class BaseChunker {
         return withSpan({
             name: "neurolink.rag.chunk",
             tracer: tracers.rag,
+            observationType: "span",
             attributes: {
                 "rag.chunker.strategy": this.strategy,
                 "rag.chunker.content_chars": content.length,

package/dist/rag/index.d.ts

@@ -43,6 +43,7 @@
  * const chunks = await chunker.chunk(text);
  * ```
  */
+import "../services/server/ai/observability/instrumentation.js";
 export { ChunkerFactory, chunkerFactory, createChunker, getAvailableStrategies as getFactoryStrategies, getDefaultConfig as getFactoryDefaultConfig, } from "./ChunkerFactory.js";
 export { ChunkerRegistry as ChunkerRegistryV2, chunkerRegistry, getAvailableChunkers, getChunker, getChunkerMetadata, } from "./ChunkerRegistry.js";
 export * from "./chunkers/index.js";

package/dist/rag/index.js

@@ -43,6 +43,10 @@
  * const chunks = await chunker.chunk(text);
  * ```
  */
+// Imported on its own, this entry starts tracing at its first span, as the
+// main entry does. The import sits here rather than in the shared tracers so
+// that the client entry stays free of the OpenTelemetry Node SDK.
+import "../services/server/ai/observability/instrumentation.js";
 export { ChunkerFactory, chunkerFactory, createChunker, getAvailableStrategies as getFactoryStrategies, getDefaultConfig as getFactoryDefaultConfig, } from "./ChunkerFactory.js";
 // ChunkerFactory and ChunkerRegistry patterns (from main worktree)
 export { ChunkerRegistry as ChunkerRegistryV2, chunkerRegistry, getAvailableChunkers, getChunker, getChunkerMetadata, } from "./ChunkerRegistry.js";

package/dist/rag/ragIntegration.js

@@ -478,6 +478,7 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
             return withSpan({
                 name: "neurolink.rag.search",
                 tracer: tracers.rag,
+                observationType: "span",
                 attributes: {
                     "rag.query_length": query ? String(query).length : 0,
                     "rag.top_k": topK ?? 5,

package/dist/rag/reranker/reranker.js

@@ -33,6 +33,7 @@ export async function rerank(results, query, model, options) {
     return withSpan({
         name: "neurolink.rag.rerank",
         tracer: tracers.rag,
+        observationType: "span",
         attributes: {
             "rag.reranker.input_count": results.length,
             "rag.reranker.top_k": options?.topK ?? 3,
@@ -153,6 +154,7 @@ export async function batchRerank(results, query, model, options) {
     return withSpan({
         name: "neurolink.rag.batchRerank",
         tracer: tracers.rag,
+        observationType: "span",
         attributes: {
             "rag.reranker.input_count": results.length,
             "rag.reranker.top_k": options?.topK ?? 3,

package/dist/rag/retrieval/vectorQueryTool.js

@@ -51,6 +51,7 @@ export function createVectorQueryTool(config, vectorStore) {
             return withSpan({
                 name: "neurolink.rag.vectorQuery",
                 tracer: tracers.rag,
+                observationType: "span",
                 attributes: {
                     "rag.vector.index": indexName,
                     "rag.vector.top_k": params.topK ?? topK,

package/dist/server/routes/codexProxyRoutes.js

@@ -1026,7 +1026,7 @@ function captureCodexResponse(ctx, response, phase, account, attempt) {
 }
 function startCodexTracer(ctx, model, body, isFallbackRequest) {
     try {
-        return ProxyTracer.startRequest({
+        const tracer = ProxyTracer.startRequest({
             requestId: ctx.requestId,
             method: ctx.method,
             path: ctx.path,
@@ -1038,6 +1038,8 @@ function startCodexTracer(ctx, model, body, isFallbackRequest) {
             recordRequestMetrics: !isFallbackRequest,
             recordUsageMetrics: true,
         }, ctx.headers);
+        tracer.setRequestInput(body);
+        return tracer;
     }
     catch {
         return undefined;

package/dist/server/utils/validation.d.ts

@@ -192,8 +192,8 @@ export declare const TranscribeConfigSchema: z.ZodObject<{
     correction: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         guard: z.ZodOptional<z.ZodEnum<{
-            decide: "decide";
             none: "none";
+            decide: "decide";
         }>>;
         decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
         rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
@@ -242,8 +242,8 @@ export declare const TranscribeRequestSchema: z.ZodObject<{
     correction: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         guard: z.ZodOptional<z.ZodEnum<{
-            decide: "decide";
             none: "none";
+            decide: "decide";
         }>>;
         decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
         rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
@@ -308,8 +308,8 @@ export declare const TranscribeStreamConfigSchema: z.ZodObject<{
     correction: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         guard: z.ZodOptional<z.ZodEnum<{
-            decide: "decide";
             none: "none";
+            decide: "decide";
         }>>;
         decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
         rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{

package/dist/services/server/ai/observability/instrumentation.d.ts

@@ -1,7 +1,7 @@
 import { type Context } from "@opentelemetry/api";
 import type { NeurolinkTraceContext, ObservabilityConfig, SpanContent } from "../../../../types/index.js";
 /**
- * @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.
+ * @description Starts NeuroLink's tracing once per process, synchronously. Every span created through the shared tracers calls it first once this module is loaded, as the main, server and livekit entries do, so direct provider calls without a NeuroLink instance are traced too. Langfuse is enabled unless `config.langfuse` is `false` or has `enabled: false`, when `config.langfuse` is `true` or an options object, or when `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are set and `LANGFUSE_ENABLED` is not `false`, `0`, `off` or `no`; an OTLP exporter is added when `OTEL_EXPORTER_OTLP_ENDPOINT` is set. When the host already registered a TracerProvider no provider is created and `OTEL_EXPORTER_OTLP_ENDPOINT` is ignored with a warning; 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, with a warning naming the options that differ from the first when it does differ; calls made before anything is configured start nothing, so a later config or environment can still start tracing, unless `langfuse: false` was passed. Langfuse enabled without both keys (in config or the environment) exports nothing to Langfuse, and a warning says so once. With `langfuse: true` or the environment alone that counts as not configured, so only an OTLP endpoint starts tracing; an options object starts tracing anyway, as it always did, so exporters registered on the shared registry receive the spans. Pending spans and metrics are flushed when the process runs out of work (`beforeExit`), within the same budget as `flushOpenTelemetry`, which an explicit `process.exit()` skips; `NEUROLINK_TELEMETRY_EXIT_FLUSH` set to `false`, `0`, `off` or `no` skips that flush too, and the process ends as soon as it has no work. 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`.
  */
@@ -13,20 +13,21 @@ export declare function ensureTelemetry(config?: ObservabilityConfig): void;
  */
 export declare function acquireTelemetry(config?: ObservabilityConfig): void;
 /**
- * @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.
+ * @description Releases one holder registered by `acquireTelemetry` and flushes pending spans as `flushOpenTelemetry` does. 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.
+ * @throws {Error} When any provider fails to flush or does not finish within the flush budget.
  */
 export declare function releaseTelemetry(): Promise<void>;
 /**
- * @description Exports pending spans and metrics from the providers NeuroLink owns and flushes its Langfuse exporter. A host provider is never flushed.
+ * @description Exports pending spans and metrics from the providers NeuroLink owns and flushes its Langfuse exporter. A host provider is never flushed. The OTLP span and metric exports are waited for at most the flush budget (`observability.langfuse.flushBudgetMs`, default 3000 ms) and the Langfuse exporter within its own budget. A provider that fails to flush, or does not finish within the budget (a collector that cannot be reached, for one), is logged as a warning and makes the call reject once every provider has settled.
  * @returns {Promise<void>} Resolves when every owned provider has flushed.
- * @throws {Error} When any provider fails to flush.
+ * @throws {Error} When any provider fails to flush or does not finish within the flush budget.
  */
 export declare function flushOpenTelemetry(): Promise<void>;
 /**
- * @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.
+ * @description Terminally shuts down the providers NeuroLink owns once no `acquireTelemetry` holder remains; while holders remain it only flushes, as `flushOpenTelemetry` does. 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. The OTLP exporters get the same budget as `flushOpenTelemetry`, and a failure of the shutdown itself is logged as a warning.
+ * @returns {Promise<void>} Resolves when telemetry is flushed or shut down, or the flush budget has run out.
+ * @throws {Error} When holders remain and the flush they get fails.
  */
 export declare function shutdownOpenTelemetry(): Promise<void>;
 /**