@juspay/neurolink 13.5.0 → 13.5.1

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

@@ -1,38 +1,168 @@
 import { propagateAttributes, setLangfuseTracerProvider, } from "@langfuse/tracing";
-import { context, createContextKey, metrics, ProxyTracerProvider, trace, } from "@opentelemetry/api";
+import { context, createContextKey, metrics, } from "@opentelemetry/api";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
-import { resourceFromAttributes } from "@opentelemetry/resources";
+import { resourceFromAttributes, } from "@opentelemetry/resources";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
+import { DEFAULT_FLUSH_BUDGET_MS } from "../../../../constants/langfuse.js";
 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 { hasHostTracerProvider, registerTelemetryStarter, } from "../../../../telemetry/telemetryStarter.js";
 import { logger } from "../../../../utils/logger.js";
-import { createLangfuseExporter, isLangfuseEnabled } from "./langfuseSetup.js";
-import { createOtlpMeterProvider, createOtlpSpanProcessor, } from "./otlpSetup.js";
+import { createLangfuseExporter, isLangfuseEnabled, isOff, resolveEnvironment, resolveRelease, } from "./langfuseSetup.js";
+import { createOtlpConnections, createOtlpMeterProvider, createOtlpSpanProcessor, } from "./otlpSetup.js";
 const MAX_PROPAGATED_CHARS = 200;
 const LANGFUSE_EXPORTER_NAME = "langfuse";
 const TRACE_METADATA_KEY = createContextKey(TRACE_METADATA_CONTEXT_KEY);
+const CONTEXT_PROBE_KEY = createContextKey("neurolink.context-manager-probe");
+// `false`, `0`, `off` or `no` skips the flush at process exit; the released build had none.
+const EXIT_FLUSH_SWITCH = "NEUROLINK_TELEMETRY_EXIT_FLUSH";
 let tracerProvider = null;
+let registryProcessor = null;
+let otlpProcessor = null;
 let meterProvider = null;
+let otlpConnections = null;
+let flushBudgetMs = DEFAULT_FLUSH_BUDGET_MS;
 let langfuseExporter = null;
 let usingExternalProvider = false;
 let started = false;
+let startedConfig;
 let initialized = false;
-let ignoredConfigLogged = false;
+let ignoredConfigDebugLogged = false;
+const ignoredConfigWarnings = new Set();
+let exitFlushRegistered = false;
 let initializationError = null;
 let terminated = false;
 let terminationLogged = false;
 let unconfiguredLogged = false;
+let missingKeysLogged = false;
 let holders = 0;
