@juspay/neurolink 13.5.0 → 13.6.0

package/dist/observability/exporters/langfuseExporter.js

@@ -1,23 +1,81 @@
-import { DEFAULT_BASE_URL, DEFAULT_FLUSH_AT, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, HEALTH_PATH, TRACES_PATH, } from "../../constants/langfuse.js";
+import { DEFAULT_BASE_URL, DEFAULT_FLUSH_AT, DEFAULT_FLUSH_BUDGET_MS, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, HEALTH_PATH, MAX_CONCURRENT_DELIVERIES, MAX_EXPORT_RETRY_AFTER_MS, MAX_QUEUED_SPANS, MAX_SPANS_PER_REQUEST, QUEUE_DROP_WARN_INTERVAL_MS, TRACES_PATH, } from "../../constants/langfuse.js";
 import { logger } from "../../utils/logger.js";
-import { chunkOtlpSpans, toOtlpAttributes, toOtlpSpan, } from "../otlpEncoding.js";
-import { BaseExporter } from "./baseExporter.js";
+import { parseRetryAfterMs } from "../../utils/retryAfter.js";
+import { chunkOtlpSpans, toOtlpEncodedSpan, toOtlpRequest, } from "../otlpEncoding.js";
+import { BaseExporter, exponentialRetryDelayMs, exporterStatusOf, reportDeliveriesWith, } from "./baseExporter.js";
 let credentialsWarned = false;
