Skip to content

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

fix(otel): preserve explicit user IDs when resolving identity (#19011)

Valery Meleshkin31b857535b2f
diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.ts
index aa8af23410..59d7a562c8 100644
--- a/packages/shared/src/server/otel/OtelIngestionProcessor.ts
+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.ts
@@ -685,6 +685,7 @@ export class OtelIngestionProcessor {
userId: this.extractUserId(
spanAttributes,
decodeMetadataValues,
+ resourceAttributes,
),
sessionId: this.extractSessionId(
spanAttributes,
@@ -1172,7 +1173,11 @@ export class OtelIngestionProcessor {
(attributes?.[LangfuseOtelSpanAttributes.RELEASE] as string) ??
resourceAttributes?.[LangfuseOtelSpanAttributes.RELEASE] ??
null,
- userId: this.extractUserId(attributes, decodeMetadataValues),
+ userId: this.extractUserId(
+ attributes,
+ decodeMetadataValues,
+ resourceAttributes,
+ ),
sessionId: this.extractSessionId(
attributes,
decodeMetadataValues,
@@ -1216,7 +1221,8 @@ export class OtelIngestionProcessor {
(attributes?.[LangfuseOtelSpanAttributes.RELEASE] as string) ??
resourceAttributes?.[LangfuseOtelSpanAttributes.RELEASE] ??
null,
- userId: this.extractUserId(attributes, decodeMetadataValues),
+ // Child updates must not replace an explicit trace user with a fallback.
+ userId: this.extractExplicitUserId(attributes, decodeMetadataValues),
/** CMA session inference belongs to root traces and individual observations. */
sessionId: this.extractSessionId(
attributes,
@@ -2760,6 +2766,32 @@ export class OtelIngestionProcessor {
private extractUserId(
attributes: Record<string, unknown>,
decodeMetadataValues: boolean,
+ resourceAttributes: Record<string, unknown>,
+ ): string | undefined {
+ // Explicit identifiers in either scope take precedence over usernames.
+ return (
+ this.extractExplicitUserId(attributes, decodeMetadataValues) ??
+ this.extractStringAttribute(
+ resourceAttributes,
+ ["langfuse.user.id", "user.id"],
+ decodeMetadataValues,
+ ) ??
+ this.extractStringAttribute(
+ attributes,
+ ["user.name"],
+ decodeMetadataValues,
+ ) ??
+ this.extractStringAttribute(
+ resourceAttributes,
+ ["user.name"],
+ decodeMetadataValues,
+ )
+ );
+ }
+
+ private extractExplicitUserId(
+ attributes: Record<string, unknown>,
+ decodeMetadataValues: boolean,
): string | undefined {
return this.extractStringAttribute(
attributes,
diff --git a/web/src/__tests__/server/api/otel/otelMapping.servertest.ts b/web/src/__tests__/server/api/otel/otelMapping.servertest.ts
index fd6ec8b214..b442770bb8 100644
--- a/web/src/__tests__/server/api/otel/otelMapping.servertest.ts
+++ b/web/src/__tests__/server/api/otel/otelMapping.servertest.ts
@@ -86,6 +86,124 @@ async function convertOtelSpanToIngestionEvent(
])) as unknown as TestIngestionEvent[];
}
+describe("OTel user identity", () => {
+ const attributes = (values: Record<string, string>) =>
+ Object.entries(values).map(([key, stringValue]) => ({
+ key,
+ value: { stringValue },
+ }));
+
+ const batch = (
+ resource: Record<string, string>,
+ spans: Record<string, string>[],
+ ): ResourceSpan => ({
+ resource: { attributes: attributes(resource) },
+ scopeSpans: [
+ {
+ scope: { name: "test-scope", version: "1.0.0" },
+ spans: spans.map((span, index) => ({
+ traceId: Buffer.from("0123456789abcdef0123456789abcdef", "hex"),
+ spanId: Buffer.from(
+ index === 0 ? "0123456789abcdef" : "1111111111111111",
+ "hex",
+ ),
+ ...(index === 0
+ ? {}
+ : { parentSpanId: Buffer.from("0123456789abcdef", "hex") }),
+ name: index === 0 ? "invoke_agent" : "chat model",
+ kind: 1,
+ startTimeUnixNano: "1752384000000000000",
+ endTimeUnixNano: "1752384001000000000",
+ attributes: attributes(span),
+ status: {},
+ })),
+ },
+ ],
+ });
+
+ const cases: {
+ name: string;
+ span: Record<string, string>;
+ resource: Record<string, string>;
+ expected: string | undefined;
+ }[] = [
+ {
+ name: "span IDs take precedence over resource IDs and usernames",
+ span: { "user.id": "span-id", "user.name": "span-name" },
+ resource: { "langfuse.user.id": "resource-id" },
+ expected: "span-id",
+ },
+ {
+ name: "existing metadata IDs take precedence over resource IDs",
+ span: { "ai.telemetry.metadata.userId": "compat-id" },
+ resource: { "user.id": "resource-id" },
+ expected: "compat-id",
+ },
+ {
+ name: "resource IDs take precedence over span usernames",
+ span: { "user.name": "github-login" },
+ resource: { "user.id": "employee-id" },
+ expected: "employee-id",
+ },
+ {
+ name: "resource Langfuse IDs take precedence over resource OTel IDs",
+ span: { "user.name": "github-login" },
+ resource: { "langfuse.user.id": "employee-id", "user.id": "otel-id" },
+ expected: "employee-id",
+ },
+ {
+ name: "span usernames take precedence over resource usernames",
+ span: { "user.name": "github-login" },
+ resource: { "user.name": "resource-name" },
+ expected: "github-login",
+ },
+ {
+ name: "resource usernames are a final fallback",
+ span: { "user.name": "" },
+ resource: { "user.name": "resource-name" },
+ expected: "resource-name",
+ },
+ {
+ name: "OS accounts are not application users",
+ span: {},
+ resource: { "process.user.name": "root" },
+ expected: undefined,
+ },
+ ];
+
+ it.each(cases)("$name", async ({ span, resource, expected }) => {
+ const resourceSpan = batch(resource, [span]);
+ const observations = createTestOtelProcessor().processToEvent([
+ resourceSpan,
+ ]);
+ expect(observations).toHaveLength(1);
+ expect(observations[0].userId).toBe(expected);
+
+ const events = await convertOtelSpanToIngestionEvent(
+ resourceSpan,
+ new Set(),
+ );
+ expect(
+ events.find((event) => event.type === "trace-create")?.body.userId,
+ ).toBe(expected);
+ });
+
+ it("preserves explicit users on legacy child trace updates", async () => {
+ const events = await convertOtelSpanToIngestionEvent(
+ batch({ "user.id": "resource-default", "process.user.name": "node" }, [
+ { "user.id": "customer-id" },
+ { "user.name": "child-name", "langfuse.trace.name": "updated" },
+ ]),
+ new Set(),
+ );
+ expect(
+ events
+ .filter((event) => event.type === "trace-create")
+ .map((event) => event.body.userId),
+ ).toEqual(["customer-id", undefined]);
+ });
+});
+
describe("OTel Resource Span Mapping", () => {
describe("Langfuse OTEL SDK spans", () => {
const publicKey = "pk-lf-1234567890";