How langfuse/langfuse-python works
Overview
Langfuse Python SDK is a client library for Langfuse observability and evaluation services. The current v4 path is OpenTelemetry-based: application code obtains a client with get_client(), creates nested observations or uses @observe, and flushes emitted data. The package also covers prompts, datasets, experiments, scores, media, integrations, and REST API access.
Core components
• Public SDK surface — langfuse/__init__.py
Exposes the package-level entry points used by application code, including the documented get_client() flow. Runtime configuration is supplied externally, including LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_BASE_URL.
• OpenTelemetry client and instrumentation — langfuse/_client
Implements client lifecycle, observation/span handling, decorators, attribute propagation, filtering, serialization, and span export/processing. This is the main runtime instrumentation area for start_as_current_observation, nested spans/generations, and flushing telemetry to Langfuse.
• Asynchronous work management — langfuse/_task_manager
Owns process-local work queues and consumers for media uploads and score ingestion. It is an implementation area for deferred background submission rather than a durable repository-backed store.
• Generated REST API — langfuse/api
Provides the broad service API surface, organized into resource clients such as observations, ingestion, prompts, datasets, scores, sessions, projects, and health. Resource-specific client.py, raw_client.py, and types packages represent the public API operations and request/response models. langfuse/api/core supplies shared HTTP, serialization, error, pagination, and request infrastructure.
• Evaluation and experiment workflows — langfuse/experiment.py and langfuse/batch_evaluation.py
Contains higher-level support for experiments, batch evaluation, and regression-style evaluation workflows described by the README. These complement the lower-level generated API and score models.
• Provider integrations — langfuse/openai.py and langfuse/langchain
Adapts OpenAI and LangChain usage to the SDK’s observability model. langfuse/langchain/CallbackHandler.py is the main LangChain callback implementation; application code and provider libraries remain external actors.
• Additional domain helpers — langfuse/media.py and langfuse/model.py
Provides package-level helpers for media and model-related functionality, alongside corresponding generated API resources.
Relationships
Application code calls the package entry points in langfuse/__init__.py or uses the OpenAI/LangChain integration modules. The client/instrumentation subsystem owns observation context and export processing; its emitted telemetry is sent to the external Langfuse service through the SDK’s HTTP/API infrastructure. The task manager owns deferred media and score submission work.
Higher-level experiment and evaluation helpers use the SDK’s domain/API capabilities, while langfuse/api remains the general REST client boundary for callers needing direct resource operations. langfuse/api/legacy is a separate compatibility surface for deprecated v1-style APIs; the README identifies the older tracing client API as deprecated for new instrumentation.
State and external boundaries
Runtime buffering and queues are process-local implementation areas visible under the client and task-manager directories. No repository-local durable database is evident in the supplied tree. The main external boundary is the Langfuse HTTP service; application code, OpenAI, LangChain, and other model providers supply the workload being instrumented.
Main entry points: api Generated REST API · _client OTel client and instrumentation · openai.py OpenAI integration · langchain LangChain integration
Components 15
Runtime
Instrumentation and deferred work management.
- Public SDK surface
langfuse/__init__.py - OTel client and instrumentation · Manages observation context, telemetry processing, and flushing.
langfuse/_client - Task manager · Queues deferred media uploads and score submissions.
langfuse/_task_manager
API and domain
REST access and higher-level workflows.
- Generated REST API · Provides resource clients and shared HTTP infrastructure.
langfuse/api - Legacy API · Separate deprecated v1-style compatibility surface.
langfuse/api/legacy - Evaluation workflows
langfuse/experiment.py - Batch evaluation
langfuse/batch_evaluation.py - Media helpers
langfuse/media.py - Model helpers
langfuse/model.py
Integrations
Provider-specific observability adapters.
- OpenAI integration
langfuse/openai.py - LangChain integration
langfuse/langchain
Other components
- Application code · Supplies workloads and uses the SDK.
- Langfuse service
- OpenAI
- LangChain
Connections 16
- Application code → Public SDK surface: calls
- Public SDK surface → OTel client and instrumentation: provides access to
- Application code → OpenAI integration: uses
- Application code → LangChain integration: uses
- OpenAI integration → OTel client and instrumentation: adapts to
- LangChain integration → OTel client and instrumentation: adapts to
- OpenAI → OpenAI integration: supplies workload to
- LangChain → LangChain integration: supplies workload to
- OTel client and instrumentation → Generated REST API: exports telemetry through
- OTel client and instrumentation → Langfuse service: sends telemetry to
- Task manager → Generated REST API: submits deferred work through
- Generated REST API → Langfuse service: calls
- Evaluation workflows → Generated REST API: uses
- Batch evaluation → Generated REST API: uses
- Media helpers → Generated REST API: uses
- Model helpers → Generated REST API: uses