+let malformedRejectionLogged = false;
 function isRetryable(status) {
     return status === 429 || status >= 500;
 }
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function retryAfterOf(error) {
+    return error instanceof Error &&
+        "retryAfterMs" in error &&
+        typeof error.retryAfterMs === "number"
+        ? error.retryAfterMs
+        : undefined;
+}
+// A flush or shutdown still ends at its budget: the delivery signal cuts the
+// wait short.
+function retryDelayFor(error, attempt) {
+    const requested = retryAfterOf(error);
+    return requested === undefined
+        ? exponentialRetryDelayMs(error, attempt)
+        : Math.min(requested, MAX_EXPORT_RETRY_AFTER_MS);
+}
+function partialSuccessOf(body) {
+    return typeof body === "object" &&
+        body !== null &&
+        "partialSuccess" in body &&
+        typeof body.partialSuccess === "object" &&
+        body.partialSuccess !== null
+        ? body.partialSuccess
+        : undefined;
+}
+// A count Langfuse cannot have meant (not a whole number, negative, or more
+// than was sent) is read as none, so it neither hides earlier drops nor
+// invents new ones.
+function rejectedCount(partial, sent) {
+    const raw = partial && "rejectedSpans" in partial ? partial.rejectedSpans : undefined;
+    if (raw === undefined) {
+        return 0;
+    }
+    const count = typeof raw === "number" || typeof raw === "string"
+        ? Number(raw)
+        : Number.NaN;
+    if (Number.isInteger(count) && count >= 0 && count <= sent) {
+        return count;
+    }
+    if (!malformedRejectionLogged) {
+        malformedRejectionLogged = true;
+        logger.debug("[langfuse] Ignoring a partialSuccess.rejectedSpans that is not a count of the spans sent", { sent });
+    }
+    return 0;
+}
 /**
- * @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 class LangfuseExporter extends BaseExporter {
     langfuse;
     authorization;
     baseUrl;
     policy;
+    flushBudgetMs;
     inflight = new Set();
+    delivery = new AbortController();
+    droppedSpans = 0;
+    // Counted when Langfuse accepts a batch; the base counter also counts a span
+    // queued by exportSpan, which is not a delivery.
+    acceptedSpans = 0;
+    lastDeliveryError;
+    unwarnedQueueDrops = 0;
+    lastQueueDropWarning = 0;
     /**
      * @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) {
         super("langfuse", {
@@ -27,12 +85,21 @@ export class LangfuseExporter extends BaseExporter {
         this.langfuse = langfuse;
         this.authorization = `Basic ${Buffer.from(`${langfuse.publicKey}:${langfuse.secretKey}`).toString("base64")}`;
         this.baseUrl = (langfuse.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.flushBudgetMs =
+            langfuse.flushBudgetMs !== undefined && langfuse.flushBudgetMs > 0
+                ? langfuse.flushBudgetMs
+                : DEFAULT_FLUSH_BUDGET_MS;
         this.policy = {
             environment: langfuse.environment ?? process.env.LANGFUSE_TRACING_ENVIRONMENT,
             release: langfuse.release ?? process.env.LANGFUSE_RELEASE,
             redactIO: langfuse.redactIO ?? false,
             mask: langfuse.mask,
         };
+        reportDeliveriesWith(this, () => ({
+            delivered: this.acceptedSpans,
+            failed: this.droppedSpans,
+            lastError: this.lastDeliveryError,
+        }));
     }
     async initialize() {
         if (this.initialized) {
@@ -42,8 +109,10 @@ export class LangfuseExporter extends BaseExporter {
             throw new Error("Langfuse publicKey and secretKey are required");
         }
         this.initialized = true;
-        this.startFlushInterval(this.config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
-        this.flushInterval?.unref();
+        // Periodic and size-triggered sends are not subject to the flush budget:
+        // only a caller that waits for delivery is.
+        this.flushInterval = setInterval(() => this.dispatch(), this.config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS);
+        this.flushInterval.unref();
     }
     async exportSpan(span) {
         this.bufferSpan(span);
@@ -51,41 +120,132 @@ export class LangfuseExporter extends BaseExporter {
     }
     async exportBatch(spans) {
         const startTime = Date.now();
-        await this.deliver(spans.map((span) => toOtlpSpan(span, this.policy)));
-        return this.createSuccessResult(spans.length, Date.now() - startTime);
+        const report = await this.deliver(spans.map((span) => toOtlpEncodedSpan(span, this.policy)), this.delivery.signal);
+        return this.record(spans.length, report, Date.now() - startTime);
     }
+    /**
+     * @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.
+     */
     async flush() {
-        const spans = this.buffer;
-        this.buffer = [];
-        if (spans.length > 0) {
+        await this.settle();
+    }
+    bufferSpan(span) {
+        this.buffer.push(span);
+        if (this.buffer.length >= this.maxBufferSize ||
+            this.buffer.length > MAX_QUEUED_SPANS) {
+            this.dispatch();
+        }
+        if (this.buffer.length > MAX_QUEUED_SPANS) {
+            this.dropOldestWaiting(this.buffer.length - MAX_QUEUED_SPANS);
+        }
+    }
+    dispatch() {
+        while (this.buffer.length > 0 &&
+            this.inflight.size < MAX_CONCURRENT_DELIVERIES) {
+            const spans = this.buffer.slice(0, MAX_SPANS_PER_REQUEST);
+            this.buffer = this.buffer.slice(spans.length);
             const pending = this.exportQuietly(spans);
             this.inflight.add(pending);
             void pending.finally(() => this.inflight.delete(pending));
         }
-        await Promise.all(this.inflight);
+    }
+    // Langfuse is not taking spans as fast as they end. Spans keep being
+    // accepted, so the oldest waiting ones make room; no breaker is involved.
+    dropOldestWaiting(count) {
+        this.buffer = this.buffer.slice(count);
+        this.droppedSpans += count;
+        this.unwarnedQueueDrops += count;
+        this.lastDeliveryError = `${MAX_CONCURRENT_DELIVERIES} deliveries in flight and ${MAX_QUEUED_SPANS} spans waiting; dropping the oldest`;
+        const now = Date.now();
+        if (now - this.lastQueueDropWarning >= QUEUE_DROP_WARN_INTERVAL_MS) {
+            logger.warn(`[langfuse] Langfuse is not keeping up; dropped the ${this.unwarnedQueueDrops} oldest waiting spans`);
+            this.lastQueueDropWarning = now;
+            this.unwarnedQueueDrops = 0;
+        }
+    }
+    // Deliveries free their slot for the next waiting spans until nothing is
+    // left or the budget runs out, so spans that end meanwhile are sent too.
+    async settle() {
+        const deadline = Date.now() + this.flushBudgetMs;
+        for (this.dispatch(); this.inflight.size > 0; this.dispatch()) {
+            if ((await this.nextDelivery(deadline)) === "expired") {
+                logger.warn(`[langfuse] Delivery did not finish within ${this.flushBudgetMs}ms; dropping what is still in flight`);
+                const abandoned = this.delivery;
+                this.delivery = new AbortController();
+                abandoned.abort(new Error("Langfuse flush budget exhausted"));
+                await Promise.all(this.inflight);
+                return;
+            }
+        }
+    }
+    async nextDelivery(deadline) {
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("expired"), Math.max(0, deadline - Date.now()));
+        });
+        const outcome = await Promise.race([
+            Promise.race(this.inflight).then(() => "delivered"),
+            expired,
+        ]);
+        clearTimeout(timer);
+        return outcome;
     }
     async exportQuietly(spans) {
         try {
             await this.exportBatch(spans);
         }
         catch (error) {
+            this.droppedSpans += spans.length;
+            this.lastDeliveryError = messageOf(error);
             logger.warn("[langfuse] Export failed", {
-                error: error instanceof Error ? error.message : String(error),
+                error: this.lastDeliveryError,
             });
         }
     }
