OpenTelemetry (OTEL) for LLM Observability - Langfuse

OpenTelemetry (OTEL) for LLM Observability

OpenTelemetry (OTEL) is a CNCF project that provides a set of specifications, APIs, and libraries that define a standard way to collect distributed traces and metrics from your application.

Use this page if your application, framework, or collector already emits OpenTelemetry (OTEL) traces and you want to send them to Langfuse.

Using Python or JavaScript/TypeScript? Use the Langfuse SDK instead of building directly on the OTEL API. The SDK handles Langfuse attributes, propagation, media, filtering, and export for you. For other languages, use the native OpenTelemetry API for your language and export spans to Langfuse.

OpenTelemetry endpoint

Langfuse can receive traces on the /api/public/otel (OTLP) endpoint.

If you use a Collector that uses the OpenTelemetry SDK to export traces, you can use the following configuration:

OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel" # 🇪🇺 EU data region
# Other Langfuse data regions include 🇺🇸 US: https://us.cloud.langfuse.com/api/public/otel, 🇯🇵 Japan: https://jp.cloud.langfuse.com/api/public/otel and ⚕️ HIPAA: https://hipaa.cloud.langfuse.com/api/public/otel
# OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3000/api/public/otel" # 🏠 Local deployment (>= v3.22.0)

OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING},x-langfuse-ingestion-version=4"

Langfuse uses Basic Auth to authenticate requests.

Important: Propagating Trace Attributes to All Spans

When using OpenTelemetry (OTEL) instrumentation to send traces to Langfuse, certain trace-level attributes should be propagated to all spans within a trace to enable accurate aggregations and filtering in Langfuse. These attributes include:

userId (via langfuse.user.id or user.id)
sessionId (via langfuse.session.id or session.id)
metadata (via langfuse.trace.metadata.* for top-level metadata keys)
version (via langfuse.version)
release (via langfuse.release)
tags (via langfuse.trace.tags)
trace_name (via langfuse.trace.name)

Langfuse filters and aggregations increasingly operate across individual observations rather than only at the trace level. If you want to reliably filter or aggregate by these attributes, they need to be present on each span in the trace, not only on the root span.

Recommended: Use OpenTelemetry Baggage for Propagation

The recommended approach for propagating these attributes across all spans is to use OpenTelemetry Baggage with a BaggageSpanProcessor. Baggage is a built-in OpenTelemetry mechanism for context propagation that automatically copies specified key-value pairs to all spans within a trace context.

To implement this pattern:

Set the desired attributes as baggage entries at the beginning of your trace.
Set the attributes on the currently active span.
Configure a BaggageSpanProcessor in your OpenTelemetry setup to automatically copy baggage entries to span attributes.
The processor will ensure all downstream spans in the trace context receive these attributes.

Ingestion Options

OpenTelemetry native Langfuse SDK v4

The quickest path to start tracing with Langfuse is the new OTEL-native Langfuse SDK v4. The SDK is a thin layer on top of the official OpenTelemetry client that automatically converts emitted spans into Langfuse observations and adds first-class helpers for LLM-specific features such as token usage, cost tracking, prompt linking, and scoring.

Get started by following the dedicated guide for the Python implementation here: /docs/observability/sdk/overview.

Filtering Spans sent to Langfuse

In case you want to selectively send OTel Spans to Langfuse, you can use the OTel Collector filterprocessor. It enables you to filter spans based on attributes, span names, and more.

Attribute Mapping

Langfuse aims to be compliant with the OpenTelemetry GenAI semantic conventions and support major LLM instrumentation frameworks.

Next steps

Once spans are arriving in Langfuse, Tracing in the Langfuse Academy covers how traces are structured and which attributes make them useful downstream, and Monitoring covers how to read them once they are there.