Skip to content

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

fix(otel): decode per-key metadata on third-party spans from Langfuse SDK v5/v6 exports (#18911)

Hassieb Pakzad0e793a19cbea
diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts
index 575bd0c294..5f2e7f1d15 100644
--- a/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts
+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts
@@ -465,6 +465,7 @@ describe("per-key metadata values from structured-metadata SDK majors", () => {
// "child" sends the attributes on a child span of an attribute-less root.
span?: "root" | "child";
headerSdkName?: string;
+ headerSdkVersion?: string;
scopeName?: string;
scopeVersion?: string;
telemetrySdkLanguage?: string;
@@ -495,7 +496,7 @@ describe("per-key metadata values from structured-metadata SDK majors", () => {
projectId: PROJECT_ID,
publicKey: "pk-test",
sdkName: params.headerSdkName ?? "python",
- sdkVersion: scopeVersion,
+ sdkVersion: params.headerSdkVersion ?? scopeVersion,
});
if (path === "v4") {
return processor.processToEvent(batch).at(-1)?.metadata as Record<
@@ -618,10 +619,19 @@ describe("per-key metadata values from structured-metadata SDK majors", () => {
scopeVersion: "5.11.1",
},
{
- case: "non-Langfuse scope",
+ case: "non-Langfuse scope under a current Python major",
headerSdkName: "python",
- scopeVersion: "5.0.0",
- scopeName: "openinference",
+ headerSdkVersion: "4.15.6",
+ scopeName: "openinference.instrumentation.openai",
+ scopeVersion: "0.1.20",
+ },
+ {
+ case: "non-Langfuse scope without a Langfuse SDK header",
+ headerSdkName: "unknown",
+ headerSdkVersion: "unknown",
+ scopeName: "openinference.instrumentation.openai",
+ scopeVersion: "6.0.0",
+ telemetrySdkLanguage: "python",
},
])("keeps per-key values as sent for the $case", async (params) => {
const result = await processMetadata(
@@ -637,6 +647,50 @@ describe("per-key metadata values from structured-metadata SDK majors", () => {
});
});
+ // The SDK span processor writes propagated metadata onto every span in its
+ // context, so third-party spans carry the same encoded values.
+ it.each([
+ {
+ case: "OpenInference span exported by Python v5",
+ headerSdkName: "python",
+ headerSdkVersion: "5.0.1",
+ scopeName: "openinference.instrumentation.openai",
+ scopeVersion: "0.1.20",
+ },
+ {
+ case: "Vercel AI SDK span exported by JS v6",
+ headerSdkName: "javascript",
+ headerSdkVersion: "6.0.0",
+ scopeName: "ai",
+ scopeVersion: "4.3.16",
+ },
+ ])("decodes per-key values on an $case", async (params) => {
+ const result = await processMetadata(
+ "v4",
+ [
+ ...perKeyAttributes("observation"),
+ {
+ key: "ai.telemetry.metadata.tenant",
+ value: { stringValue: "acme" },
+ },
+ {
+ key: "ai.telemetry.metadata.count",
+ value: { stringValue: "42" },
+ },
+ ],
+ params,
+ );
+
+ expect(result).toMatchObject({
+ environment: "prod",
+ retries: 3,
+ database: metadata.database,
+ // The AI SDK writes its own metadata raw.
+ tenant: "acme",
+ count: "42",
+ });
+ });
+
describe("user, session and tags sent as per-key metadata", () => {
const compatAttributes = (
domain: "observation" | "trace",
diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.ts
index 09c351cb06..50f1de4368 100644
--- a/packages/shared/src/server/otel/OtelIngestionProcessor.ts
+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.ts
@@ -2748,7 +2748,7 @@ export class OtelIngestionProcessor {
"ai.telemetry.metadata.tags",
"ai.telemetry.metadata.langfusePrompt",
]),
- decodeValues,
+ decodedPrefix: decodeValues ? metadataKeyPrefix : undefined,
});
return {
@@ -3666,14 +3666,14 @@ export class OtelIngestionProcessor {
attributes: Record<string, unknown>;
prefixes: string[];
excludedKeys?: Set<string>;
- // Set for structured-metadata SDKs, which JSON-encode every value.
- decodeValues?: boolean;
+ /** decodedPrefix holds JSON-encoded values for structured-metadata SDKs */
+ decodedPrefix?: string;
}): Record<string, unknown> {
const {
attributes,
prefixes,
excludedKeys = new Set<string>(),
- decodeValues,
+ decodedPrefix,
} = params;
const metadata: Record<string, unknown> = {};
for (const [key, value] of Object.entries(attributes)) {
@@ -3687,7 +3687,7 @@ export class OtelIngestionProcessor {
continue;
}
- if (!decodeValues || typeof value !== "string") {
+ if (prefix !== decodedPrefix || typeof value !== "string") {
metadata[metadataKey] = value;
continue;
}
@@ -3716,16 +3716,11 @@ export class OtelIngestionProcessor {
return metadata;
}
- // Langfuse SDK spans from a major that opts into decoded per-key metadata.
- // The language comes from the request header, falling back to the OTel
- // resource for exports relayed without Langfuse headers.
+ /** shouldDecodeMetadataValues is true for spans of any scope exported by a structured-metadata Langfuse SDK major, versioned by the scope on langfuse-sdk spans and by the request header otherwise */
private shouldDecodeMetadataValues(
scopeSpan: any,
resourceAttributes: Record<string, unknown>,
): boolean {
- if (!scopeSpan?.scope?.name?.startsWith("langfuse-sdk")) {
- return false;
- }
const sdkName =
normalizeIngestionSdkName(this.sdkName) ??
OTEL_SDK_LANGUAGE_TO_SDK_NAME.get(
@@ -3734,7 +3729,9 @@ export class OtelIngestionProcessor {
null;
return isStructuredMetadataSdkVersion({
sdkName,
- sdkVersion: scopeSpan.scope.version,
+ sdkVersion: scopeSpan?.scope?.name?.startsWith("langfuse-sdk")
+ ? scopeSpan.scope.version
+ : this.sdkVersion,
});
}