OpenTelemetry integration for Langfuse.

This module provides comprehensive OpenTelemetry support including:

• Span Processor - Intercept OTEL spans and convert to Langfuse observations
• Attribute Mapping - Map GenAI semantic conventions to Langfuse fields
• W3C Trace Context - Distributed tracing with traceparent headers
• Setup Helpers - Easy configuration for OTEL export

Quick Start

Option 1: Native OTEL Export (Simplest)

Configure OpenTelemetry to export directly to Langfuse:

# config/runtime.exs
config :opentelemetry_exporter,
  otlp_protocol: :http_protobuf,
  otlp_endpoint: System.get_env("LANGFUSE_HOST", "https://cloud.langfuse.com") <>
                 "/api/public/otel/v1/traces",
  otlp_headers: [
    {"Authorization", "Basic " <> Base.encode64(
      System.get_env("LANGFUSE_PUBLIC_KEY") <> ":" <>
      System.get_env("LANGFUSE_SECRET_KEY")
    )}
  ]

Or programmatically:

Langfuse.OpenTelemetry.Setup.configure_exporter()

Option 2: Span Processor (More Control)

Use Langfuse's span processor for fine-grained control:

# In your application supervisor
Langfuse.OpenTelemetry.Setup.register_processor()

# Or with filtering
Langfuse.OpenTelemetry.Setup.register_processor(
  filter_fn: fn span ->
    attrs = elem(span, 7)
    Map.has_key?(attrs, "gen_ai.request.model")
  end
)

Attribute Mapping

The integration automatically maps OpenTelemetry semantic conventions to Langfuse fields. See Langfuse.OpenTelemetry.AttributeMapper for the complete mapping reference.

GenAI Conventions

Langfuse Namespace

Distributed Tracing

Propagate trace context across service boundaries using W3C Trace Context:

# Extract from incoming request
context = Langfuse.OpenTelemetry.TraceContext.extract!(conn.req_headers)
trace = Langfuse.trace(id: context.trace_id, name: "api-request")

# Inject into outgoing request
headers = Langfuse.OpenTelemetry.TraceContext.inject(trace.id, span.id)
Req.post(downstream_url, headers: headers, json: payload)

Example: Tracing LLM Calls

defmodule MyApp.LLM do
  require OpenTelemetry.Tracer, as: Tracer

  def generate(prompt, opts \\ []) do
    model = Keyword.get(opts, :model, "gpt-4")

    Tracer.with_span "llm.generate", kind: :client do
      Tracer.set_attributes([
        {"gen_ai.system", "openai"},
        {"gen_ai.request.model", model},
        {"gen_ai.prompt", prompt},
        {"langfuse.user.id", opts[:user_id]}
      ])

      {response, usage} = call_openai(prompt, model)

      Tracer.set_attributes([
        {"gen_ai.completion", response},
        {"gen_ai.usage.input_tokens", usage.input},
        {"gen_ai.usage.output_tokens", usage.output}
      ])

      response
    end
  end
end

Submodules

• Langfuse.OpenTelemetry.SpanProcessor - OTEL span processor behaviour
• Langfuse.OpenTelemetry.AttributeMapper - Attribute mapping logic
• Langfuse.OpenTelemetry.TraceContext - W3C Trace Context support
• Langfuse.OpenTelemetry.Setup - Configuration helpers