Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .changeset/langfuse-v5-upgrade.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
"@voltagent/langfuse-exporter": major
---

Upgrade to Langfuse JS SDK v5 via @langfuse/otel

Replaced the custom v3 OTel-based exporter with a thin wrapper around `LangfuseSpanProcessor` from `@langfuse/otel`.

**Breaking changes**

- The `LangfuseExporter` class and the `createLangfuseSpanProcessor` wrapper around it are gone. `VoltAgentLangfuseProcessor` (a `SpanProcessor` wrapping `@langfuse/otel`) is now the entry point.
- The `langfuse@^3` runtime dependency is replaced by `@langfuse/otel@^5`. `@opentelemetry/api` and `@opentelemetry/sdk-trace-base` remain peer dependencies that you still have to provide.

**Migration**

```diff
- import { createLangfuseSpanProcessor } from "@voltagent/langfuse-exporter";
+ import { VoltAgentLangfuseProcessor } from "@voltagent/langfuse-exporter";

const observability = new VoltAgentObservability({
spanProcessors: [
- createLangfuseSpanProcessor({ publicKey, secretKey, baseUrl }),
+ new VoltAgentLangfuseProcessor({ publicKey, secretKey, baseUrl }),
],
});
```

`createLangfuseSpanProcessor` is still exported as a deprecated factory that forwards to the new class, so existing code keeps working.

