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.

Langfuse can operate as an OpenTelemetry Backend to receive traces on the /api/public/otel (OTLP) endpoint. In addition to the Langfuse SDKs and native integrations, this OpenTelemetry endpoint is designed to increase compatibility with frameworks, libraries, and languages beyond the SDKs and native integrations. Popular OpenTelemetry libraries include OpenLLMetry and OpenLIT which extend Language support of Langfuse tracing to Java and Go and cover frameworks such as AutoGen, Semantic Kernel, and more.

As the Semantic Conventions for GenAI attributes on traces are still evolving, Langfuse maps the received OTel traces to the Langfuse data model and supports additional attributes that are popular in the OTel GenAI ecosystem (attribute mapping). Please contribute to the discussion on GitHub if an integration does not work as expected or does not parse the correct attributes.

Using other OTEL-based tools? If you're using Langfuse alongside other OpenTelemetry-based tools, you may run into conflicts. See Using Langfuse with an Existing OpenTelemetry Setup for configuration guidance.

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)

On the Langfuse v4 data model, filters and aggregations operate across individual observations, and every observation row stores its own copy of these attributes. A span that does not carry them is not matched when you filter or group by user, session, tags, and so on — setting them only on the root span means only the root observation is found. To reliably filter and aggregate, the attributes need to be present on each span in the trace.

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:

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

For implementation details and code examples, refer to the OpenTelemetry documentation for Python and JavaScript.

Alternative: Use Langfuse SDK Helpers

If you're using the Langfuse SDKs with OpenTelemetry integration, you can use the convenience methods propagate_attributes() (Python) or propagateAttributes() (TypeScript), which handle attribute propagation automatically. These methods provide a simpler interface and are the recommended approach when using Langfuse SDKs. See Add attributes to observations for implementation details.

Ingestion Options

OpenTelemetry-native Langfuse SDKs

The quickest path to start tracing with Langfuse are the OTEL-native Langfuse SDKs (Python SDK v4, JS/TS SDK v5). The SDKs are a thin layer on top of the official OpenTelemetry client that automatically converts emitted spans into rich Langfuse observations (spans, generations, events, and other observation types), adds first-class helpers for LLM-specific features such as token usage, cost tracking, prompt linking, and scoring, and handles trace attribute propagation via propagate_attributes() / propagateAttributes().

Because they live in the shared OpenTelemetry context, spans from other OTEL-instrumented libraries can be exported to Langfuse too. By default, Langfuse focuses on LLM-relevant spans (Langfuse SDK spans, spans with gen_ai.* attributes, and known LLM instrumentors). To export everything, use a permissive custom filter as described in the advanced SDK docs.

Get started with the dedicated guide: /docs/observability/sdk/overview.

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"

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://cloud.langfuse.com/api/public/otel/v1/traces" # 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

Please note that Langfuse currently supports OTLP over HTTP with both HTTP/JSON and HTTP/protobuf. gRPC is not supported yet.

Custom via OpenTelemetry SDKs

You can use the OpenTelemetry SDKs to directly export traces to Langfuse with the configuration mentioned above. Thereby, Language support of Langfuse is extended to other languages than the ones supported by the Langfuse SDKs (Python and JS/TS).

Use OpenTelemetry GenAI Instrumentation Libraries

Any OpenTelemetry compatible instrumentation can be used to export traces to Langfuse. Check out the following end-to-end examples of popular instrumentation SDKs to get started:

Libraries

• OpenLIT
• OpenLLMetry
• Arize
• MLflow

Framework integrations powered by OpenTelemetry

• Hugging Face smolagents
• CrewAI
• AutoGen
• Semantic Kernel
• Pydantic AI
• Spring AI
• LlamaIndex
• LlamaIndex Workflows

Export from OpenTelemetry Collector

If you run an OpenTelemetry Collector, you can use the following configuration to export traces to Langfuse:

receivers:
  otlp:
    protocols:
    grpc:
      endpoint: 0.0.0.0:4317
    http:
      endpoint: 0.0.0.0:4318

processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G
    limit_mib: 1500
    # 25% of limit up to 2G
    spike_limit_mib: 512
    check_interval: 5s

