Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(otel): denormalize AI-feature child trace names for cost filters (#16793)

Lysander Kiesele94743fee228
diff --git a/packages/shared/src/server/llm/ai-sdk/telemetry.ts b/packages/shared/src/server/llm/ai-sdk/telemetry.ts
index 995feae50e..ba3b106e9d 100644
--- a/packages/shared/src/server/llm/ai-sdk/telemetry.ts
+++ b/packages/shared/src/server/llm/ai-sdk/telemetry.ts
@@ -23,8 +23,10 @@ import type { TelemetryOptions } from "ai";
import { stringifyValue } from "../../../utils/stringChecks";
import { traceException } from "../../instrumentation";
import { logger } from "../../logger";
-import { LangfuseOtelSpanAttributes } from "../../otel/attributes";
-import { AI_FEATURE_OTEL_SDK_NAME } from "../../otel/internalAiFeatureOtelWriter";
+import {
+ AI_FEATURE_OTEL_SDK_NAME,
+ LangfuseOtelSpanAttributes,
+} from "../../otel/attributes";
import { publishInternalOtelSpans } from "../../otel/internalTraceOtelWriter";
import type { InternalTraceExperimentContext } from "../internalTraceEvents";
import type { TraceSinkParams } from "../types";
diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.ts
index 6067d2af6f..58d19b164a 100644
--- a/packages/shared/src/server/otel/OtelIngestionProcessor.ts
+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.ts
@@ -27,7 +27,10 @@ import {
LangfuseInternalTraceEnvironment,
} from "../";
-import { LangfuseOtelSpanAttributes } from "./attributes";
+import {
+ AI_FEATURE_OTEL_SDK_NAME,
+ LangfuseOtelSpanAttributes,
+} from "./attributes";
import { ObservationTypeMapperRegistry } from "./ObservationTypeMapper";
import { env } from "../../env";
import { OtelIngestionQueue } from "../redis/otelIngestionQueue";
@@ -383,7 +386,7 @@ export class OtelIngestionProcessor {
return [];
}
- return resourceSpans
+ const events = resourceSpans
.filter((r) => Boolean(r))
.flatMap((resourceSpan) => {
const resourceAttributes =
@@ -672,6 +675,12 @@ export class OtelIngestionProcessor {
return events;
});
+
+ if (this.sdkName === AI_FEATURE_OTEL_SDK_NAME) {
+ this.denormalizeAiFeatureChildTraceNames(events);
+ }
+
+ return events;
} catch (error) {
logger.error("Error processing OTEL spans to events:", {
error,
@@ -683,6 +692,45 @@ export class OtelIngestionProcessor {
});
}
+ /**
+ * Copy the wrapping root's observation.traceName onto sibling events in the
+ * same batch that omitted langfuse.trace.name. That OTEL attribute is a
+ * trace-update signal; filling the events-table field keeps cost-by-trace-name
+ * filters working without rewriting the trace.
+ */
+ private denormalizeAiFeatureChildTraceNames(
+ events: Array<{
+ traceId?: string;
+ traceName?: string | null;
+ parentSpanId?: string | null;
+ isAppRoot?: boolean;
+ }>,
+ ): void {
+ const traceNameByTraceId = new Map<string, string>();
+
+ for (const event of events) {
+ if (!event.traceId || !event.traceName) {
+ continue;
+ }
+
+ const isRoot = !event.parentSpanId || event.isAppRoot === true;
+ if (isRoot) {
+ traceNameByTraceId.set(event.traceId, event.traceName);
+ }
+ }
+
+ for (const event of events) {
+ if (event.traceName || !event.traceId) {
+ continue;
+ }
+
+ const traceName = traceNameByTraceId.get(event.traceId);
+ if (traceName !== undefined) {
+ event.traceName = traceName;
+ }
+ }
+ }
+
/**
* Process resource spans and convert them to Langfuse ingestion events.
* Handles trace deduplication automatically using internal state.
diff --git a/packages/shared/src/server/otel/attributes.ts b/packages/shared/src/server/otel/attributes.ts
index 43ee33163a..7382b6b50f 100644
--- a/packages/shared/src/server/otel/attributes.ts
+++ b/packages/shared/src/server/otel/attributes.ts
@@ -52,3 +52,6 @@ export enum LangfuseOtelSpanAttributes {
EXPERIMENT_ITEM_ROOT_OBSERVATION_ID = "langfuse.experiment.item.root_observation_id",
EXPERIMENT_ITEM_EXPECTED_OUTPUT = "langfuse.experiment.item.expected_output",
}
+
+/** SDK name for internally published AI-feature product traces. */
+export const AI_FEATURE_OTEL_SDK_NAME = "langfuse-internal-ai-features";
diff --git a/packages/shared/src/server/otel/internalAiFeatureOtelWriter.test.ts b/packages/shared/src/server/otel/internalAiFeatureOtelWriter.test.ts
index d4cb4dbb90..176de5ef8a 100644
--- a/packages/shared/src/server/otel/internalAiFeatureOtelWriter.test.ts
+++ b/packages/shared/src/server/otel/internalAiFeatureOtelWriter.test.ts
@@ -3,8 +3,9 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
import { buildInternalTraceEventInputs } from "../llm/internalTraceEvents";
import {
AI_FEATURE_OTEL_SDK_NAME,
- publishAiFeatureTraceViaOtelIngestion,
-} from "./internalAiFeatureOtelWriter";
+ LangfuseOtelSpanAttributes,
+} from "./attributes";
+import { publishAiFeatureTraceViaOtelIngestion } from "./internalAiFeatureOtelWriter";
const publishToOtelIngestionQueue = vi.fn().mockResolvedValue(undefined);
const processorConstructor = vi.fn();
@@ -91,9 +92,23 @@ const processedEvents = [
},
];
-const processPublishedSpans = async () => {
+const getPublishedResourceSpans = () => {
expect(publishToOtelIngestionQueue).toHaveBeenCalledTimes(1);
- const resourceSpans = publishToOtelIngestionQueue.mock.calls[0][0];
+ return publishToOtelIngestionQueue.mock.calls[0][0];
+};
+
+const spanAttributeMap = (span: {
+ attributes?: Array<{ key: string; value: { stringValue?: string } }>;
+}) =>
+ Object.fromEntries(
+ (span.attributes ?? []).map((attribute) => [
+ attribute.key,
+ attribute.value.stringValue,
+ ]),
+ );
+
+const processPublishedSpans = async (sdkName = AI_FEATURE_OTEL_SDK_NAME) => {
+ const resourceSpans = getPublishedResourceSpans();
const { OtelIngestionProcessor } = await vi.importActual<
typeof import("./OtelIngestionProcessor")
@@ -101,29 +116,33 @@ const processPublishedSpans = async () => {
return new OtelIngestionProcessor({
projectId: "project-1",
publicKey: "",
- sdkName: AI_FEATURE_OTEL_SDK_NAME,
+ sdkName,
sdkVersion: "unknown",
ingestionVersion: "4",
isLangfuseInternal: false,
}).processToEvent(resourceSpans);
};
+const publishFixture = async () => {
+ const { eventInputs } = buildInternalTraceEventInputs({
+ processedEvents,
+ traceId: TRACE_ID,
+ projectId: "project-1",
+ });
+
+ await publishAiFeatureTraceViaOtelIngestion({
+ projectId: "project-1",
+ eventInputs,
+ });
+};
+
beforeEach(() => {
vi.clearAllMocks();
});
describe("publishAiFeatureTraceViaOtelIngestion", () => {
it("preserves agent and tool observation types from SDK event types", async () => {
- const { eventInputs } = buildInternalTraceEventInputs({
- processedEvents,
- traceId: TRACE_ID,
- projectId: "project-1",
- });
-
- await publishAiFeatureTraceViaOtelIngestion({
- projectId: "project-1",
- eventInputs,
- });
+ await publishFixture();
expect(processorConstructor).toHaveBeenCalledWith(
expect.objectContaining({
@@ -147,6 +166,7 @@ describe("publishAiFeatureTraceViaOtelIngestion", () => {
traceId: TRACE_ID,
parentSpanId: null,
name: "agent-turn",
+ traceName: "agent-turn",
type: "SPAN",
environment: "production",
userId: "user-1",
@@ -159,6 +179,7 @@ describe("publishAiFeatureTraceViaOtelIngestion", () => {
traceId: TRACE_ID,
parentSpanId: TRACE_ID,
name: "agent-turn",
+ traceName: "agent-turn",
type: "AGENT",
environment: "production",
});
@@ -166,6 +187,7 @@ describe("publishAiFeatureTraceViaOtelIngestion", () => {
traceId: TRACE_ID,
parentSpanId: RUN_ID,
name: "invoke-model",
+ traceName: "agent-turn",
type: "GENERATION",
environment: "production",
modelName: "claude-opus",
@@ -176,6 +198,7 @@ describe("publishAiFeatureTraceViaOtelIngestion", () => {
traceId: TRACE_ID,
parentSpanId: RUN_ID,
name: "langfuse_listPrompts",
+ traceName: "agent-turn",
type: "TOOL",
environment: "production",
userId: "user-1",
@@ -188,6 +211,74 @@ describe("publishAiFeatureTraceViaOtelIngestion", () => {
});
});
+ it("keeps langfuse.trace.name on the wrapping root only", async () => {
+ await publishFixture();
+
+ const spans = getPublishedResourceSpans().flatMap((resourceSpan: any) =>
+ resourceSpan.scopeSpans.flatMap((scopeSpan: any) => scopeSpan.spans),
+ );
+ const root = spans.find((span: any) => !span.parentSpanId);
+ const children = spans.filter((span: any) => span.parentSpanId);
+
+ expect(spanAttributeMap(root)[LangfuseOtelSpanAttributes.TRACE_NAME]).toBe(
+ "agent-turn",
+ );
+ expect(children).toHaveLength(3);
+ for (const child of children) {
+ expect(
+ spanAttributeMap(child)[LangfuseOtelSpanAttributes.TRACE_NAME],
+ ).toBe(undefined);
+ }
+ });
+
+ it("does not copy the batch-root traceName onto children for other SDK names", async () => {
+ await publishFixture();
+
+ const events = await processPublishedSpans("langfuse-internal-otel-writer");
+ const wrappingRoot = events.find((event) => event.spanId === TRACE_ID);
+ const generation = events.find(
+ (event) => event.spanId === `${RUN_ID}-llm-0`,
+ );
+
+ expect(wrappingRoot?.traceName).toBe("agent-turn");
+ expect(generation?.name).toBe("invoke-model");
+ expect(generation?.traceName).toBeNull();
+ });
+
+ it("does not emit named trace-create rewrites from child spans", async () => {
+ await publishFixture();
+
+ const resourceSpans = getPublishedResourceSpans();
+ const { OtelIngestionProcessor } = await vi.importActual<
+ typeof import("./OtelIngestionProcessor")
+ >("./OtelIngestionProcessor");
+ const processor = new OtelIngestionProcessor({
+ projectId: "project-1",
+ publicKey: "",
+ sdkName: AI_FEATURE_OTEL_SDK_NAME,
+ sdkVersion: "unknown",
+ ingestionVersion: "4",
+ isLangfuseInternal: false,
+ });
+ vi.spyOn(
+ processor as unknown as { getSeenTracesSet: () => Promise<Set<string>> },
+ "getSeenTracesSet",
+ ).mockResolvedValue(new Set());
+
+ const events = await processor.processToIngestionEvents(resourceSpans);
+ const namedTraceCreates = events.filter(
+ (event) =>
+ event.type === "trace-create" &&
+ Boolean((event.body as { name?: string }).name),
+ );
+
+ expect(namedTraceCreates).toHaveLength(1);
+ expect(namedTraceCreates[0]?.body).toMatchObject({
+ id: TRACE_ID,
+ name: "agent-turn",
+ });
+ });
+
it("skips an empty input", async () => {
await publishAiFeatureTraceViaOtelIngestion({
projectId: "project-1",
diff --git a/packages/shared/src/server/otel/internalAiFeatureOtelWriter.ts b/packages/shared/src/server/otel/internalAiFeatureOtelWriter.ts
index 6e6ca81c80..6ac099813c 100644
--- a/packages/shared/src/server/otel/internalAiFeatureOtelWriter.ts
+++ b/packages/shared/src/server/otel/internalAiFeatureOtelWriter.ts
@@ -1,11 +1,11 @@
import type { InternalTraceEventInput } from "../llm/internalTraceEvents";
import { type ResourceSpan } from "./OtelIngestionProcessor";
+import { AI_FEATURE_OTEL_SDK_NAME } from "./attributes";
import {
internalTraceEventToOtelAttributes,
publishOtelResourceSpans,
} from "./internalTraceOtelWriter";
-export const AI_FEATURE_OTEL_SDK_NAME = "langfuse-internal-ai-features";
const AI_FEATURE_OTEL_SCOPE = "langfuse-ai-features-writer";
const AI_FEATURE_SERVICE_NAME = "langfuse-ai-features";