@juspay/neurolink/dist/services/server/ai/observability/instrumentation.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

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.
 * @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 declare function ensureTelemetry(config?: ObservabilityConfig): void;
/**
 * @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 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.
 * @returns {Promise<void>} Resolves when pending spans are flushed.
 * @throws {Error} When any provider fails to flush.
 */
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.
 * @returns {Promise<void>} Resolves when every owned provider has flushed.
 * @throws {Error} When any provider fails to flush.
 */
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.
 */
export declare function shutdownOpenTelemetry(): Promise<void>;
/**
 * @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 declare function isOpenTelemetryInitialized(): boolean;
/**
 * @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 declare function getLangfuseHealthStatus(): {
    isHealthy: boolean;
    initialized: boolean;
    hasProcessor: boolean;
    usingExternalProvider: boolean;
    error?: string;
};
/**
 * @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 declare function traceMetadataFromContext(ctx: Context): Record<string, SpanContent>;
/**
 * @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
 * await setLangfuseContext({ userId: "u1", sessionId: "s1" }, () => neurolink.generate({ input: { text: "hi" } }));
 */
export declare function setLangfuseContext<T>(params: NeurolinkTraceContext, fn: () => T): T;