exporters:
  otlphttp/langfuse:
    endpoint: "https://cloud.langfuse.com/api/public/otel" # EU data region
    # Other regions: US https://us.cloud.langfuse.com/api/public/otel, Japan https://jp.cloud.langfuse.com/api/public/otel, HIPAA https://hipaa.cloud.langfuse.com/api/public/otel
    headers:
      Authorization: "Basic ${AUTH_STRING}" # Previously encoded API keys
      x-langfuse-ingestion-version: "4"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp/langfuse]

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. As this applies on a Span level, you may risk incomplete traces and should be careful when applying complex filter rules. Langfuse also expects the root span of each trace to be sent: it becomes the root observation that represents the trace (trace name, timestamps, time bucketing in charts). Traces whose root span is filtered out can render incompletely or be missing from time-series charts.

With the configuration below, you would only forward Spans which have a gen_ai.system attribute set to openai:

receivers:
  otlp:
    protocols:
    grpc:
      endpoint: 0.0.0.0:4317
    http:
      endpoint: 0.0.0.0:4318

processors:
  filter/openaisystem:
    error_mode: ignore
    traces:
      span:
        - 'attributes["gen_ai.system"] != "openai"'

exporters:
  otlphttp/langfuse:
    endpoint: "https://cloud.langfuse.com/api/public/otel" # EU data region
    # Other regions: US https://us.cloud.langfuse.com/api/public/otel, Japan https://jp.cloud.langfuse.com/api/public/otel, HIPAA https://hipaa.cloud.langfuse.com/api/public/otel
    headers:
      Authorization: "Basic ${AUTH_STRING}" # Previously encoded API keys
      x-langfuse-ingestion-version: "4"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [filter/openaisystem]
      exporters: [otlphttp/langfuse]

Attribute Mapping

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

Furthermore, Langfuse uses attributes within the langfuse.* namespace to map OpenTelemetry span attributes directly to the Langfuse data model. These specific attributes always take precedence over the generic OpenTelemetry conventions and are recommended for all users that are manually instrumenting their applications.

Langfuse distinguishes between trace-level attributes and observation-level attributes.

• Trace-level attributes represent shared context for an entire interaction — user, session, tags, release, version. On the Langfuse v4 data model, every observation stores its own copy of these attributes, so they must be propagated to all spans of a trace.
• Observation-level attributes describe individual steps within a trace. Langfuse keeps them on the observation level.

How Metadata Mapping Works

OpenTelemetry spans can carry arbitrary attributes. Langfuse handles these attributes differently depending on how they are named:

Trace-Level Attributes

These attributes carry the shared context of a trace and are used to group, filter, and aggregate related observations. Set them on every span of a trace (propagation): with direct v4 ingestion, each observation only carries the attributes set on its own span, so a span without them is missed by filters and aggregations. Spans ingested through the transitional non-v4 pipeline (no x-langfuse-ingestion-version: 4 header) retain the previous behavior — attributes set on any span are applied to the whole trace — at the cost of a ~10 minute delay.

with tracer.start_as_current_span("Langfuse Attributes") as span:
    span.set_attribute("langfuse.trace.metadata.user_name", "user-123")

Observation-Level Attributes

These attributes are applied to individual observations (spans) within a trace (data model).

with tracer.start_as_current_span("Langfuse Attributes") as span:
    span.set_attribute("langfuse.observation.metadata.user_name", "user-123")

Troubleshooting

• Filtering by userId, sessionId, or tags only matches the root observation: these trace-level attributes are stored per observation on the Langfuse v4 data model. Propagate them to all spans of the trace — see Propagating Trace Attributes to All Spans.
• Spans appear with a ~10 minute delay: OTel exporters without the x-langfuse-ingestion-version: 4 header flow through the transitional ingestion pipeline. Add the header to your exporter to ingest in real time (configuration).
• If you encounter 4xx errors while self-hosting Langfuse, please upgrade your deployment to the latest version. The OpenTelemetry endpoint was first introduced in Langfuse v3.22.0 and has seen significant improvements since then.
• Langfuse supports OTLP over HTTP with both HTTP/JSON and HTTP/protobuf. gRPC is not supported yet.