+    /**
+     * @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.
+     */
     async shutdown() {
-        await this.flush();
+        await this.settle();
         this.stopFlushInterval();
         this.initialized = false;
+        const stranded = this.buffer.length;
+        if (stranded > 0) {
+            this.buffer = [];
+            this.droppedSpans += stranded;
+            this.lastDeliveryError = "Langfuse exporter shut down before delivery";
+            logger.warn(`[langfuse] Dropped ${stranded} spans still waiting at shutdown`);
+        }
+    }
+    /**
+     * @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() {
+        return exporterStatusOf(this);
     }
+    // Reachable is not enough: like getStatus(), the exporter reads unhealthy
+    // while its latest delivery failed, until Langfuse accepts a batch again.
     async healthCheck() {
+        const problems = [
+            ...(this.lastDeliveryError !== undefined ? [this.lastDeliveryError] : []),
+            ...(this.droppedSpans > 0
+                ? [
+                    `${this.droppedSpans} ${this.droppedSpans === 1 ? "span" : "spans"} dropped since start`,
+                ]
+                : []),
+        ];
         try {
             await this.withRetry(() => this.ping(), "health check");
-            return this.createHealthStatus(true);
+            return this.createHealthStatus(this.lastDeliveryError === undefined, problems.length > 0 ? problems : undefined);
         }
         catch {
-            return this.createHealthStatus(false, ["Health check failed"]);
+            return this.createHealthStatus(false, [
+                "Health check failed",
+                ...problems,
+            ]);
         }
     }
     async ping() {
@@ -97,19 +257,67 @@ export class LangfuseExporter extends BaseExporter {
             throw new Error(`Langfuse API unreachable: ${response.status}`);
         }
     }
-    async deliver(spans) {
-        for (const chunk of chunkOtlpSpans(spans)) {
+    record(total, report, durationMs) {
+        if (total === 0) {
+            return this.createSuccessResult(0, durationMs);
+        }
+        const failed = report.droppedIds.length + report.rejected;
+        this.droppedSpans += failed;
+        // Langfuse took none of the batch, refused or rejected: that is a failed
+        // delivery even when the response was a 200 with partialSuccess.
+        this.lastDeliveryError =
+            report.delivered === 0 && failed > 0
+                ? `Dropped ${failed} of ${total} spans: ${report.error ?? "Langfuse rejected every span"}`
+                : report.error;
+        if (failed > 0) {
+            logger.warn(`[langfuse] Dropped ${failed} of ${total} spans`, {
+                error: report.error,
+            });
+        }
+        if (report.delivered > 0) {
+            this.lastExportTime = Date.now();
+            this.acceptedSpans += report.delivered;
+        }
+        return {
+            success: failed === 0,
+            exportedCount: report.delivered,
+            failedCount: failed,
+            ...(report.droppedIds.length > 0 && {
+                errors: report.droppedIds.map((spanId) => ({
+                    spanId,
+                    error: report.error ?? "Delivery failed",
+                    retryable: true,
+                })),
+            }),
+            durationMs,
+        };
+    }
+    async deliver(items, signal) {
+        const report = {
+            delivered: 0,
+            rejected: 0,
+            droppedIds: [],
+        };
+        for (const chunk of chunkOtlpSpans(items)) {
             try {
-                await this.withRetry(() => this.post(chunk), "export");
+                const outcome = await this.withRetry(() => this.post(chunk, signal), "export", signal, retryDelayFor);
+                if (outcome.accepted) {
+                    report.delivered += chunk.length - outcome.rejected;
+                    report.rejected += outcome.rejected;
+                }
+                else {
+                    report.droppedIds.push(...chunk.map(({ span }) => span.spanId));
+                    report.error = "Langfuse did not accept the batch";
+                }
             }
             catch (error) {
-                logger.warn(`[langfuse] Dropped ${chunk.length} spans`, {
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                report.droppedIds.push(...chunk.map(({ span }) => span.spanId));
+                report.error = messageOf(error);
             }
         }
+        return report;
     }
-    async post(spans) {
+    async post(chunk, signal) {
         const response = await fetch(`${this.baseUrl}${TRACES_PATH}`, {
             method: "POST",
             headers: {
@@ -119,38 +327,40 @@ export class LangfuseExporter extends BaseExporter {
                 "x-langfuse-ingestion-version": "4",
                 "x-langfuse-public-key": this.langfuse.publicKey,
             },
-            body: JSON.stringify({
-                resourceSpans: [
-                    {
-                        resource: {
-                            attributes: toOtlpAttributes({ "service.name": "service" }),
-                        },
-                        scopeSpans: [{ scope: { name: "sdk" }, spans }],
-                    },
-                ],
-            }),
-            signal: AbortSignal.timeout(this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            body: JSON.stringify(toOtlpRequest(chunk)),
+            signal: AbortSignal.any([
+                AbortSignal.timeout(this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+                signal,
+            ]),
         });
         if (response.status === 401 || response.status === 403) {
             if (!credentialsWarned) {
                 credentialsWarned = true;
                 logger.warn("[langfuse] Langfuse credentials rejected");
             }
-            return;
+            return { accepted: false };
         }
         if (isRetryable(response.status)) {
-            throw new Error(`Langfuse API error: ${response.status}`);
+            const retryAfterMs = response.status === 429 || response.status === 503
+                ? parseRetryAfterMs(response.headers)
+                : undefined;
+            throw Object.assign(new Error(`Langfuse API error: ${response.status}`), retryAfterMs === undefined ? {} : { retryAfterMs });
         }
         if (!response.ok) {
             logger.warn(`[langfuse] Export rejected with ${response.status}`);
-            return;
+            return { accepted: false };
         }
-        const body = (await response.json().catch(() => ({})));
-        const rejected = Number(body.partialSuccess?.rejectedSpans ?? 0);
+        // Langfuse took the request; a body that is not an object, or not JSON,
+        // reports no rejections.
+        const partial = partialSuccessOf(await response.json().catch(() => undefined));
+        const rejected = rejectedCount(partial, chunk.length);
         if (rejected > 0) {
             logger.warn(`[langfuse] ${rejected} spans rejected`, {
-                message: body.partialSuccess?.errorMessage,
+                message: partial && "errorMessage" in partial
+                    ? partial.errorMessage
+                    : undefined,
             });
         }
+        return { accepted: true, rejected };
     }
 }

package/dist/observability/langfuseMasking.d.ts

@@ -1,6 +1,6 @@
 import type { LangfuseAttributePolicy, SpanAttributes } from "../types/index.js";
 /**
- * @description Applies the exporter's policy to a span's attributes: fills environment and release when the span has none, removes input and output when `redactIO` is set, and masks input, output and metadata when a mask is configured.
+ * @description Applies the Langfuse exporter's policy to a span's attributes as they are sent to Langfuse: fills environment and release when the span has none, removes input and output when `redactIO` is set, and masks input, output and metadata when a mask is configured. Nothing else is touched: other attributes, events and the status message go to Langfuse as they are, and no other exporter sees the policy.
  * @param attributes {SpanAttributes} - Attributes of the span being exported.
  * @param policy {LangfuseAttributePolicy} - Environment, release, redaction and mask settings.
  * @returns {SpanAttributes} A new attribute record; the input is not modified.

package/dist/observability/langfuseMasking.js

@@ -18,7 +18,7 @@ function maskValue(value, mask) {
     }
 }
 /**
- * @description Applies the exporter's policy to a span's attributes: fills environment and release when the span has none, removes input and output when `redactIO` is set, and masks input, output and metadata when a mask is configured.
+ * @description Applies the Langfuse exporter's policy to a span's attributes as they are sent to Langfuse: fills environment and release when the span has none, removes input and output when `redactIO` is set, and masks input, output and metadata when a mask is configured. Nothing else is touched: other attributes, events and the status message go to Langfuse as they are, and no other exporter sees the policy.
  * @param attributes {SpanAttributes} - Attributes of the span being exported.
  * @param policy {LangfuseAttributePolicy} - Environment, release, redaction and mask settings.
  * @returns {SpanAttributes} A new attribute record; the input is not modified.

package/dist/observability/otlpEncoding.d.ts

@@ -1,4 +1,4 @@
-import type { LangfuseAttributePolicy, OtlpKeyValue, OtlpSpan, SpanAttributes, SpanData } from "../types/index.js";
+import type { LangfuseAttributePolicy, OtlpEncodedSpan, OtlpKeyValue, OtlpSpan, OtlpTraceRequest, SpanAttributes, SpanData } from "../types/index.js";
 /**
  * @description Encodes attributes as OTLP/JSON key-values, dropping `undefined` and `null` entries.
  * @param attributes {SpanAttributes} - Attribute record to encode.
@@ -6,15 +6,28 @@ import type { LangfuseAttributePolicy, OtlpKeyValue, OtlpSpan, SpanAttributes, S
  */
 export declare function toOtlpAttributes(attributes: SpanAttributes): OtlpKeyValue[];
 /**
- * @description Encodes one span as OTLP/JSON, applying the exporter's attribute policy to its attributes.
+ * @description Encodes one span as OTLP/JSON, applying the exporter's attribute policy to its attributes (its events and status message are sent as they are), leaving GenAI model and usage keys off a plain span or event observation, and keeping the span's links and nanosecond times. Every span is sent as kind INTERNAL, as Langfuse has always received it.
  * @param span {SpanData} - Span to encode.
  * @param policy {LangfuseAttributePolicy} - Environment, release, redaction and mask settings.
  * @returns {OtlpSpan} The span in the shape Langfuse's ingestion endpoint reads.
  */
 export declare function toOtlpSpan(span: SpanData, policy: LangfuseAttributePolicy): OtlpSpan;
