feat(langfuse-exporter): upgrade to Langfuse JS SDK v5 via @langfuse/otel

PI
2d ago
+622-508

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: drops langfuse v3 dependency)
  • Replaced langfuse: ^3.38.6 with @langfuse/otel: ^5.0.0
  • Removed @opentelemetry/core from direct dependencies (now provided transitively via @langfuse/otel)
  • Updated @opentelemetry/api peer dep to ^1.9.0 (required by @langfuse/otel)
  • Fixed repository.directory from "packages/src" to "packages/langfuse-exporter"

src/exporter.ts -- Complete rewrite

  • Removed the ~450-line custom LangfuseExporter class that manually grouped spans by trace ID and recreated them via the v3 langfuse.trace() / .span() / .generation() event API
  • Replaced with VoltAgentLangfuseProcessor -- a thin SpanProcessor wrapper around LangfuseSpanProcessor from @langfuse/otel
  • Added normalizeVoltAgentAttributes() that runs on every span in both onStart and onEnd, mapping VoltAgent/Vercel-AI-SDK attributes to standard gen_ai.* semantic conventions:
    • ai.model.name -> gen_ai.request.model
    • ai.response.text -> gen_ai.output.text
    • ai.prompt.messages -> gen_ai.input.messages
    • ai.response.finishReason -> gen_ai.response.finish_reasons
    • ai.response.msToFirstChunk / ai.stream.msToFirstChunk -> gen_ai.response.time_to_first_token_ms
    • usage.prompt_tokens -> gen_ai.usage.input_tokens
    • usage.completion_tokens -> gen_ai.usage.output_tokens
    • ai.usage.tokens -> gen_ai.usage.total_tokens
    • enduser.id -> user.id
    • conversation.id -> session.id
  • Added scoped shouldExportSpan that 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 createLangfuseSpanProcessor factory is replaced with a re-export of VoltAgentLangfuseProcessor
  • Marked @deprecated with migration guidance

src/index.ts -- Updated exports

  • Primary export: VoltAgentLangfuseProcessor
  • Backward-compatible alias: LangfuseSpanProcessor (maps to VoltAgentLangfuseProcessor)
  • Re-exports LangfuseSpanProcessorParams, ShouldExportSpan, MaskFunction types 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 LangfuseExporter class is removed; use VoltAgentLangfuseProcessor directly
  • langfuse v3 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 LangfuseExporter with VoltAgentLangfuseProcessor, a thin wrapper around @langfuse/otel's LangfuseSpanProcessor; batching, flush, and shutdown now come from upstream.
  • Normalizes ai.*/usage.* to gen_ai.* without overriding existing gen_ai.* values, and maps enduser.id to user.id, conversation.id to session.id, and prompt.tags/tags to langfuse.trace.tags.
  • The default shouldExportSpan now includes @voltagent/core and other @voltagent/*/voltagent.* scopes; a new additionalInstrumentationScopes option lets callers declare custom scopes, and a caller-supplied shouldExportSpan replaces the filter entirely.
  • Added unit tests for attribute normalization, scope filtering, and the shouldExportSpan override.

Migration

  • Replace createLangfuseSpanProcessor({...}) with new VoltAgentLangfuseProcessor({...}); the old factory is still exported as deprecated and forwards to the new class.
  • Upgrade to @voltagent/langfuse-exporter@3.x and @opentelemetry/api@^1.9.0, and remove direct langfuse v3 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.