feat(langfuse-exporter): upgrade to Langfuse JS SDK v5 via @langfuse/otel
PI
2d ago+622+622+012345678901234567890123456789-508-508-012345678901234567890123456789
Summary
Upgrades @voltagent/langfuse-exporter from the custom v3 OTel-backed exporter to a thin wrapper around LangfuseSpanProcessor from @langfuse/otel (Langfuse JS SDK v5), as requested in #1381.
Changes
package.json
- Bumped to
3.0.0(breaking: dropslangfusev3 dependency) - Replaced
langfuse: ^3.38.6with@langfuse/otel: ^5.0.0 - Removed
@opentelemetry/corefrom direct dependencies (now provided transitively via@langfuse/otel) - Updated
@opentelemetry/apipeer dep to^1.9.0(required by@langfuse/otel) - Fixed
repository.directoryfrom"packages/src"to"packages/langfuse-exporter"
src/exporter.ts -- Complete rewrite
- Removed the ~450-line custom
LangfuseExporterclass that manually grouped spans by trace ID and recreated them via the v3langfuse.trace()/.span()/.generation()event API - Replaced with
VoltAgentLangfuseProcessor-- a thinSpanProcessorwrapper aroundLangfuseSpanProcessorfrom@langfuse/otel - Added
normalizeVoltAgentAttributes()that runs on every span in bothonStartandonEnd, mapping VoltAgent/Vercel-AI-SDK attributes to standardgen_ai.*semantic conventions:ai.model.name->gen_ai.request.modelai.response.text->gen_ai.output.textai.prompt.messages->gen_ai.input.messagesai.response.finishReason->gen_ai.response.finish_reasonsai.response.msToFirstChunk/ai.stream.msToFirstChunk->gen_ai.response.time_to_first_token_msusage.prompt_tokens->gen_ai.usage.input_tokensusage.completion_tokens->gen_ai.usage.output_tokensai.usage.tokens->gen_ai.usage.total_tokensenduser.id->user.idconversation.id->session.id
- Added scoped
shouldExportSpanthat always includes VoltAgent spans (instrumentationScope.name === "ai"or prefixed with"voltagent.") composed with the default Langfuse filter (or user-supplied filter), preventing unrelated HTTP/database spans from being pulled in - User/session/tags attributes are normalised on every span (not just the root trace), aligning with v5 observations-first data model
src/processor.ts -- Simplified
- The old
createLangfuseSpanProcessorfactory is replaced with a re-export ofVoltAgentLangfuseProcessor - Marked
@deprecatedwith migration guidance
src/index.ts -- Updated exports
- Primary export:
VoltAgentLangfuseProcessor - Backward-compatible alias:
LangfuseSpanProcessor(maps toVoltAgentLangfuseProcessor) - Re-exports
LangfuseSpanProcessorParams,ShouldExportSpan,MaskFunctiontypes from@langfuse/otel
Migration guide for users
- import { createLangfuseSpanProcessor } from "@voltagent/langfuse-exporter";
- const processor = createLangfuseSpanProcessor({ publicKey, secretKey });
+ import { VoltAgentLangfuseProcessor } from "@voltagent/langfuse-exporter";
+ const processor = new VoltAgentLangfuseProcessor({ publicKey, secretKey });
What is preserved
- Parent-child span relationships (handled natively by OTel)
- Generation usage/TTFT (normalised to
gen_ai.*attributes) - Error status propagation
- Batching, force-flush, and shutdown (delegated to
LangfuseSpanProcessor)
What changes
- No more manual trace/span/generation creation via v3 API
- The
LangfuseExporterclass is removed; useVoltAgentLangfuseProcessordirectly langfusev3 is no longer a dependency
Closes #1381
Summary by cubic
Upgrades @voltagent/langfuse-exporter to Langfuse JS SDK v5 via @langfuse/otel, replacing the custom v3 exporter with a thin span processor and normalizing attributes to gen_ai.* conventions. VoltAgent spans are now exported by default, as requested in #1381.
Refactors
- Replaced the custom
LangfuseExporterwithVoltAgentLangfuseProcessor, a thin wrapper around@langfuse/otel'sLangfuseSpanProcessor; batching, flush, and shutdown now come from upstream. - Normalizes
ai.*/usage.*togen_ai.*without overriding existinggen_ai.*values, and mapsenduser.idtouser.id,conversation.idtosession.id, andprompt.tags/tagstolangfuse.trace.tags. - The default
shouldExportSpannow includes@voltagent/coreand other@voltagent/*/voltagent.*scopes; a newadditionalInstrumentationScopesoption lets callers declare custom scopes, and a caller-suppliedshouldExportSpanreplaces the filter entirely. - Added unit tests for attribute normalization, scope filtering, and the
shouldExportSpanoverride.
Migration
- Replace
createLangfuseSpanProcessor({...})withnew VoltAgentLangfuseProcessor({...}); the old factory is still exported as deprecated and forwards to the new class. - Upgrade to
@voltagent/langfuse-exporter@3.xand@opentelemetry/api@^1.9.0, and remove directlangfusev3 usage; the package now depends on@langfuse/otel@^5.
Summary by CodeRabbit
-
New Features
- Upgraded the Langfuse integration to SDK v5 and added an OpenTelemetry-based processor for VoltAgent and Vercel AI telemetry.
- Normalized AI attributes, tags, and session details for Langfuse, with default span filtering and support for custom scopes or filtering.
- The existing processor factory remains available as a deprecated compatibility option; the new processor is the recommended entry point.
-
Documentation
- Updated setup guidance and package metadata for the new integration.
-
Tests
- Added coverage for attribute mapping, filtering, span forwarding, and compatibility.