+/**
+ * @description Encodes a span together with the resource it was produced under, falling back to a generic service name for a span that carries none, and the instrumentation scope `sdk` that the Langfuse request has always named.
+ * @param span {SpanData} - Span to encode.
+ * @param policy {LangfuseAttributePolicy} - Environment, release, redaction and mask settings.
+ * @returns {OtlpEncodedSpan} The encoded span with its resource and scope.
+ */
+export declare function toOtlpEncodedSpan(span: SpanData, policy: LangfuseAttributePolicy): OtlpEncodedSpan;
+/**
+ * @description Builds an OTLP/JSON export request, grouping spans under the resource and instrumentation scope they were produced under.
+ * @param items {OtlpEncodedSpan[]} - Encoded spans, in export order.
+ * @returns {OtlpTraceRequest} The request body, with one `resourceSpans` entry per distinct resource and one `scopeSpans` entry per distinct scope within it.
+ */
+export declare function toOtlpRequest(items: OtlpEncodedSpan[]): OtlpTraceRequest;
 /**
  * @description Splits encoded spans into request-sized batches, bounded by span count and serialized bytes.
- * @param spans {OtlpSpan[]} - Encoded spans, in export order.
- * @returns {OtlpSpan[][]} Batches that each fit one export request; a single oversized span still gets its own batch.
+ * @param items {OtlpEncodedSpan[]} - Encoded spans, in export order.
+ * @returns {OtlpEncodedSpan[][]} Batches that each fit one export request; a single oversized span still gets its own batch.
  */
