@juspay/neurolink 13.5.0 → 13.5.1

package/dist/observability/exporterSpanProcessor.js

@@ -1,6 +1,6 @@
 import { getPropagatedAttributesFromContext } from "@langfuse/core";
 import { SpanStatusCode } from "@opentelemetry/api";
-import { MAX_REMEMBERED_SPANS } from "../constants/telemetry.js";
+import { INTERNAL_SPAN_ATTRIBUTE, MAX_REMEMBERED_SPANS, PROXY_TRACER_SCOPE, } from "../constants/telemetry.js";
 import { SpanStatus, SpanType } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { getExporterRegistry } from "./exporterRegistry.js";
@@ -15,10 +15,36 @@ const OBSERVATION_SPAN_TYPES = {
     evaluator: SpanType.EVALUATION,
     embedding: SpanType.EMBEDDING,
 };
+// OpenTelemetry SDK 1.x spans expose `parentSpanId` and `instrumentationLibrary`;
+// 2.x replaced them with `parentSpanContext` and `instrumentationScope`.
+function legacy(span) {
+    return span;
+}
+function parentIdOf(span) {
+    return span.parentSpanContext?.spanId ?? legacy(span).parentSpanId;
+}
+function scopeOf(span) {
+    const scope = span.instrumentationScope ?? legacy(span).instrumentationLibrary;
+    return (scope && {
+        name: scope.name,
+        ...(scope.version && { version: scope.version }),
+    });
+}
 function isObservation(span) {
     return (span.attributes[LANGFUSE_OBSERVATION_TYPE] !== undefined ||
         span.attributes[GEN_AI_OBSERVATION_TYPE] !== undefined ||
-        Object.keys(span.attributes).some((key) => key.startsWith("gen_ai.")));
+        // The proxy writes gen_ai.* keys on its spans for collectors; of those
+        // spans only the ones it marks with observe() are observations.
+        (scopeOf(span)?.name !== PROXY_TRACER_SCOPE &&
+            Object.keys(span.attributes).some((key) => key.startsWith("gen_ai."))));
+}
+// Only observations are exported, whatever tracer scope they come from: a
+// scope name is not NeuroLink's alone (a host can create a tracer called
+// "http" or "rag"), and the helper spans of NeuroLink's own tracers (http,
+// mcp, memory, file and the rest) were never sent. Wrapper spans marked
+// internal are never exported, observation or not.
+function isExported(span) {
+    return (span.attributes[INTERNAL_SPAN_ATTRIBUTE] !== true && isObservation(span));
 }
 function spanTypeOf(span) {
     const observationType = String(span.attributes[LANGFUSE_OBSERVATION_TYPE] ?? "").toLowerCase();
@@ -40,8 +66,12 @@ function toMillis(time) {
 function toIso(time) {
     return new Date(toMillis(time)).toISOString();
 }
+function toNanos(time) {
+    return (BigInt(time[0]) * 1000000000n + BigInt(time[1])).toString();
+}
 function toSpanData(span, parentSpanId) {
     const { traceId, spanId } = span.spanContext();
+    const scope = scopeOf(span);
     return {
         spanId,
         traceId,
@@ -50,13 +80,21 @@ function toSpanData(span, parentSpanId) {
         name: span.name,
         startTime: toIso(span.startTime),
         endTime: toIso(span.endTime),
+        startTimeUnixNano: toNanos(span.startTime),
+        endTimeUnixNano: toNanos(span.endTime),
         durationMs: toMillis(span.duration),
+        kind: span.kind,
+        ...(span.resource?.attributes && {
+            resource: { ...span.resource.attributes },
+        }),
+        ...(scope && { scope }),
         status: STATUS_BY_CODE[span.status.code],
         ...(span.status.message && { statusMessage: span.status.message }),
         attributes: { ...span.attributes },
         events: span.events.map((event) => ({
             name: event.name,
             timestamp: toIso(event.time),
+            timestampUnixNano: toNanos(event.time),
             ...(event.attributes && { attributes: { ...event.attributes } }),
         })),
         links: span.links.map((link) => ({
@@ -67,18 +105,27 @@ function toSpanData(span, parentSpanId) {
     };
 }
 /**
- * @description OpenTelemetry span processor that turns every observation span into `SpanData` and hands it to an `ExporterRegistry`, so one instrumentation feeds Langfuse, Datadog, Sentry and every other registered exporter. Spans that are not observations are skipped and their children are re-parented onto the nearest exported ancestor. Delivery never blocks the span's thread.
+ * @description OpenTelemetry span processor that turns every observation span into `SpanData` and hands it to an `ExporterRegistry`, so one instrumentation feeds Langfuse, Datadog, Sentry and every other registered exporter. Spans that are not observations (health checks, auth, middleware, NeuroLink's helper spans), wrapper spans marked `langfuse.internal` and spans from other libraries are skipped and their children are re-parented onto the nearest exported ancestor. `shutdown()` shuts the registry's exporters down, as it always did, unless the processor was created to leave them running. Parent ids are read from OpenTelemetry SDK 2.x (`parentSpanContext`) and 1.x (`parentSpanId`) spans alike. At most `MAX_REMEMBERED_SPANS` open and ended spans are remembered for re-parenting; an ancestor of a span that is still open is kept past that limit. Delivery never blocks the span's thread, and a span that cannot be converted is skipped without throwing into the code that ended it.
  */
 export class ExporterSpanProcessor {
     registry;
+    shutsDownExporters;
     open = new Map();
     ended = new Map();
+    // Holds per span id: one for each child that is open or still holds its own
+    // children. An ended span with holds stays resolvable, and keeps its parent
+    // held, until the last open descendant ends, however many unrelated spans
+    // end in between.
+    pins = new Map();
+    evictionLogged = false;
     /**
      * @description Creates a processor bound to a registry.
      * @param registry {ExporterRegistry} - Registry that receives every exported span.
+     * @param shutsDownExporters {boolean} - Whether `shutdown()` also shuts down the registry's exporters; defaults to `true`. Pass `false` for a host provider that is shut down and rebuilt while the exporters stay shared.
      */
-    constructor(registry) {
+    constructor(registry, shutsDownExporters = true) {
         this.registry = registry;
+        this.shutsDownExporters = shutsDownExporters;
     }
     /**
      * @description Copies the propagated Langfuse trace attributes (user, session, trace name, tags, metadata) from the parent context onto the new span and remembers it until it ends.
@@ -87,14 +134,17 @@ export class ExporterSpanProcessor {
      * @returns {void} Nothing.
      */
     onStart(span, parentContext) {
-        span.setAttributes(getPropagatedAttributesFromContext(parentContext));
-        this.open.set(span.spanContext().spanId, span);
-        if (this.open.size > MAX_REMEMBERED_SPANS) {
-            const oldest = this.open.keys().next().value;
-            if (oldest !== undefined) {
-                this.open.delete(oldest);
+        try {
+            span.setAttributes(getPropagatedAttributesFromContext(parentContext));
+            this.open.set(span.spanContext().spanId, span);
+            this.hold(parentIdOf(span));
+            if (this.open.size > MAX_REMEMBERED_SPANS) {
+                this.evictOldestOpen();
             }
         }
+        catch (error) {
+            this.contain("start", span.name, error);
+        }
     }
     /**
      * @description Exports an ended observation span without waiting for the exporters.
@@ -102,15 +152,26 @@ export class ExporterSpanProcessor {
      * @returns {void} Nothing.
      */
     onEnd(span) {
-        const { spanId } = span.spanContext();
-        this.open.delete(spanId);
-        const observation = isObservation(span);
-        this.remember(spanId, span.parentSpanContext?.spanId, observation);
-        if (!observation) {
-            return;
+        try {
+            const { spanId } = span.spanContext();
+            const exported = isExported(span);
+            // Resolved before this span lets go of its ancestors, which the next
+            // trim may then drop.
+            const parentSpanId = exported
+                ? this.nearestExportedAncestor(span)
+                : undefined;
+            if (this.open.delete(spanId) && !this.pins.has(spanId)) {
+                this.release(parentIdOf(span));
+            }
+            this.remember(spanId, parentIdOf(span), exported);
+            if (!exported) {
+                return;
+            }
+            void this.exportQuietly(toSpanData(span, parentSpanId));
+        }
+        catch (error) {
+            this.contain("end", span.name, error);
         }
-        const spanData = toSpanData(span, this.nearestExportedAncestor(span));
-        void this.exportQuietly(spanData);
     }
     /**
      * @description Flushes every exporter in the registry.
@@ -120,11 +181,21 @@ export class ExporterSpanProcessor {
         return this.registry.flushAll();
     }
     /**
-     * @description Shuts down every exporter in the registry.
-     * @returns {Promise<void>} Resolves when all exporters have shut down.
+     * @description Shuts down every exporter in the registry, or only flushes them when the processor was created to leave them running.
+     * @returns {Promise<void>} Resolves when the exporters have shut down or flushed.
      */
     shutdown() {
-        return this.registry.shutdownAll();
+        return this.shutsDownExporters
+            ? this.registry.shutdownAll()
+            : this.registry.flushAll();
+    }
+    // Telemetry must not fail the code that created the span: the SDK calls
+    // these hooks from span.start() and span.end() without a guard.
+    contain(stage, spanName, error) {
+        logger.debug(`[ExporterSpanProcessor] Could not process span on ${stage}`, {
+            span: spanName,
+            error: error instanceof Error ? error.message : String(error),
+        });
     }
     async exportQuietly(spanData) {
         try {
@@ -137,31 +208,88 @@ export class ExporterSpanProcessor {
             });
         }
     }
-    remember(spanId, parentSpanId, observation) {
-        this.ended.set(spanId, { parentSpanId, observation });
-        if (this.ended.size > MAX_REMEMBERED_SPANS) {
-            const oldest = this.ended.keys().next().value;
-            if (oldest !== undefined) {
-                this.ended.delete(oldest);
+    // An open span holds its parent from its start; an ended span holds its
+    // parent while it has holds of its own. The first hold on an ended span
+    // therefore takes a hold on its parent, and so on up the chain.
+    hold(spanId) {
+        for (let current = spanId; current;) {
+            const held = this.pins.get(current) ?? 0;
+            this.pins.set(current, held + 1);
+            if (held > 0 || this.open.has(current)) {
+                return;
+            }
+            current = this.ended.get(current)?.parentSpanId;
+        }
+    }
+    // The last hold on an ended span releases its hold on its parent.
+    release(spanId) {
+        for (let current = spanId; current;) {
+            const remaining = (this.pins.get(current) ?? 0) - 1;
+            if (remaining > 0) {
+                this.pins.set(current, remaining);
+                return;
+            }
+            this.pins.delete(current);
+            if (this.open.has(current)) {
+                return;
+            }
+            current = this.ended.get(current)?.parentSpanId;
+        }
+    }
+    // The oldest open span, usually a long-lived root, moves to the ended map
+    // with what its descendants need, instead of vanishing and orphaning them.
+    evictOldestOpen() {
+        const oldest = this.open.entries().next().value;
+        if (oldest === undefined) {
+            return;
+        }
+        const [spanId, live] = oldest;
+        this.open.delete(spanId);
+        this.remember(spanId, parentIdOf(live), isExported(live));
+        if (!this.pins.has(spanId)) {
+            this.release(parentIdOf(live));
+        }
+        if (!this.evictionLogged) {
+            this.evictionLogged = true;
+            logger.debug(`[ExporterSpanProcessor] More than ${MAX_REMEMBERED_SPANS} spans are open; the oldest are remembered only for re-parenting`);
+        }
+    }
+    remember(spanId, parentSpanId, exported) {
+        this.ended.delete(spanId);
+        this.ended.set(spanId, { parentSpanId, exported });
+        this.trimEnded();
+    }
+    // Drops the oldest entries that no open span descends from; a pinned entry
+    // goes to the back so the next trim does not meet it first again.
+    trimEnded() {
+        for (let attempts = this.ended.size; this.ended.size > MAX_REMEMBERED_SPANS && attempts > 0; attempts -= 1) {
+            const oldest = this.ended.entries().next().value;
+            if (oldest === undefined) {
+                return;
+            }
+            const [spanId, entry] = oldest;
+            this.ended.delete(spanId);
+            if (this.pins.has(spanId)) {
+                this.ended.set(spanId, entry);
             }
         }
     }
     nearestExportedAncestor(span) {
-        let candidate = span.parentSpanContext?.spanId;
+        let candidate = parentIdOf(span);
         while (candidate) {
             const live = this.open.get(candidate);
             if (live) {
-                if (isObservation(live)) {
+                if (isExported(live)) {
                     return candidate;
                 }
-                candidate = live.parentSpanContext?.spanId;
+                candidate = parentIdOf(live);
                 continue;
             }
             const finished = this.ended.get(candidate);
             if (!finished) {
                 return undefined;
             }
-            if (finished.observation) {
+            if (finished.exported) {
                 return candidate;
             }
             candidate = finished.parentSpanId;
@@ -170,12 +298,16 @@ export class ExporterSpanProcessor {
     }
 }
 /**
- * @description Creates a span processor that feeds NeuroLink's observation spans to an exporter registry. Add it to a host `TracerProvider` to deliver spans through the registered exporters (such as `LangfuseExporter`) instead of `LangfuseSpanProcessor`.
+ * @description Creates a span processor that feeds NeuroLink's observation spans to an exporter registry. Add it to a host `TracerProvider` to deliver spans through the registered exporters (such as `LangfuseExporter`) instead of `LangfuseSpanProcessor`. Shutting that provider down shuts the registry's exporters down; pass `{ shutdownExporters: false }` to flush them and leave them running, so a provider the host rebuilds keeps exporting.
  * @param registry {ExporterRegistry} - Registry to export to; defaults to the process-wide registry.
+ * @param options {ExporterSpanProcessorOptions} - `shutdownExporters` (default `true`) says whether the processor's `shutdown()` also shuts down the registry's exporters.
  * @returns {ExporterSpanProcessor} A processor ready to be added to a TracerProvider.
  * @example
  * const provider = new NodeTracerProvider({ spanProcessors: [createExporterSpanProcessor()] });
+ * @example
+ * // A host provider that is shut down and rebuilt over the same exporters
+ * const processor = createExporterSpanProcessor(getExporterRegistry(), { shutdownExporters: false });
  */
-export function createExporterSpanProcessor(registry = getExporterRegistry()) {
-    return new ExporterSpanProcessor(registry);
+export function createExporterSpanProcessor(registry = getExporterRegistry(), options = {}) {
+    return new ExporterSpanProcessor(registry, options.shutdownExporters ?? true);
 }

package/dist/observability/exporters/baseExporter.d.ts

@@ -2,7 +2,24 @@
  * Abstract base class for all observability exporters
  * Follows NeuroLink's factory pattern with a unified exporter interface
  */
-import type { ExporterConfig, ExporterHealthStatus, ExportResult, SpanData } from "../../types/index.js";
+import type { ExporterConfig, ExporterDeliveryCounts, ExporterHealthStatus, ExporterStatus, ExportResult, SpanData } from "../../types/index.js";
+/**
+ * Backoff of `withRetry` unless its caller passes another: one second, doubled
+ * for every attempt that failed.
+ */
+export declare function exponentialRetryDelayMs(_error: unknown, attempt: number): number;
+/**
+ * Lets an exporter that counts its own deliveries, instead of through
+ * `createSuccessResult` and `createFailureResult`, say what it counted.
+ */
+export declare function reportDeliveriesWith(exporter: BaseExporter, read: () => ExporterDeliveryCounts): void;
+/**
+ * Snapshot of a registered exporter for status reporting, without a network
+ * call. It reads only what every exporter has had since the first release
+ * (`getName`, `isInitialized`, `getPendingCount`, `getLastExportTime`), so an
+ * exporter written in plain JavaScript against that set is reported too.
+ */
+export declare function exporterStatusOf(exporter: BaseExporter): ExporterStatus;
 /**
  * Abstract base class for all observability exporters
  * Provides common functionality: buffering, flush intervals, health checks, retry logic
@@ -97,10 +114,12 @@ export declare abstract class BaseExporter {
      * Execute an operation with exponential backoff retry
      * @param operation - The async operation to execute
      * @param operationName - Name for logging purposes
+     * @param signal - Stops further attempts and cuts a backoff wait short when aborted
+     * @param delayMs - Milliseconds to wait before the next attempt, given why the attempt failed and its zero-based number; one second doubled per attempt by default
      * @returns The result of the operation
-     * @throws The last error if all retries fail
+     * @throws The last error if all retries fail, or the abort reason when the signal fires
      */
-    protected withRetry<T>(operation: () => Promise<T>, operationName: string): Promise<T>;
+    protected withRetry<T>(operation: () => Promise<T>, operationName: string, signal?: AbortSignal, delayMs?: (error: unknown, attempt: number) => number): Promise<T>;
 }
 /**
  * No-op exporter for when observability is disabled

package/dist/observability/exporters/baseExporter.js

@@ -3,6 +3,56 @@
  * Follows NeuroLink's factory pattern with a unified exporter interface
  */
 import { logger } from "../../utils/logger.js";
+// What each exporter delivered and dropped is kept here, not on the instance:
+// a subclass written before these counts existed may declare a member of any
+// name, and a plain-JavaScript exporter has no counts at all.
+const deliveryTallies = new WeakMap();
+const deliveryReaders = new WeakMap();
+const NO_DELIVERIES = {
+    delivered: 0,
+    failed: 0,
+    lastError: undefined,
+};
+/**
+ * Backoff of `withRetry` unless its caller passes another: one second, doubled
+ * for every attempt that failed.
+ */
+export function exponentialRetryDelayMs(_error, attempt) {
+    return 1000 * 2 ** attempt;
+}
+/**
+ * Lets an exporter that counts its own deliveries, instead of through
+ * `createSuccessResult` and `createFailureResult`, say what it counted.
+ */
+export function reportDeliveriesWith(exporter, read) {
+    deliveryReaders.set(exporter, read);
+}
+/**
+ * Snapshot of a registered exporter for status reporting, without a network
+ * call. It reads only what every exporter has had since the first release
+ * (`getName`, `isInitialized`, `getPendingCount`, `getLastExportTime`), so an
+ * exporter written in plain JavaScript against that set is reported too.
+ */
+export function exporterStatusOf(exporter) {
+    const { delivered, failed, lastError } = (deliveryReaders.get(exporter) ??
+        (() => deliveryTallies.get(exporter) ?? NO_DELIVERIES))();
+    const initialized = exporter.isInitialized();
+    const lastExportTime = typeof exporter.getLastExportTime === "function"
+        ? exporter.getLastExportTime()
+        : 0;
+    return {
+        name: exporter.getName(),
+        enabled: initialized,
+        healthy: initialized && lastError === undefined,
+        pendingSpans: exporter.getPendingCount(),
+        deliveredSpans: delivered,
+        failedSpans: failed,
+        ...(lastExportTime > 0 && {
+            lastExportTime: new Date(lastExportTime).toISOString(),
+        }),
+        ...(lastError !== undefined && { errors: [lastError] }),
+    };
+}
 /**
  * Abstract base class for all observability exporters
  * Provides common functionality: buffering, flush intervals, health checks, retry logic
@@ -95,6 +145,12 @@ export class BaseExporter {
      */
     createSuccessResult(exportedCount, durationMs) {
         this.lastExportTime = Date.now();
+        const tally = deliveryTallies.get(this) ?? NO_DELIVERIES;
+        deliveryTallies.set(this, {
+            delivered: tally.delivered + exportedCount,
+            failed: tally.failed,
+            lastError: undefined,
+        });
         return {
             success: true,
             exportedCount,
@@ -106,6 +162,12 @@ export class BaseExporter {
      * Create a standard export result for failure
      */
     createFailureResult(spanIds, error, durationMs, retryable = true) {
+        const tally = deliveryTallies.get(this) ?? NO_DELIVERIES;
+        deliveryTallies.set(this, {
+            delivered: tally.delivered,
+            failed: tally.failed + spanIds.length,
+            lastError: error,
+        });
         return {
             success: false,
             exportedCount: 0,
@@ -134,33 +196,53 @@ export class BaseExporter {
      * Execute an operation with exponential backoff retry
      * @param operation - The async operation to execute
      * @param operationName - Name for logging purposes
+     * @param signal - Stops further attempts and cuts a backoff wait short when aborted
+     * @param delayMs - Milliseconds to wait before the next attempt, given why the attempt failed and its zero-based number; one second doubled per attempt by default
      * @returns The result of the operation
-     * @throws The last error if all retries fail
+     * @throws The last error if all retries fail, or the abort reason when the signal fires
      */
-    async withRetry(operation, operationName) {
+    async withRetry(operation, operationName, signal, delayMs = exponentialRetryDelayMs) {
         const maxRetries = this.retries;
-        const baseDelay = 1000;
         let lastError;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            signal?.throwIfAborted();
             try {
                 return await operation();
             }
             catch (error) {
                 lastError = error;
+                if (signal?.aborted) {
+                    break;
+                }
                 if (attempt < maxRetries) {
-                    const delay = baseDelay * 2 ** attempt;
+                    const delay = delayMs(lastError, attempt);
                     logger.warn(`[${this.name}] ${operationName} failed, retrying in ${delay}ms`, {
                         attempt: attempt + 1,
                         maxRetries,
                         error: lastError.message,
                     });
-                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    await sleepUnlessAborted(delay, signal);
                 }
             }
         }
         throw lastError;
     }
 }
+function sleepUnlessAborted(delayMs, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, delayMs);
+        signal?.addEventListener("abort", finish, { once: true });
+    });
+}
 /**
  * No-op exporter for when observability is disabled
  * Provides zero-overhead behavior

package/dist/observability/exporters/langfuseExporter.d.ts

@@ -1,27 +1,53 @@
-import type { ExporterHealthStatus, ExportResult, LangfuseExporterConfig, SpanData } from "../../types/index.js";
+import type { ExporterHealthStatus, ExporterStatus, ExportResult, LangfuseExporterConfig, SpanData } from "../../types/index.js";
 import { BaseExporter } from "./baseExporter.js";
 /**
- * @description Exporter that delivers observation spans to Langfuse's OTLP/HTTP JSON endpoint (`POST /api/public/otel/v1/traces`), which keeps native observation types and identity on every observation. Spans are queued without blocking and sent in batches; failed requests are retried with backoff when the failure is transient (429, 5xx, network).
+ * @description Exporter that delivers observation spans to Langfuse's OTLP/HTTP JSON endpoint (`POST /api/public/otel/v1/traces`), which keeps native observation types and identity on every observation. Spans are queued without blocking and sent in batches, with at most `MAX_CONCURRENT_DELIVERIES` requests in flight; spans that end while every one is busy wait, at most `MAX_QUEUED_SPANS` of them, and the oldest beyond that are dropped, counted and warned about once a minute. Failed requests are retried with backoff when the failure is transient (429, 5xx, network), after the `Retry-After` of a 429 or 503 when it names one (at most `MAX_EXPORT_RETRY_AFTER_MS`). `flush()` and `shutdown()` wait at most `flushBudgetMs` and then drop what is still in flight, and a batch that could not be delivered is reported by `exportBatch`, logged at warn level and counted in the health check; when Langfuse took none of the latest batch (refused, failed or every span rejected), `getStatus()` and `healthCheck()` read unhealthy with the dropped count until a batch is accepted again. `exportSpan` reports only the buffer step, so a failed delivery never opens the registry's circuit breaker and spans that end after an outage are still buffered and sent.
  */
 export declare class LangfuseExporter extends BaseExporter {
     private readonly langfuse;
     private readonly authorization;
     private readonly baseUrl;
     private readonly policy;
+    private readonly flushBudgetMs;
     private readonly inflight;
+    private delivery;
+    private droppedSpans;
+    private acceptedSpans;
+    private lastDeliveryError;
+    private unwarnedQueueDrops;
+    private lastQueueDropWarning;
     /**
      * @description Creates an exporter for one Langfuse project.
-     * @param config {LangfuseExporterConfig} - Credentials, endpoint, environment, release, masking and batching options. `environment` and `release` fall back to `LANGFUSE_TRACING_ENVIRONMENT` and `LANGFUSE_RELEASE`, and only fill spans that do not carry them already.
+     * @param config {LangfuseExporterConfig} - Credentials, endpoint, environment, release, masking, batching and flush-budget options. `environment` and `release` fall back to `LANGFUSE_TRACING_ENVIRONMENT` and `LANGFUSE_RELEASE`, and only fill spans that do not carry them already.
      */
     constructor(langfuse: LangfuseExporterConfig);
     initialize(): Promise<void>;
     exportSpan(span: SpanData): Promise<ExportResult>;
     exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    /**
+     * @description Sends everything buffered and waits for delivery, but no longer than the flush budget; spans still in flight when it runs out are dropped and counted, and spans still waiting for a delivery slot stay buffered.
+     * @returns {Promise<void>} Resolves when delivery finished or the budget ran out.
+     */
     flush(): Promise<void>;
+    protected bufferSpan(span: SpanData): void;
+    private dispatch;
+    private dropOldestWaiting;
+    private settle;
+    private nextDelivery;
     private exportQuietly;
+    /**
+     * @description Delivers what is buffered, including spans that end while it drains, within the flush budget, then stops the exporter. Spans that could not be sent by then are dropped and counted, so none is left pending.
+     * @returns {Promise<void>} Resolves when the exporter has stopped.
+     */
     shutdown(): Promise<void>;
+    /**
+     * @description Snapshot of this exporter for status reporting, without a network call: what is queued, what Langfuse accepted and what was dropped, and unhealthy while the latest delivery failed.
+     * @returns {ExporterStatus} The exporter's current state.
+     */
+    getStatus(): ExporterStatus;
     healthCheck(): Promise<ExporterHealthStatus>;
     protected ping(): Promise<void>;
+    private record;
     private deliver;
     private post;
 }