Also added `ai.*`/`usage.*` → `gen_ai.*` attribute normalization, `prompt.tags` → `langfuse.trace.tags` mapping, and a default `shouldExportSpan` that covers VoltAgent's `@voltagent/core` instrumentation scope.
2 changes: 1 addition & 1 deletion examples/with-langfuse/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"dependencies": {
"@voltagent/cli": "^0.1.21",
"@voltagent/core": "^2.11.1",
"@voltagent/langfuse-exporter": "^2.0.3",
"@voltagent/langfuse-exporter": "^3.0.0",
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
"@voltagent/libsql": "^2.1.2",
"@voltagent/logger": "^2.0.2",
"@voltagent/server-hono": "^2.0.14",
Expand Down
4 changes: 2 additions & 2 deletions examples/with-langfuse/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { Agent, Memory, VoltAgent, VoltAgentObservability } from "@voltagent/core";
import { createLangfuseSpanProcessor } from "@voltagent/langfuse-exporter";
import { VoltAgentLangfuseProcessor } from "@voltagent/langfuse-exporter";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
Expand Down Expand Up @@ -27,7 +27,7 @@ const agent = new Agent({
// Configure Observability with Langfuse
const observability = new VoltAgentObservability({
spanProcessors: [
createLangfuseSpanProcessor({
new VoltAgentLangfuseProcessor({
publicKey: process.env.LANGFUSE_PUBLIC_KEY,
secretKey: process.env.LANGFUSE_SECRET_KEY,
baseUrl: process.env.LANGFUSE_BASE_URL,
Expand Down
13 changes: 5 additions & 8 deletions packages/langfuse-exporter/package.json
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
{
"name": "@voltagent/langfuse-exporter",
"description": "OpenTelemetry SpanExporter for sending VoltAgent traces to Langfuse.",
"version": "2.0.3",
"description": "Langfuse integration for VoltAgent using @langfuse/otel (Langfuse JS SDK v5).",
"version": "3.0.0",
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
"dependencies": {
"@opentelemetry/core": "^2.0.0",
"@opentelemetry/sdk-trace-base": "^2.0.0",
"langfuse": "^3.38.6"
"@langfuse/otel": "^5.0.0"
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
},
"devDependencies": {
"@vitest/coverage-v8": "^3.2.4",
Expand All @@ -30,15 +28,14 @@
"main": "dist/index.js",
"module": "dist/index.mjs",
"peerDependencies": {
"@opentelemetry/api": "^1.0.0",
"@opentelemetry/core": "^2.0.0",
"@opentelemetry/api": "^1.9.0",
"@opentelemetry/sdk-trace-base": "^2.0.0",
"@voltagent/core": "^2.0.0"
},
"repository": {
"type": "git",
"url": "https://github.com/VoltAgent/voltagent.git",
"directory": "packages/src"
"directory": "packages/langfuse-exporter"
},
"scripts": {
"attw": "attw --pack",
Expand Down
256 changes: 254 additions & 2 deletions packages/langfuse-exporter/src/exporter.spec.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,255 @@
import { describe } from "vitest";
import { type Context, ROOT_CONTEXT } from "@opentelemetry/api";
import type { ReadableSpan, Span as SDKSpan } from "@opentelemetry/sdk-trace-base";
import { describe, expect, it, vi } from "vitest";
import { VoltAgentLangfuseProcessor } from "./exporter";

describe.todo("add unit tests");
const createSpan = (
instrumentationScope: string,
attributes: Record<string, unknown> = {},
): SDKSpan => {
const span = {
spanContext: () => ({
traceId: "trace-id",
spanId: "span-id",
traceFlags: 1,
isRemote: false,
traceState: undefined,
}),
resource: { attributes: {} },
instrumentationScope: { name: instrumentationScope },
attributes: { ...attributes },
events: [],
links: [],
startTime: [0, 0],
endTime: [0, 0],
droppedAttributesCount: 0,
droppedEventsCount: 0,
droppedLinksCount: 0,
duration: [0, 0],
status: { code: 0 },
name: "test-span",
kind: 0,
parentSpanId: undefined,
addEvent: vi.fn(),
end: vi.fn(),
isRecording: vi.fn().mockReturnValue(true),
recordException: vi.fn(),
setAttribute: vi.fn((key: string, value: unknown) => {
(span.attributes as Record<string, unknown>)[key] = value;
}),
setAttributes: vi.fn(),
setStatus: vi.fn(),
updateName: vi.fn(),
};

return span as unknown as SDKSpan;
};

const noopContext = ROOT_CONTEXT as Context;

describe("VoltAgentLangfuseProcessor", () => {
describe("attribute normalisation", () => {
it("maps ai.* attributes to gen_ai.* conventions", () => {
const processor = new VoltAgentLangfuseProcessor();
const span = createSpan("ai", {
"ai.model.id": "gpt-4o-mini",
"ai.response.text": "hello",
"ai.usage.promptTokens": 12,
"ai.usage.completionTokens": 34,
});

processor.onStart(span, noopContext);

expect(span.attributes["gen_ai.request.model"]).toBe("gpt-4o-mini");
expect(span.attributes["gen_ai.output.text"]).toBe("hello");
expect(span.attributes["gen_ai.usage.input_tokens"]).toBe(12);
expect(span.attributes["gen_ai.usage.output_tokens"]).toBe(34);
});

it("does not clobber an existing gen_ai.* value", () => {
const processor = new VoltAgentLangfuseProcessor();
const span = createSpan("ai", {
"ai.model.id": "from-ai-sdk",
"gen_ai.request.model": "from-upstream-instrumentor",
});

processor.onStart(span, noopContext);

expect(span.attributes["gen_ai.request.model"]).toBe("from-upstream-instrumentor");
});

it("maps ai.model.id and ai.model.name to the same key without order dependence", () => {
const processor = new VoltAgentLangfuseProcessor();
const span = createSpan("ai", {
"ai.model.name": "by-name",
"ai.model.id": "by-id",
});

processor.onStart(span, noopContext);

// Whichever source wins, the result must be one of the two inputs and
// must be stable across runs — never undefined or a mix.
expect(["by-name", "by-id"]).toContain(span.attributes["gen_ai.request.model"]);
});

it("maps VoltAgent tags to langfuse.trace.tags", () => {
const arrayProcessor = new VoltAgentLangfuseProcessor();
const arraySpan = createSpan("@voltagent/core", {
tags: ["production", "v2"],
});
arrayProcessor.onStart(arraySpan, noopContext);
expect(arraySpan.attributes["langfuse.trace.tags"]).toEqual(["production", "v2"]);

const jsonProcessor = new VoltAgentLangfuseProcessor();
const jsonSpan = createSpan("@voltagent/core", {
"prompt.tags": '["alpha","beta"]',
});
jsonProcessor.onStart(jsonSpan, noopContext);
expect(jsonSpan.attributes["langfuse.trace.tags"]).toEqual(["alpha", "beta"]);
});

it("maps enduser.id / conversation.id to the standard semconv keys", () => {
const processor = new VoltAgentLangfuseProcessor();
const span = createSpan("@voltagent/core", {
"enduser.id": "user-1",
"conversation.id": "session-1",
});

processor.onStart(span, noopContext);

expect(span.attributes["user.id"]).toBe("user-1");
expect(span.attributes["session.id"]).toBe("session-1");
});

it("normalises on end so attributes set late are still exported", () => {
const processor = new VoltAgentLangfuseProcessor();
const span = createSpan("@voltagent/core");
const readable = span as unknown as ReadableSpan;
(readable.attributes as Record<string, unknown>)["ai.model.id"] = "late-model";

// A finished span reaches `onEnd` as a `ReadableSpan`, which has no
// `setAttribute`. Drop the mock's method so this exercises the direct
// attribute-map write, which is the branch production actually takes,
// instead of the live-span setter the mock would otherwise select.
delete (readable as unknown as { setAttribute?: unknown }).setAttribute;

processor.onEnd(readable);
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved

expect(readable.attributes["gen_ai.request.model"]).toBe("late-model");
});
});

describe("delegation", () => {
it("forwards spans to the inner processor", () => {
const processor = new VoltAgentLangfuseProcessor();

const inner = (processor as unknown as { inner: { onEnd: unknown } }).inner;
const spy = vi.spyOn(inner as { onEnd: (s: ReadableSpan) => void }, "onEnd");

const span = createSpan("@voltagent/core");
processor.onEnd(span as unknown as ReadableSpan);

expect(spy).toHaveBeenCalledTimes(1);
});
});

describe("shouldExportSpan override", () => {
it("treats a caller-supplied predicate as the override", () => {
const processor = new VoltAgentLangfuseProcessor({
shouldExportSpan: () => false,
});

const inner = (
processor as unknown as {
inner: { shouldExportSpan: (p: { otelSpan: ReadableSpan }) => boolean };
}
).inner;

const span = createSpan("@voltagent/core") as unknown as ReadableSpan;

// The caller asked for "export nothing", so even a VoltAgent span is
// rejected — the predicate is not short-circuited by an `||`.
expect(inner.shouldExportSpan({ otelSpan: span })).toBe(false);
});

it("widens the default filter to include VoltAgent scopes", () => {
const processor = new VoltAgentLangfuseProcessor();

const inner = (
processor as unknown as {
inner: { shouldExportSpan: (p: { otelSpan: ReadableSpan }) => boolean };
}
).inner;

const coreSpan = createSpan("@voltagent/core") as unknown as ReadableSpan;
expect(inner.shouldExportSpan({ otelSpan: coreSpan })).toBe(true);
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
});

it("leaves the ai scope to the stock filter rather than duplicating it", () => {
const processor = new VoltAgentLangfuseProcessor();

const inner = (
processor as unknown as {
inner: { shouldExportSpan: (p: { otelSpan: ReadableSpan }) => boolean };
}
).inner;

// `KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES` from @langfuse/otel already
// contains "ai", so the widened filter must not need its own copy of it.
const aiSpan = createSpan("ai") as unknown as ReadableSpan;
expect(inner.shouldExportSpan({ otelSpan: aiSpan })).toBe(true);
});

it("rejects spans from unrelated instrumentation scopes", () => {
const processor = new VoltAgentLangfuseProcessor();

const inner = (
processor as unknown as {
inner: { shouldExportSpan: (p: { otelSpan: ReadableSpan }) => boolean };
}
).inner;

// No gen_ai.* attribute and a scope unrelated to VoltAgent: the widened
// filter must not have widened all the way to "accept everything".
const unrelated = createSpan("my-own-instrumentation", {
"custom.attribute": "value",
}) as unknown as ReadableSpan;

expect(inner.shouldExportSpan({ otelSpan: unrelated })).toBe(false);
});

it("accepts a custom VoltAgent instrumentation scope when configured", () => {
// `VoltAgentObservability` accepts an arbitrary `instrumentationScopeName`.
// The default filter cannot guess it, so it has to be declared.
const processor = new VoltAgentLangfuseProcessor({
additionalInstrumentationScopes: ["my-app"],
});

const inner = (
processor as unknown as {
inner: { shouldExportSpan: (p: { otelSpan: ReadableSpan }) => boolean };
}
).inner;

const customSpan = createSpan("my-app") as unknown as ReadableSpan;
expect(inner.shouldExportSpan({ otelSpan: customSpan })).toBe(true);

// An undeclared scope stays rejected.
const otherSpan = createSpan("some-other-app") as unknown as ReadableSpan;
expect(inner.shouldExportSpan({ otelSpan: otherSpan })).toBe(false);
});
});

describe("backward-compatible factory", () => {
it("returns a working processor instance", async () => {
const { createLangfuseSpanProcessor } = await import("./processor");
const processor = createLangfuseSpanProcessor();

expect(processor).toBeInstanceOf(VoltAgentLangfuseProcessor);
expect(typeof processor.onStart).toBe("function");
expect(typeof processor.onEnd).toBe("function");
expect(typeof processor.forceFlush).toBe("function");
expect(typeof processor.shutdown).toBe("function");
});
});
});
Loading