-export declare function chunkOtlpSpans(spans: OtlpSpan[]): OtlpSpan[][];
+export declare function chunkOtlpSpans(items: OtlpEncodedSpan[]): OtlpEncodedSpan[][];

package/dist/observability/otlpEncoding.js

@@ -1,7 +1,10 @@
-import { MAX_BYTES_PER_REQUEST, MAX_SPANS_PER_REQUEST, OTLP_STATUS_CODES, } from "../constants/langfuse.js";
+import { LangfuseOtelSpanAttributes } from "@langfuse/tracing";
+import { MAX_BYTES_PER_REQUEST, MAX_SPANS_PER_REQUEST, MODEL_ATTRIBUTE_KEYS, OTLP_STATUS_CODES, UNPRICED_OBSERVATION_TYPES, USAGE_ATTRIBUTE_PREFIX, } from "../constants/langfuse.js";
 import { SpanStatus } from "../types/index.js";
 import { protectAttributes } from "./langfuseMasking.js";
 const SPAN_KIND_INTERNAL = 1;
+const FALLBACK_SERVICE_NAME = "service";
+const SCOPE_NAME = "sdk";
 function toNanos(iso) {
     return (BigInt(Date.parse(iso)) * 1000000n).toString();
 }
@@ -29,8 +32,18 @@ export function toOtlpAttributes(attributes) {
         .filter(([, value]) => value !== undefined && value !== null)
         .map(([key, value]) => ({ key, value: toOtlpValue(value) }));
 }
