Langfuse Integration#

Dify ships a first-party Langfuse tracing provider that forwards observability data — traces, spans, and generation observations — to a Langfuse project. It is packaged as an isolated Python sub-package under api/providers/trace/trace-langfuse/ and depends on langfuse>=4.2.0,<5.0.0.

The entry point is LangFuseDataTrace, which implements BaseTraceInstance and creates a dedicated LangfuseAPI client per integration instance. All data is sent via the low-level batch ingestion API (client.ingestion.batch) using explicit IngestionEvent_*Create objects rather than the high-level convenience methods deprecated in SDK v3 1.

Data Model#

Three entity types map Dify's runtime events to Langfuse concepts 2:

All three models use filter_none_values before serialization, which strips any field left as None — including id. This behavior is the root cause of the generation dropout issue described below 3.

The GenerationUsage model maps token counts and costs. The totalCost field is populated from message_data.total_price in the message_trace path 4.

Trace Paths#

The trace() dispatcher routes each BaseTraceInfo subtype to a dedicated handler:

• workflow_trace() — emits a top-level Langfuse trace, a workflow span, then iterates all WorkflowNodeExecution rows and creates generation observations for LLM nodes and span observations for others. Every generation is created with id=node_execution_id 5, so workflow apps are unaffected by the ID bug.
• message_trace() — used by Chatbot, Agent, and Completion apps. Emits one trace and one llm generation observation 6.
• moderation_trace(), suggested_question_trace(), dataset_retrieval_trace(), tool_trace() — additional child observations on the message path 7.

The trace_id for all events is resolved as trace_info.trace_id or message_id (or workflow_run_id for workflows) 8.

SDK v2→v3 Migration (Dify v1.14.0) and Regressions#

PR #34265 (merged 2026-03-30) upgraded the Langfuse SDK from ~=2.51.3 to >=3.0.0 and replaced the old high-level SDK calls with the low-level ingestion API. The v2 methods (client.trace(), client.generation(), etc.) automatically assigned a client-side UUID when no id was supplied; the v3 ingestion API does not.

This introduced two regressions:

1. Generation Observation Dropout (Issue #37824)#

Affected: Chatbot, Agent, and Completion apps (all message_trace paths) from Dify v1.14.0 onward. Workflow / Advanced-Chat apps are not affected.

Root cause: message_trace() constructs LangfuseGeneration without passing an id. filter_none_values strips the None, and CreateGenerationBody is sent with id=None. Langfuse drops the observation, so traces show only the top-level trace node — no cost, 0.00 s latency 9.

The same id-less pattern affects suggested_question_trace(), moderation_trace(), dataset_retrieval_trace(), and tool_trace() 7.

Fix (PR #37833, open at time of writing): Pass id=str(uuid.uuid4()) explicitly when creating LangfuseGeneration in all affected handler methods 9.

2. Cross-Tenant Isolation#

PR #36107 (merged 2026-05-13) and PR #41403 addressed cross-tenant security: earlier versions allowed OpenTelemetry spans from the global process to leak into tenant Langfuse projects, and shared a single Langfuse client instance across tenants with identical public keys but different endpoints or secret keys.

Fix: Each LangFuseDataTrace instance now constructs an independent LangfuseAPI client with its own dedicated httpx.Client. The HTTP client is configured with a timeout from the LANGFUSE_TIMEOUT environment variable (default: 5 seconds). The LangfuseAPI client is initialized with base_url, username (from public_key), password (from secret_key), SDK metadata headers, and the httpx_client 10. The close() and __del__() lifecycle methods close the HTTP client connection on cache eviction or garbage collection 11. The close() method is idempotent.

Configuration#

LangfuseConfig (extends BaseTracingConfig) exposes three fields:

A Pydantic field_validator normalizes custom hosts, including paths. Credentials are stored per-app and loaded when LangFuseDataTrace is instantiated.

Key Files#