-function hasHostTracerProvider() {
-    const global = trace.getTracerProvider();
-    if (!(global instanceof ProxyTracerProvider)) {
-        return true;
+function differingConfigFields(first, later) {
+    const firstLangfuse = first?.langfuse;
+    const laterLangfuse = later.langfuse;
+    if ((firstLangfuse === false) !== (laterLangfuse === false)) {
+        return ["langfuse"];
+    }
+    const left = typeof firstLangfuse === "object" ? firstLangfuse : {};
+    const right = typeof laterLangfuse === "object" ? laterLangfuse : {};
+    return [...new Set([...Object.keys(left), ...Object.keys(right)])]
+        .filter((key) => left[key] !== right[key])
+        .sort();
+}
+function reportIgnoredConfig(config) {
+    const differing = differingConfigFields(startedConfig, config);
+    if (differing.length === 0) {
+        if (!ignoredConfigDebugLogged) {
+            ignoredConfigDebugLogged = true;
+            logger.debug(`${OTEL_LOG_PREFIX} Telemetry already started; ignoring observability config`);
+        }
+        return;
     }
-    return global.getDelegateTracer("ai") !== undefined;
+    const fields = differing.join(", ");
+    if (ignoredConfigWarnings.has(fields)) {
+        return;
+    }
+    ignoredConfigWarnings.add(fields);
+    logger.warn(`${OTEL_LOG_PREFIX} Telemetry already started; ignoring the observability config of a later NeuroLink instance. The first config stays in effect; the ignored one differs in: ${fields}`);
+}
+function flushBudgetOf(config) {
+    const budget = typeof config?.langfuse === "object"
+        ? config.langfuse.flushBudgetMs
+        : undefined;
+    return budget !== undefined && budget > 0 ? budget : DEFAULT_FLUSH_BUDGET_MS;
+}
+function hasLangfuseKeys(config) {
+    const options = typeof config?.langfuse === "object" ? config.langfuse : {};
+    return Boolean((options.publicKey ?? process.env.LANGFUSE_PUBLIC_KEY) &&
+        (options.secretKey ?? process.env.LANGFUSE_SECRET_KEY));
+}
+// An unreachable collector must not hold the caller past the budget. When the
+// budget runs out `onExpiry` closes what the work still has open, so the export
+// does not carry on to its own timeout and hold the process open.
+async function withinBudget(work, budgetMs, onExpiry) {
+    if (!work) {
+        return;
+    }
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            onExpiry?.();
+            reject(new Error(`did not finish within ${budgetMs}ms`));
+        }, budgetMs);
+    });
+    try {
+        await Promise.race([work, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function cutOtlpConnections() {
+    otlpConnections?.cut();
+}
+function reportUnsettled(action, results) {
+    const errors = results.flatMap((result) => result.status === "rejected"
+        ? [
+            result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason),
+        ]
+        : []);
+    if (errors.length > 0) {
+        logger.warn(`${OTEL_LOG_PREFIX} ${action} did not complete; spans or metrics still pending may be lost`, { errors });
+    }
+}
+function flushBeforeExit() {
+    if (isOff(process.env[EXIT_FLUSH_SWITCH])) {
+        return;
+    }
+    flushOpenTelemetry().catch((error) => {
+        logger.debug(`${OTEL_LOG_PREFIX} Flush at process exit failed`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+}
+function registerExitFlush() {
+    if (exitFlushRegistered) {
+        return;
+    }
+    exitFlushRegistered = true;
+    process.once("beforeExit", flushBeforeExit);
+}
+// Without a registered context manager `context.with` runs the callback but
+// `context.active()` stays the root context, so nothing set on a context
+// (user, session, the parent span) reaches the spans created inside.
+function hasContextManager() {
+    return context.with(context.active().setValue(CONTEXT_PROBE_KEY, true), () => context.active().getValue(CONTEXT_PROBE_KEY) === true);
+}
+// The OTLP traces and metrics keep the service name existing dashboards and
+// alerts match on. The provider's own resource, which the registry exporters
+// (Langfuse) read, is built in `initialize` with its own default.
+function otlpResourceOf(config) {
+    const environment = resolveEnvironment(config);
+    return resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "ai-service",
+        [ATTR_SERVICE_VERSION]: resolveRelease(config) || process.env.npm_package_version || "v1.0.0",
+        ...(environment && { "deployment.environment": environment }),
+    });
+}
+// A view over each ended span rather than a copy, so the methods and fields the
+// exporter reads stay intact, with the sink's own resource on top.
+function withResource(processor, resource) {
+    return {
+        onStart: (span, parentContext) => processor.onStart(span, parentContext),
+        onEnd: (span) => {
+            const view = Object.create(span, {
+                resource: { value: resource, enumerable: true },
+            });
+            processor.onEnd(view);
+        },
+        forceFlush: () => processor.forceFlush(),
+        shutdown: () => processor.shutdown(),
+    };
 }
 function registerLangfuseExporter(config) {
     const registry = getExporterRegistry();
@@ -47,68 +177,107 @@ function registerLangfuseExporter(config) {
     return exporter;
 }
 function initialize(config) {
-    const langfuse = isLangfuseEnabled(config);
+    const langfuseRequested = isLangfuseEnabled(config);
+    // Without both keys there is nothing to export to, so Langfuse counts as not
+    // configured and a later config that has them can still start tracing.
+    const langfuse = langfuseRequested && hasLangfuseKeys(config);
+    if (langfuseRequested && !langfuse && !missingKeysLogged) {
+        missingKeysLogged = true;
+        logger.warn(`${OTEL_LOG_PREFIX} Langfuse is enabled but publicKey and secretKey are not both set in config or LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY; not exporting to Langfuse`);
+    }
     const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
-    if (!langfuse && !otlpEndpoint) {
+    // An options object starts the pipeline even without keys, as it always did:
+    // exporters registered on the shared registry still receive the spans.
+    const optionsObject = langfuseRequested && typeof config?.langfuse === "object";
+    if (!langfuse && !optionsObject && !otlpEndpoint) {
         if (!unconfiguredLogged) {
             unconfiguredLogged = true;
             logger.debug(`${OTEL_LOG_PREFIX} Langfuse and OTLP not configured; skipping`);
         }
         return config?.langfuse === false;
     }
+    flushBudgetMs = flushBudgetOf(config);
     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.`);
+            logger.info(`${OTEL_LOG_PREFIX} Host TracerProvider detected; Langfuse exporter registered. Add \`createExporterSpanProcessor()\` to the host provider to export NeuroLink spans to it, and register a context manager (\`NodeTracerProvider.register()\` and \`NodeSDK\` do) so user, session and parent spans reach the spans NeuroLink creates.`);
+            if (!hasContextManager()) {
+                logger.warn(`${OTEL_LOG_PREFIX} The host TracerProvider has no context manager registered: setLangfuseContext() user, session and metadata and parent/child span nesting are lost. Register one, for example with \`NodeTracerProvider.register()\`, or start the host with \`NodeSDK\`.`);
+            }
         }
         else {
             logger.info(`${OTEL_LOG_PREFIX} Host TracerProvider detected; NeuroLink registers no provider and no exporter.`);
         }
+        if (otlpEndpoint) {
+            logger.warn(`${OTEL_LOG_PREFIX} OTEL_EXPORTER_OTLP_ENDPOINT is ignored because a host TracerProvider is registered; NeuroLink exports no traces or metrics to it. Add an OTLP exporter to the host's own providers. NeuroLink's ai_* metrics are recorded on the host's MeterProvider.`);
+        }
+        if (langfuseExporter) {
+            registerExitFlush();
+        }
         return true;
     }
+    const environment = resolveEnvironment(config);
     const resource = resourceFromAttributes({
-        [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "ai-service",
+        [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "neurolink",
+        [ATTR_SERVICE_VERSION]: resolveRelease(config) || process.env.npm_package_version || "v1.0.0",
+        ...(environment && { "deployment.environment": environment }),
     });
     const exporter = langfuse ? registerLangfuseExporter(config) : null;
-    const otlpProcessor = otlpEndpoint
-        ? createOtlpSpanProcessor(otlpEndpoint)
+    const otlpResource = otlpResourceOf(config);
+    const connections = otlpEndpoint ? createOtlpConnections() : null;
+    const otlpExporter = otlpEndpoint
+        ? createOtlpSpanProcessor(otlpEndpoint, flushBudgetMs, connections ?? undefined)
         : null;
-    const spanProcessors = [
-        new ExporterSpanProcessor(getExporterRegistry()),
-    ];
-    if (otlpProcessor) {
-        spanProcessors.push(otlpProcessor);
+    const otlpSpanProcessor = otlpExporter && withResource(otlpExporter, otlpResource);
+    const exporterSpanProcessor = new ExporterSpanProcessor(getExporterRegistry(), true);
+    const spanProcessors = [exporterSpanProcessor];
+    if (otlpSpanProcessor) {
+        spanProcessors.push(otlpSpanProcessor);
     }
     const provider = new NodeTracerProvider({ resource, spanProcessors });
     provider.register({ propagator: new W3CTraceContextPropagator() });
     setLangfuseTracerProvider(provider);
     tracerProvider = provider;
+    registryProcessor = exporterSpanProcessor;
+    otlpProcessor = otlpSpanProcessor;
     langfuseExporter = exporter;
     meterProvider = otlpEndpoint
-        ? createOtlpMeterProvider(otlpEndpoint, resource)
+        ? createOtlpMeterProvider(otlpEndpoint, otlpResource, flushBudgetMs, connections ?? undefined)
         : null;
+    otlpConnections = connections;
     usingExternalProvider = false;
     initialized = true;
+    registerExitFlush();
     logger.info(`${OTEL_LOG_PREFIX} Observability initialized`, {
         langfuseEnabled: exporter !== null,
-        otlpEnabled: otlpProcessor !== null,
+        otlpEnabled: otlpSpanProcessor !== null,
     });
     return true;
 }
 async function stop() {
     const provider = tracerProvider;
+    const registry = registryProcessor;
+    const otlp = otlpProcessor;
     const meters = meterProvider;
+    const connections = otlpConnections;
     const hostExporter = usingExternalProvider ? langfuseExporter : null;
+    const budgetMs = flushBudgetMs;
     terminated = true;
     tracerProvider = null;
+    registryProcessor = null;
+    otlpProcessor = null;
     meterProvider = null;
+    otlpConnections = null;
     langfuseExporter = null;
     usingExternalProvider = false;
     started = false;
+    startedConfig = undefined;
     initialized = false;
     initializationError = null;
+    process.off("beforeExit", flushBeforeExit);
+    exitFlushRegistered = false;
     if (provider) {
         setLangfuseTracerProvider(null);
     }
@@ -118,23 +287,18 @@ async function stop() {
     if (hostExporter) {
         getExporterRegistry().unregister(hostExporter.getName());
     }
+    // The provider's own shutdown only shuts down these processors; each is shut
+    // down here so the OTLP one is bounded and Langfuse keeps its own budget.
     const results = await Promise.allSettled([
-        provider?.shutdown(),
+        registry?.shutdown(),
+        withinBudget(otlp?.shutdown(), budgetMs, () => connections?.cut()),
         hostExporter?.shutdown(),
-        meters?.shutdown(),
+        withinBudget(meters?.shutdown(), budgetMs, () => connections?.cut()),
     ]);
-    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),
-            });
-        }
-    }
+    reportUnsettled("Shutdown", results);
 }
 /**
- * @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`.
  */
@@ -147,18 +311,19 @@ export function ensureTelemetry(config) {
         return;
     }
     if (started) {
-        if (config && !ignoredConfigLogged) {
-            ignoredConfigLogged = true;
-            logger.debug(`${OTEL_LOG_PREFIX} Telemetry already started; ignoring observability config`);
+        if (config) {
+            reportIgnoredConfig(config);
         }
         return;
     }
     initializationError = null;
     try {
         started = initialize(config);
+        startedConfig = started ? config : undefined;
     }
     catch (error) {
         started = true;
+        startedConfig = config;
         initializationError =
             error instanceof Error ? error.message : String(error);
         logger.error(`${OTEL_LOG_PREFIX} Initialization failed`, {
@@ -166,6 +331,7 @@ export function ensureTelemetry(config) {
         });
     }
 }
+registerTelemetryStarter(ensureTelemetry);
 /**
  * @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`.
@@ -176,25 +342,28 @@ export function acquireTelemetry(config) {
     ensureTelemetry(config);
 }
 /**
- * @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 async function releaseTelemetry() {
     holders = Math.max(0, holders - 1);
     await flushOpenTelemetry();
 }
 /**
- * @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 async function flushOpenTelemetry() {
+    const budgetMs = flushBudgetMs;
     const results = await Promise.allSettled([
-        tracerProvider?.forceFlush(),
+        registryProcessor?.forceFlush(),
         usingExternalProvider ? langfuseExporter?.flush() : undefined,
-        meterProvider?.forceFlush(),
+        withinBudget(otlpProcessor?.forceFlush(), budgetMs, cutOtlpConnections),
+        withinBudget(meterProvider?.forceFlush(), budgetMs, cutOtlpConnections),
     ]);
+    reportUnsettled("Flush", results);
     const failed = results.filter((result) => result.status === "rejected");
     if (failed.length > 0) {
         throw new Error(`${OTEL_LOG_PREFIX} Flush failed`, {
@@ -203,8 +372,9 @@ export async function flushOpenTelemetry() {
     }
 }
 /**
- * @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 async function shutdownOpenTelemetry() {
     if (holders > 0) {

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

@@ -1,7 +1,25 @@
 import { LangfuseExporter } from "../../../../observability/exporters/langfuseExporter.js";
 import type { ObservabilityConfig } from "../../../../types/index.js";
 /**
- * @description Decides whether Langfuse export is on: off when `config.langfuse` is `false`, on when it is an options object or both Langfuse keys are in the environment.
+ * @description Tells whether a setting says "off": `false`, or the text `false`, `0`, `off` or `no` in any case.
+ * @param value {unknown} - A config value or an environment variable.
+ * @returns {boolean} `true` for an explicit off setting; `false` for anything else, an unset value included.
+ */
+export declare function isOff(value: unknown): boolean;
+/**
+ * @description Resolves the environment name the OTLP resource reports as `deployment.environment`: the config value, then `LANGFUSE_TRACING_ENVIRONMENT`, `LANGFUSE_ENVIRONMENT` and `PUBLIC_APP_ENVIRONMENT`. Langfuse traces are labelled from the config value and `LANGFUSE_TRACING_ENVIRONMENT` alone, as before.
+ * @param config {ObservabilityConfig | undefined} - Observability options.
+ * @returns {string | undefined} The environment name, or `undefined` when none is set.
+ */
+export declare function resolveEnvironment(config?: ObservabilityConfig): string | undefined;
+/**
+ * @description Resolves the release the OTLP resource reports as `service.version`: the config value, then `LANGFUSE_RELEASE` and `PUBLIC_APP_VERSION`. Langfuse traces are labelled from the config value and `LANGFUSE_RELEASE` alone, as before.
+ * @param config {ObservabilityConfig | undefined} - Observability options.
+ * @returns {string | undefined} The release identifier, or `undefined` when none is set.
+ */
+export declare function resolveRelease(config?: ObservabilityConfig): string | undefined;
+/**
+ * @description Decides whether Langfuse export is on. Off when `config.langfuse` is `false` or an options object with `enabled: false`. On for `true` and for an options object with `enabled: true` or with both keys. Any other options object, and no options at all with both keys in the environment, is on unless `LANGFUSE_ENABLED` is `false`, `0`, `off` or `no`: the switch governs the keys wherever they come from the environment, so an options object that leaves them there (only a mask or an environment name) obeys it too, while keys or `enabled: true` given in code are an explicit choice and win over it.
  * @param config {ObservabilityConfig | undefined} - Observability options.
  * @returns {boolean} `true` when a Langfuse exporter should be created.
  */

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

@@ -11,8 +11,48 @@ async function initializeQuietly(exporter) {
         });
     }
 }