+// The proxy root also carries gen_ai model and usage keys for collectors;
+// Langfuse would price it a second time next to the request's generation.
+function withoutUnpricedUsage(attributes) {
+    const type = attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE];
+    if (typeof type !== "string" || !UNPRICED_OBSERVATION_TYPES.has(type)) {
+        return attributes;
+    }
+    return Object.fromEntries(Object.entries(attributes).filter(([key]) => !MODEL_ATTRIBUTE_KEYS.has(key) &&
+        !key.startsWith(USAGE_ATTRIBUTE_PREFIX)));
+}
 /**
- * @description Encodes one span as OTLP/JSON, applying the exporter's attribute policy to its attributes.
+ * @description Encodes one span as OTLP/JSON, applying the exporter's attribute policy to its attributes (its events and status message are sent as they are), leaving GenAI model and usage keys off a plain span or event observation, and keeping the span's links and nanosecond times. Every span is sent as kind INTERNAL, as Langfuse has always received it.
  * @param span {SpanData} - Span to encode.
  * @param policy {LangfuseAttributePolicy} - Environment, release, redaction and mask settings.
  * @returns {OtlpSpan} The span in the shape Langfuse's ingestion endpoint reads.
@@ -43,31 +56,75 @@ export function toOtlpSpan(span, policy) {
         ...(span.parentSpanId && { parentSpanId: span.parentSpanId }),
         name: span.name,
         kind: SPAN_KIND_INTERNAL,
-        startTimeUnixNano: toNanos(span.startTime),
-        endTimeUnixNano: toNanos(span.endTime ?? span.startTime),
-        attributes: toOtlpAttributes(protectAttributes(span.attributes, policy)),
+        startTimeUnixNano: span.startTimeUnixNano ?? toNanos(span.startTime),
+        endTimeUnixNano: span.endTimeUnixNano ?? toNanos(span.endTime ?? span.startTime),
+        attributes: toOtlpAttributes(protectAttributes(withoutUnpricedUsage(span.attributes), policy)),
         events: span.events.map((event) => ({
             name: event.name,
-            timeUnixNano: toNanos(event.timestamp),
+            timeUnixNano: event.timestampUnixNano ?? toNanos(event.timestamp),
             attributes: toOtlpAttributes(event.attributes ?? {}),
         })),
+        links: span.links.map((link) => ({
+            traceId: link.traceId,
+            spanId: link.spanId,
+            attributes: toOtlpAttributes(link.attributes ?? {}),
+        })),
         status: {
             code: OTLP_STATUS_CODES[span.status],
             ...(failed && span.statusMessage && { message: span.statusMessage }),
         },
     };
 }
+/**
+ * @description Encodes a span together with the resource it was produced under, falling back to a generic service name for a span that carries none, and the instrumentation scope `sdk` that the Langfuse request has always named.
+ * @param span {SpanData} - Span to encode.
+ * @param policy {LangfuseAttributePolicy} - Environment, release, redaction and mask settings.
+ * @returns {OtlpEncodedSpan} The encoded span with its resource and scope.
+ */
+export function toOtlpEncodedSpan(span, policy) {
+    return {
+        span: toOtlpSpan(span, policy),
+        resource: toOtlpAttributes(span.resource ?? { "service.name": FALLBACK_SERVICE_NAME }),
+        scope: { name: SCOPE_NAME },
+    };
+}
+/**
+ * @description Builds an OTLP/JSON export request, grouping spans under the resource and instrumentation scope they were produced under.
+ * @param items {OtlpEncodedSpan[]} - Encoded spans, in export order.
+ * @returns {OtlpTraceRequest} The request body, with one `resourceSpans` entry per distinct resource and one `scopeSpans` entry per distinct scope within it.
+ */
+export function toOtlpRequest(items) {
+    const resources = new Map();
+    for (const { span, resource, scope } of items) {
+        const resourceKey = JSON.stringify(resource);
+        const group = resources.get(resourceKey) ?? {
+            resource,
+            scopes: new Map(),
+        };
+        resources.set(resourceKey, group);
+        const scopeKey = `${scope.name}\u0000${scope.version ?? ""}`;
+        const scoped = group.scopes.get(scopeKey) ?? { scope, spans: [] };
+        group.scopes.set(scopeKey, scoped);
+        scoped.spans.push(span);
+    }
+    return {
+        resourceSpans: [...resources.values()].map((group) => ({
+            resource: { attributes: group.resource },
+            scopeSpans: [...group.scopes.values()],
+        })),
+    };
+}
 /**
  * @description Splits encoded spans into request-sized batches, bounded by span count and serialized bytes.
- * @param spans {OtlpSpan[]} - Encoded spans, in export order.
- * @returns {OtlpSpan[][]} Batches that each fit one export request; a single oversized span still gets its own batch.
+ * @param items {OtlpEncodedSpan[]} - Encoded spans, in export order.
+ * @returns {OtlpEncodedSpan[][]} Batches that each fit one export request; a single oversized span still gets its own batch.
  */
