Overview - Langfuse (original) (raw)

Docs

Observability

SDKs

Overview

Langfuse offers two SDKs:

The Langfuse SDKs are the recommended way to create custom observations and traces and use the Langfuse prompt-management and evaluation features.

Key benefits

• Based on OpenTelemetry, so you can use any OTEL-based instrumentation library for your LLM stack.
• Fully async requests, meaning Langfuse adds almost no latency.
• Interoperable with Langfuse native integrations.
• Accurate latency tracking via synchronous timestamps.
• IDs available for downstream use.
• Great DX when nesting observations.
• Cannot break your application: SDK errors are caught and logged.

This section documents tracing related features of the Langfuse SDK. To use the Langfuse SDK for prompt management and evaluation, visit their respective documentation.

Requirements for self-hosted Langfuse Legacy documentation

This documentation is for the latest versions of the Langfuse SDKs.

• Documentation for the legacy Python SDK v3 can be found here.
• Documentation for the legacy TypeScript SDK v4 can be found here.

Follow the quickstart guide to get the first trace into Langfuse. See the setup section for more details.

This section covers all detail of setting up the Langfuse SDKs. Follow the Quickstart guide to create your first trace.

The Langfuse SDKs are built on top of OpenTelemetry. This provides:

• Standardization with the wider observability ecosystem and tooling.
• Robust context propagation so nested spans stay connected, even across async workloads.
• Attribute propagation to keep userId, sessionId, metadata, version, and tags aligned across observations.
• Ecosystem interoperability meaning third-party instrumentations automatically appear inside Langfuse traces.

The following diagram shows how Langfuse maps to native OpenTelemetry concepts:

• OTel Trace: An OTel-trace represents the entire lifecycle of a request or transaction as it moves through your application and its services. A trace is typically a sequence of operations, like an LLM generating a response followed by a parsing step. The root (first) span created in a sequence defines the OTel trace. OTel traces do not have a start and end time, they are defined by the root span.
• OTel Span: A span represents a single unit of work or operation within a trace. Spans have a start and end time, a name, and can have attributes (key-value pairs of metadata). Spans can be nested to create a hierarchy, showing parent-child relationships between operations.
• Langfuse Trace: A Langfuse trace collects observations and holds trace attributes such as session_id, user_id as well as overall input and outputs. It shares the same ID as the OTel trace and its attributes are set via specific OTel span attributes that are automatically propagated to the Langfuse trace.
• Langfuse Observation: In Langfuse terminology, an "observation" is a Langfuse-specific representation of an OTel span. It can be a generic span (Langfuse-span), a specialized "generation" (Langfuse-generation), a point-in-time event (Langfuse-event), or other observation types.
  • Langfuse Span: A Langfuse-span is a generic OTel span in Langfuse, designed for non-LLM operations.
  • Langfuse Generation: A Langfuse-generation is a specialized type of OTel span in Langfuse, designed specifically for Large Language Model (LLM) calls. It includes additional fields like model, model_parameters, usage_details (tokens), and cost_details.
  • Langfuse Event: A Langfuse-event tracks a point in time action.
  • Other observation types: Langfuse supports other observation types such as tool calls, RAG retrieval steps, etc.
• Context Propagation: OpenTelemetry automatically handles the propagation of the current trace and span context. This means when you call another function (whether it's also traced by Langfuse, an OTel-instrumented library, or a manually created span), the new span will automatically become a child of the currently active span, forming a correct trace hierarchy.
• Attribute Propagation: Certain trace attributes (user_id, session_id, metadata, version, tags) can be automatically propagated to all child observations using propagate_attributes(). This ensures consistent attribute coverage across all observations in a trace. See the instrumentation docs for details.

The Langfuse SDKs provide wrappers around OTel spans (LangfuseSpan, LangfuseGeneration) that offer convenient methods for interacting with Langfuse-specific features like scoring and media handling, while still being native OTel spans under the hood. You can also use these wrapper objects to add Langfuse trace attributes via update_trace() or use propagate_attributes() for automatic propagation to all child observations.

Langfuse maintains SDKs for Python and JavaScript/TypeScript. For other languages, you can use our OpenTelemetry endpoint to instrument your application and use the public API to use Langfuse prompt management, evaluation, and querying.

Instrumentation

To instrument your application, you can send OpenTelemetry spans to the Langfuse OTel endpoint. For this, you can use the following OpenTelemetry SDKs:

• JetBrains Tracy for Kotlin/Java
• OpenTelemetry Java
• OpenTelemetry .NET
• OpenTelemetry Go
• OpenTelemetry C++
• OpenTelemetry Erlang/Elixir
• OpenTelemetry Ruby
• OpenTelemetry PHP
• OpenTelemetry Rust
• OpenTelemetry Swift

Prompt management, evaluation, and querying:

To use other Langfuse features, you can use the public API to integrate Langfuse from any runtime. We also provide a list of community-maintained SDKs here.