+const OFF_VALUES = new Set(["false", "0", "off", "no"]);
 /**
- * @description Decides whether Langfuse export is on: off when `config.langfuse` is `false`, on when it is an options object or both Langfuse keys are in the environment.
+ * @description Tells whether a setting says "off": `false`, or the text `false`, `0`, `off` or `no` in any case.
+ * @param value {unknown} - A config value or an environment variable.
+ * @returns {boolean} `true` for an explicit off setting; `false` for anything else, an unset value included.
+ */
+export function isOff(value) {
+    return (value === false ||
+        (typeof value === "string" && OFF_VALUES.has(value.trim().toLowerCase())));
+}
+function firstEnv(...names) {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function langfuseOptions(config) {
+    return typeof config?.langfuse === "object" ? config.langfuse : {};
+}
+/**
+ * @description Resolves the environment name the OTLP resource reports as `deployment.environment`: the config value, then `LANGFUSE_TRACING_ENVIRONMENT`, `LANGFUSE_ENVIRONMENT` and `PUBLIC_APP_ENVIRONMENT`. Langfuse traces are labelled from the config value and `LANGFUSE_TRACING_ENVIRONMENT` alone, as before.
+ * @param config {ObservabilityConfig | undefined} - Observability options.
+ * @returns {string | undefined} The environment name, or `undefined` when none is set.
+ */
+export function resolveEnvironment(config) {
+    return (langfuseOptions(config).environment ||
+        firstEnv("LANGFUSE_TRACING_ENVIRONMENT", "LANGFUSE_ENVIRONMENT", "PUBLIC_APP_ENVIRONMENT"));
+}
+/**
+ * @description Resolves the release the OTLP resource reports as `service.version`: the config value, then `LANGFUSE_RELEASE` and `PUBLIC_APP_VERSION`. Langfuse traces are labelled from the config value and `LANGFUSE_RELEASE` alone, as before.
+ * @param config {ObservabilityConfig | undefined} - Observability options.
+ * @returns {string | undefined} The release identifier, or `undefined` when none is set.
+ */
+export function resolveRelease(config) {
+    return (langfuseOptions(config).release ||
+        firstEnv("LANGFUSE_RELEASE", "PUBLIC_APP_VERSION"));
+}
+/**
+ * @description Decides whether Langfuse export is on. Off when `config.langfuse` is `false` or an options object with `enabled: false`. On for `true` and for an options object with `enabled: true` or with both keys. Any other options object, and no options at all with both keys in the environment, is on unless `LANGFUSE_ENABLED` is `false`, `0`, `off` or `no`: the switch governs the keys wherever they come from the environment, so an options object that leaves them there (only a mask or an environment name) obeys it too, while keys or `enabled: true` given in code are an explicit choice and win over it.
  * @param config {ObservabilityConfig | undefined} - Observability options.
  * @returns {boolean} `true` when a Langfuse exporter should be created.
  */
@@ -21,8 +61,21 @@ export function isLangfuseEnabled(config) {
     if (langfuse === false) {
         return false;
     }
-    return (typeof langfuse === "object" ||
-        Boolean(process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY));
+    if (typeof langfuse === "object") {
+        if (isOff(langfuse.enabled)) {
+            return false;
+        }
+        // Keys or `enabled: true` given in code are an explicit choice and win over the
+        // environment switch. An object that leaves the keys to the environment (only a
+        // mask or an environment name) is governed by it like the keys themselves.
+        return (langfuse.enabled === true ||
+            Boolean(langfuse.publicKey && langfuse.secretKey) ||
+            !isOff(process.env.LANGFUSE_ENABLED));
+    }
+    if (langfuse === true) {
+        return true;
+    }
+    return (Boolean(process.env.LANGFUSE_PUBLIC_KEY && process.env.LANGFUSE_SECRET_KEY) && !isOff(process.env.LANGFUSE_ENABLED));
 }
 /**
  * @description Builds and starts a Langfuse exporter from config, falling back to the `LANGFUSE_*` environment variables.
@@ -30,7 +83,7 @@ export function isLangfuseEnabled(config) {
  * @returns {LangfuseExporter | null} The exporter, or `null` (after a warning) when the public or secret key is missing.
  */
 export function createLangfuseExporter(config) {
-    const options = typeof config?.langfuse === "object" ? config.langfuse : {};
+    const options = langfuseOptions(config);
     const publicKey = options.publicKey ?? process.env.LANGFUSE_PUBLIC_KEY;
     const secretKey = options.secretKey ?? process.env.LANGFUSE_SECRET_KEY;
     if (!publicKey || !secretKey) {
@@ -42,9 +95,14 @@ export function createLangfuseExporter(config) {
         publicKey,
         secretKey,
         baseUrl: options.baseUrl ?? process.env.LANGFUSE_BASE_URL,
+        // The released build labelled Langfuse traces from the option and
+        // LANGFUSE_TRACING_ENVIRONMENT / LANGFUSE_RELEASE only (the exporter reads
+        // those two itself); the longer chain feeds the OTLP resource alone.
         environment: options.environment,
         release: options.release,
+        flushBudgetMs: options.flushBudgetMs,
         mask: options.mask,
+        redactIO: options.redactIO,
         maxBufferSize: options.exportMode === "immediate" ? 1 : options.flushAt,
         flushIntervalMs: options.flushInterval === undefined
             ? undefined

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

@@ -1,16 +1,26 @@
 import type { Resource } from "@opentelemetry/resources";
 import { MeterProvider } from "@opentelemetry/sdk-metrics";
 import { type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import type { OtlpConnections } from "../../../../types/index.js";
+/**
+ * @description Tracks the connections the OTLP exporters open, so a flush or shutdown that has run out of its budget can close them instead of leaving a request in flight that holds the process open.
+ * @returns {OtlpConnections} The agent factory to give the exporters and the function that closes what they opened.
+ */
+export declare function createOtlpConnections(): OtlpConnections;
 /**
  * @description Builds a batching span processor that ships spans to an OTLP/HTTP endpoint.
  * @param endpoint {string} - OTLP base URL; `/v1/traces` is appended.
+ * @param budgetMs {number | undefined} - Request timeout in milliseconds, used unless `OTEL_EXPORTER_OTLP_TIMEOUT` or `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` is set; the exporter's default when omitted.
+ * @param connections {OtlpConnections | undefined} - Tracks the connections the exporter opens so they can be closed when a flush runs out of its budget.
  * @returns {SpanProcessor | null} The processor, or `null` (after a warning) when the exporter cannot be created.
  */
-export declare function createOtlpSpanProcessor(endpoint: string): SpanProcessor | null;
+export declare function createOtlpSpanProcessor(endpoint: string, budgetMs?: number, connections?: OtlpConnections): SpanProcessor | null;
 /**
  * @description Builds a meter provider that exports metrics to an OTLP/HTTP endpoint and registers it as the global meter provider.
  * @param endpoint {string} - OTLP base URL; `/v1/metrics` is appended.
  * @param resource {Resource} - Resource describing the service.
+ * @param budgetMs {number | undefined} - Request timeout in milliseconds, used unless `OTEL_EXPORTER_OTLP_TIMEOUT` or `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` is set; the exporter's default when omitted.
+ * @param connections {OtlpConnections | undefined} - Tracks the connections the exporter opens so they can be closed when a flush runs out of its budget.
  * @returns {MeterProvider | null} The provider, or `null` (after a warning) when it cannot be created.
  */
-export declare function createOtlpMeterProvider(endpoint: string, resource: Resource): MeterProvider | null;
+export declare function createOtlpMeterProvider(endpoint: string, resource: Resource, budgetMs?: number, connections?: OtlpConnections): MeterProvider | null;