VoltAgent Langfuse Exporter

Core Directive: OpenTelemetry SpanExporter for sending VoltAgent traces to Langfuse. Maps OpenTelemetry attributes directly to Langfuse Traces, Generations, and Spans for LLM observability.

🚀 Quick Start

• Install: npm install @voltagent/langfuse-exporter
• Usage: Initialize the processor and attach it to your OpenTelemetry pipeline.

import { createLangfuseSpanProcessor } from "@voltagent/langfuse-exporter"
 
const processor = createLangfuseSpanProcessor({
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  baseUrl: process.env.LANGFUSE_BASE_URL,
  batch: { maxQueueSize: 2048, maxExportBatchSize: 512 },
})

🔧 Configuration

• secretKey / publicKey / baseUrl: Langfuse project credentials.
• debug: Enables verbose internal exporter logging.
• batch.maxQueueSize: Limits the internal span queue (Default: 2048).
• batch.maxExportBatchSize: Maximum spans sent per flush (Default: 512).
• batch.scheduledDelayMillis: Interval between flushes (Default: 5000).
• batch.exportTimeoutMillis: Timeout limit per batch (Default: 30000).

📦 Dependencies

• @opentelemetry/core
• @opentelemetry/sdk-trace-base
• langfuse
• @voltagent/core

💡 Best Practices

• Batch Processing: Always use createLangfuseSpanProcessor over direct LangfuseExporter instantiation. This leverages OpenTelemetry’s BatchSpanProcessor to prevent event loop blocking.
• User & Session Tracking: Emit user.id and session.id in span attributes. The exporter automatically hoists these to trace-level metadata in Langfuse.
• Generation Tagging: Ensure LLM spans include ai.model.name or ai.usage.tokens attributes. Alternatively, include llm, generate, or stream in the span name to categorize it as a Langfuse Generation.
• Tool Execution Mapping: Set the tool.name attribute on function call spans. The exporter maps this to tool: {name} in Langfuse and tracks tool.arguments and tool.result.
• Structured I/O: Pass valid JSON objects or arrays to ai.prompt.messages and ai.response.text. The exporter applies safeJsonParse automatically, rendering structured inputs in the Langfuse UI.

🚨 Gotchas / Warnings

• Missing Secret Key: Instantiating without secretKey throws a fatal synchronous error.
• Internal Metadata Dropping: Attributes prefixed with metadata.internal. are explicitly stripped by extractMetadata(). Use the metadata. prefix for custom data instead.
• Memory Persistence: The exporter hardcodes the Langfuse SDK to use persistence: "memory". Offline disk buffering is disabled, so failed network flushes may result in lost telemetry.
• Double-Stringifying: Double-stringifying inputs or outputs causes Langfuse to display them as unformatted raw strings. The exporter already parses stringified JSON internally.

🔍 Research / References

• NPM: https://www.npmjs.com/package/@voltagent/langfuse-exporter
• GitHub: https://github.com/VoltAgent/voltagent