-export function chunkOtlpSpans(spans) {
+export function chunkOtlpSpans(items) {
     const chunks = [];
     let current = [];
     let bytes = 0;
-    for (const span of spans) {
-        const size = Buffer.byteLength(JSON.stringify(span));
+    for (const item of items) {
+        const size = Buffer.byteLength(JSON.stringify(item.span));
         if (current.length > 0 &&
             (current.length >= MAX_SPANS_PER_REQUEST ||
                 bytes + size > MAX_BYTES_PER_REQUEST)) {
@@ -75,7 +132,7 @@ export function chunkOtlpSpans(spans) {
             current = [];
             bytes = 0;
         }
-        current.push(span);
+        current.push(item);
         bytes += size;
     }
     if (current.length > 0) {

package/dist/observability/utils/spanSerializer.d.ts

@@ -11,8 +11,9 @@ export declare class SpanSerializer {
      * Create a new span with generated IDs.
      *
      * When `traceId` / `parentSpanId` are omitted, the method automatically
-     * attempts to inherit them from the active OTel context so that Pipeline B
-     * spans land inside the same Langfuse trace as Pipeline A spans (fix A5).
+     * attempts to inherit them from the active OTel context so that these
+     * in-process span records carry the traceId of the exported OTEL trace they
+     * belong to (fix A5). The records themselves are never exported.
      */
     static createSpan(type: SpanType, name: string, attributes?: Partial<SpanAttributes>, parentSpanId?: string, traceId?: string): SpanData;
     /**

package/dist/observability/utils/spanSerializer.js

@@ -13,12 +13,14 @@ export class SpanSerializer {
      * Create a new span with generated IDs.
      *
      * When `traceId` / `parentSpanId` are omitted, the method automatically
-     * attempts to inherit them from the active OTel context so that Pipeline B
-     * spans land inside the same Langfuse trace as Pipeline A spans (fix A5).
+     * attempts to inherit them from the active OTel context so that these
+     * in-process span records carry the traceId of the exported OTEL trace they
+     * belong to (fix A5). The records themselves are never exported.
      */
     static createSpan(type, name, attributes = {}, parentSpanId, traceId) {
         // A5 fix: When no explicit traceId is provided, try to inherit from the
-        // active OTel context so Pipeline B spans are linked to Pipeline A traces.
+        // active OTel context so these in-process records can be matched to the
+        // OTEL trace of the request.
         let resolvedTraceId = traceId;
         let resolvedParentSpanId = parentSpanId;
         if (!resolvedTraceId) {

package/dist/processors/base/BaseFileProcessor.d.ts

@@ -43,6 +43,7 @@
  * }
  * ```
  */
+import "../../services/server/ai/observability/instrumentation.js";
 import { FileErrorCode } from "../errors/index.js";
 import type { BatchProcessingSummary, FileInfo, FileProcessingError, ProcessorFileProcessingResult, FileProcessorConfig, ProcessorOperationResult, ProcessedFileBase, ProcessOptions } from "../../types/index.js";
 /**

package/dist/processors/base/BaseFileProcessor.js

@@ -49,6 +49,10 @@ import { SIZE_LIMITS } from "../config/index.js";
 import { isAbortError } from "../../utils/errorHandling.js";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
+// Starts tracing at the first span, as this module always did: the shared
+// tracers only start what a loaded entry registered, and this path can be
+// imported without the package entry. The client entry stays free of it.
+import "../../services/server/ai/observability/instrumentation.js";
 import { createFileError, extractHttpStatus, FileErrorCode, isRetryableError, } from "../errors/index.js";
 import { DEFAULT_RETRY_CONFIG } from "../../types/index.js";
 const gunzipAsync = promisify(gunzip);

package/dist/processors/index.d.ts

@@ -64,6 +64,7 @@
  * });
  * ```
  */
+import "../services/server/ai/observability/instrumentation.js";
 export { BaseFileProcessor, DEFAULT_IMAGE_MAX_SIZE_MB, DEFAULT_IMAGE_TIMEOUT_MS, DEFAULT_RETRY_CONFIG, DEFAULT_TEXT_MAX_SIZE_MB, DEFAULT_TEXT_TIMEOUT_MS, getDefaultImageMaxSizeMB, getDefaultImageTimeout, getDefaultTextMaxSizeMB, getDefaultTextTimeout, PROCESSOR_PRIORITIES, } from "./base/index.js";
 export { AI_VISION_EXTENSIONS, ARCHIVE_EXTENSIONS, ARCHIVE_LIMITS, ARCHIVE_MIME_TYPES, AUDIO_EXTENSIONS, AUDIO_MIME_TYPES, bytesToMB, CONFIG_EXTENSIONS, CSV_EXTENSIONS, DATA_EXTENSIONS, DATA_MIME_TYPES, DATABASE_EXTENSIONS, DESIGN_EXTENSIONS, DOCUMENT_EXTENSIONS, DOCUMENT_MIME_TYPES, detectLanguageFromFilename, EXACT_FILENAME_MAP, EXCEL_EXTENSIONS, EXECUTABLE_EXTENSIONS, FILE_EXTENSIONS, formatBytes, getLanguageIdentifier, getSizeLimitForType, getSupportedExtensions, getSupportedFilenames, HTML_EXTENSIONS, IMAGE_EXTENSIONS, IMAGE_MIME_TYPES, isSourceCodeFile, isWithinSizeLimit, JSON_EXTENSIONS, LANGUAGE_MAP, MARKDOWN_EXTENSIONS, MIME_TYPES, mbToBytes, OPENDOCUMENT_EXTENSIONS, PDF_EXTENSIONS, POWERPOINT_EXTENSIONS, PROCESSING_LIMITS, RTF_EXTENSIONS, SIZE_LIMITS, SIZE_LIMITS_BYTES, SIZE_LIMITS_MB, SOURCE_CODE_EXTENSIONS, SOURCE_CODE_MIME_TYPES, TEXT_EXTENSIONS, TEXT_MIME_TYPES, VIDEO_EXTENSIONS, VIDEO_MIME_TYPES, validateFileSize, WORD_EXTENSIONS, XML_EXTENSIONS, YAML_EXTENSIONS, YAML_LIMITS, } from "./config/index.js";
 export { combineSummaries, createCustomFileError, createFileError, createProcessingSummary, ERROR_MESSAGES, extractHttpStatus, extractSafeMetadata, FileErrorCode, formatFileError, generateErrorFingerprint, getErrorTemplate, getRetryDelay, isFileProcessingError, isRetryableError, isRetryableErrorCode, mapErrorToCode, safeStringify, serializeError, summarizeError, } from "./errors/index.js";