How Dify sends app traces to Langfuse
A team running Dify workflows and chatflows often needs token counts, node execution details and run history in a trace store it controls, not in a vendor's hosted service. The supported path for this is the per-app Langfuse setting on the Monitoring page under tracing app performance. You create a project in your Langfuse instance, generate its public key and secret key, and enter those together with the Langfuse host in Dify. Dify does not act as a general OpenTelemetry exporter in this path, so you should not plan around OTLP endpoints or Collector pipelines when you configure it. Confirm the current field names and the steps on the Monitoring page against the Dify Langfuse integration docs before you write runbooks, because the screens change between releases.
Both products are open source and can run inside your own network. Langfuse offers the same core features in its MIT-licensed version and documents a self-hosted deployment built from the same codebase as its cloud service. The Langfuse side needs its own planning: a web container, a worker container, PostgreSQL, ClickHouse, Redis or Valkey, and S3-compatible blob storage. DeployOpen plans and builds that Langfuse deployment and the Dify configuration for each app, including key ownership, host reachability from the Dify network and the access model for the trace project. Ask who in your organization will own the project keys, since rotating a key means updating every app that uses it.
Before you rely on traces for cost or incident review, run a test. Send a single test message through each app, then check that the trace in Langfuse shows the expected input, output, status, total tokens and node-level steps. Confirm that prompts and outputs in those traces are acceptable to store in your Langfuse project, because the trace contains the inputs and outputs of the run. Also confirm that the Dify container can reach the Langfuse host through your proxy and firewall rules, since a blocked host usually shows up as silent missing traces rather than an error in the app.
What a Langfuse tracing integration needs before setup
Dify sends traces to Langfuse from its own api container, so the version pairing, network path and certificate trust must work before you touch the Monitoring page. Each card below is a prerequisite that is easy to assume and expensive to debug later.
Dify version and Compose baseline
Confirm your Dify release and Docker Compose version before planning the integration. The self-hosting docs require Docker Compose 2.24.0 or later and at least 2 CPU cores and 4 GB of RAM for the Compose deployment. Dify ships minor releases roughly monthly, so record the exact tag you run and read its upgrade guide before changing it. Tracing settings are per app, so a version change can affect how existing apps report.
Self-hosted Langfuse stack running
Langfuse needs more than its web container. A self-hosted deployment runs Langfuse Web for the UI and APIs and Langfuse Worker for asynchronous processing, plus PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible blob storage. Confirm each component is healthy and sized, because missing traces are often a worker or ClickHouse problem rather than a Dify problem.
Langfuse version and v4 prerequisites
Match the Langfuse release to your data plan before you send traffic. The v3 to v4 guide requires ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later, and moves to an observations-first ClickHouse data model. If you are upgrading an existing v3 instance, plan a migration window and the disk headroom the guide advises for backfilling history.
Host URL reachable from the Dify api container
The host you enter in Dify is resolved and called from inside the api container, not from your browser. A localhost address or a hostname that only your workstation resolves will fail silently. Test the exact URL from inside the container with the same DNS and network path Dify uses, and confirm the port and path reach the Langfuse Web service rather than the database or a reverse proxy with the wrong route.
TLS certificate trust path
If Langfuse runs behind HTTPS with an internal certificate authority, the Dify api container must trust that chain. Otherwise the connection fails during the handshake and the app's monitoring status stays unconfigured or in error. Ask your platform team which CA issued the certificate, confirm the chain is complete, and decide how the CA certificate gets into the Dify image or container trust store. Verify the trust with a request from inside the container before configuring the app.
SSRF proxy path to internal Langfuse
Dify routes outbound requests through an SSRF proxy that blocks internal and private IP ranges, controlled by the SSRF_PROXY settings. If Langfuse sits on a private address, the call may be refused before it leaves Dify. Confirm whether your SSRF proxy configuration permits the Langfuse host or whether the tracing call bypasses it in your build, and test with a real trace. Treat any allowlist change as a security decision that needs review.
Project keys created before setup
Create a dedicated Langfuse project for the Dify environment and generate its public and secret API keys before you open the Dify console. You will paste the secret key, public key and host into each app's Monitoring page. Keep the secret key out of shared notes and tickets, and confirm which Langfuse user or team owns the key so rotation has a clear owner.
Configuring tracing for each Dify app
This sequence connects one Dify app to a self-hosted Langfuse project, then proves with test runs that traces arrive with IDs you can match back to Dify. Repeat it for each app you want traced.
Create the Langfuse project and API keys
In your self-hosted Langfuse instance, create a project dedicated to the Dify app or environment you are tracing, then generate a public key and a secret key for that project. Store the secret key in your secrets manager rather than in a shared document, because Dify will hold it and anyone with console access to the app can view it. The step is done when you have the secret key, public key and the host URL of your Langfuse instance written down in your secure record, and the project appears empty in the Langfuse UI. For background on running Langfuse itself, see the Langfuse self-hosting documentation.
Confirm the Langfuse host is reachable from Dify
From the network where the Dify api and worker containers run, confirm that the Langfuse host URL resolves and accepts HTTPS connections on the port you plan to use. Dify sends traces from its own servers, so a URL that only works from your laptop will fail silently or show errors later. Check outbound routing, any proxy or egress allowlist, and TLS trust for an internal certificate authority if Langfuse uses one. The step is done when a request to the Langfuse host from the Dify host returns a normal response. If your Dify deployment routes outbound traffic through the SSRF proxy, confirm that the Langfuse host is permitted by that path, since the proxy is designed to block internal and private address ranges.
Open the app's Monitoring page
Sign in to the Dify console as a user with rights to edit the app, open the app you want to trace, and go to its Monitoring page under tracing app performance. Tracing is configured per app, so each workflow, chatflow or agent app needs this step even if they share a workspace. Note the app name and its ID so you can match later test traces to the right app. The step is done when the tracing settings for that app are visible and show Langfuse as an available provider.
Enter the Langfuse keys and host
In the Langfuse tracing settings for the app, paste the secret key, the public key and the host URL from your Langfuse project, then save the configuration. Enter values exactly as Langfuse displays them, including the scheme in the host URL, and avoid trailing spaces that cause authentication errors. Keep the configuration limited to the app being traced so that other apps in the workspace do not send data to the same project. The step is done when Dify saves the configuration without a validation error and the tracing provider shows as enabled for this app.
Enable tracing and record the app state
Switch tracing on for the app and confirm the setting persists after a page reload. Before testing, record the published version of the workflow or chatflow, since Langfuse traces for workflows include a workflow version field that you will want to compare against. Make sure the app is published or that you know which draft you are testing, because test results from an unpublished draft may not match what end users see. The step is done when the tracing toggle remains on after reload and you have noted the app name, app ID and version under test.
Run a test workflow and verify the trace
Run the workflow with a short, non-sensitive test input, then open the Langfuse project and locate the new trace. Compare the workflow run ID, timestamps and status with what Dify shows in its logs for that run, and check that node execution details and token totals appear. Use synthetic test data only, since inputs and outputs are sent to Langfuse. The step is done when the trace in Langfuse has a run ID that matches the Dify run, and the node list matches the nodes you executed.
Run a test chatflow and match conversation IDs
Start a new conversation in the chatflow, send two or three test messages, then find the corresponding trace in Langfuse. Check that the conversation ID in the trace matches the conversation shown in Dify and that each message is recorded with its own identifiers, so you can follow a multi-turn exchange. Repeat for each app that will be traced in production. The step is done when the conversation ID in Langfuse matches the Dify conversation, and you have written the test results into your change record before enabling tracing for real users.
Which trace fields Dify exports to Langfuse
Workflow traces describe a single run of a Dify workflow from start to finish. They are the primary record when a reviewer asks what ran, when it ran, which version of the workflow executed and whether it succeeded. The Dify Langfuse integration documentation lists the run-level fields that are sent, and node execution details are included so that each step of the workflow can be inspected on its own.
- Identifiers: The workflow ID and workflow run ID let you tie a Langfuse trace back to the exact run in Dify's logs and to the app version that produced it.
- Version and trigger: The workflow version shows whether a change in behavior followed a publish, and the trigger source shows whether the run came from a user, an API call or another automated source.
- Status, timing and errors: Elapsed time, status, start and end times and error messages help you find slow or failing runs and confirm when an incident began.
- Token and file counts: Total tokens and files processed support cost reviews and show whether a run handled documents.
- Node execution details: Per-node records show which step consumed the time or tokens and where an error first appeared.
Before you rely on these fields for review, confirm with a test run in your own environment which node details appear for each node type you use.
Message and chatflow traces follow a conversation rather than a single run. A chat app can produce many messages inside one conversation, so the conversation ID is the field that links them. Reviewers use this view to answer questions about a user's session, such as what the assistant said in response to a given request and how the exchange developed over several turns.
- Conversation ID: Groups related messages so a reviewer can reconstruct a full exchange instead of isolated calls.
- Message-level inputs and outputs: Show what the user sent and what the model returned for each turn.
- Timing and status: Show response time and whether each message completed, which helps identify slow turns in a long conversation.
- Token usage: Shows how much each turn consumed, useful for tracking cost per conversation.
- Linked execution data: Where a chatflow calls nodes or tools, the related execution data is what explains an unexpected answer.
Confirm in your own test environment whether a given chatflow or app type produces the fields you expect, since the exported set depends on the app configuration.
Inputs and outputs are the most valuable fields for debugging and the most sensitive. They contain whatever users typed, whatever documents were processed and whatever the model produced, which can include names, account details, health or financial information and internal material. Once these values reach Langfuse, the tracing store becomes a repository of that content, with its own access, retention and backup obligations.
- Personal data: Prompts and responses may contain personal information that falls under your privacy obligations.
- Confidential material: Documents passed through workflows can carry internal or client-confidential content into traces.
- Access scope: Anyone with access to the Langfuse project can read the captured values, so project roles should match who may see that data.
- Retention and backups: Trace data persists in ClickHouse and blob storage, so deletion and backup policies must cover it.
- Masking decisions: Decide whether to mask fields before export and confirm which masking options your Langfuse edition supports.
Before enabling tracing on a production app, ask your security and privacy teams to approve the data classes that will be sent and document the controls that protect them.
Each field earns its place by answering a specific question. Mapping the fields to the questions your reviewers ask makes it clear which ones to keep, which to restrict and which to leave out of a shared view. The mapping below is illustrative and should be adjusted to your own review process.
- Incident response: Status, errors, timing and node details show where a run failed and when the failure started.
- Change review: Workflow version and trigger source show whether a publish or an external event changed behavior.
- Cost review: Total tokens, per-message token usage and file counts support spend analysis by app or conversation.
- User-level investigation: Conversation ID and message inputs answer what happened in a specific session, subject to your privacy controls.
- Model behavior audits: Outputs paired with the app version show what a model returned under a given configuration.
Ask your Dify and Langfuse administrators to demonstrate, in a test workspace, that each field appears as you expect for the app types you run.
Mapping Dify run data to Langfuse trace fields
This table compares Dify run concepts with where they appear in a Langfuse trace. Fields listed in the Dify Langfuse integration documentation are marked as documented, and everything else should be checked against a test trace from your Dify version before you build dashboards or alerts on it.
| Dify concept | Where it appears in Langfuse | Source status |
|---|---|---|
| App and workflow version | Trace metadata for the workflow version and app-level tracing settings | Documented: workflow version is listed. Confirm the exact metadata key names in a test trace. |
| Workflow run ID | Trace identifier linking the run to Dify's own run record | Documented: workflow and run IDs are listed. Confirm which one maps to the Langfuse trace ID. |
| Conversation ID | Session or metadata field grouping messages from one chat | Documented: conversation ID is listed. Confirm whether it appears as a session grouping in your Langfuse version. |
| Node executions | Child observations or spans, one per workflow node run | Documented: node execution details are listed. Confirm the observation types and nesting in a test run. |
| Total tokens | Usage fields on the trace or generation observations | Documented: total tokens is listed. Confirm whether input and output splits are also sent for each model call. |
| Trigger source | Metadata field showing what started the run, such as an end user or API call | Documented: trigger source is listed. Confirm the values Dify sends for each trigger type. |
| Status, errors and timing | Trace status, error output and start and end timestamps | Documented: status, errors, start and end times and elapsed time are listed. Test a failing node to see how errors appear. |
| Files processed | Metadata or input fields listing files handled by the run | Documented: files processed is listed. Confirm whether file names or only counts are sent. |
| Inputs and outputs | Trace input and output fields, which may contain prompts and user data | Documented: inputs and outputs are listed. Plan masking or access controls before enabling this in production. |
Questions teams ask before connecting Dify to Langfuse
What does connecting Dify to Langfuse cost in effort, and what is one-time versus recurring?
The one-time work is creating a Langfuse project, generating API credentials, configuring tracing on each Dify app and checking that traces arrive with the fields you need. The recurring work is operating Langfuse itself: upgrades, backups, capacity, certificates and monitoring of the web, worker, PostgreSQL, ClickHouse, Redis or Valkey and blob storage. The connection step is small compared with running the Langfuse stack. Ask any partner for a quote that separates the Dify connection work from Langfuse deployment, sizing, backup and support, because those are paid for differently. Langfuse self-hosting also needs the cost of your own infrastructure, which the quote will not include.
Can our team connect Dify to Langfuse without outside help?
Yes, for a single test app, the connection itself is a configuration task. You create a Langfuse project, copy the public key, secret key and host, and paste them into the Monitoring page of the app under tracing app performance. The harder part is everything around it: running a self-hosted Langfuse with its web and worker containers, PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible storage, deciding who owns keys, and proving that prompt data stays where your policy requires. Teams without someone who has operated ClickHouse or similar stateful services often bring in a partner for the Langfuse side and keep the Dify configuration in-house.
What do we need to provide before the work starts?
Plan for four inputs. First, a Langfuse instance you can reach, or a decision to deploy one in your infrastructure. Second, network paths from the Dify api and worker containers to the Langfuse host, which may need firewall rules or DNS entries depending on where each runs. Third, named owners for the Langfuse project, the API keys and their rotation. Fourth, a test Dify app with representative workflows and a chatflow, so you can check the trace fields against real inputs and outputs. Confirm with your security team whether prompts and outputs may leave the Dify network before you choose a destination.
How long does the integration take, and what changes the timeline?
The duration depends mostly on how many Dify apps need tracing and how ready your Langfuse environment is. Configuring one app is a short task, but each additional app needs its own project decision, key handling and verification of trace content. If Langfuse already runs in production with backups and capacity planned, the work is mainly configuration and testing. If Langfuse must be deployed, sized and backed up first, that stack becomes the critical path. Ask for a written scope that lists the apps, the Langfuse state you assume and the acceptance checks, then compare the timeline against that scope.
Is Langfuse Community enough for production tracing?
For core tracing, yes. Langfuse states that all core features and APIs are available in the MIT-licensed open source version without limits, and self-hosted deployments use the same codebase as Langfuse Cloud. Enterprise license keys gate specific capabilities: project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side data masking, UI customization, organization creators, the org management API with SCIM and the instance management API. If your governance requires role separation, retention rules, audit trails or masking of sensitive fields in the Langfuse interface, check those requirements against the license key documentation before deciding. Langfuse also offers a custom-priced Self-Hosted Enterprise plan with support, which you should price separately.
Can we send Dify traces to Langfuse Cloud if our data is regulated?
Langfuse Cloud is a hosted service, so traces that include prompts, inputs, outputs and errors leave your infrastructure when sent there. Whether that is acceptable depends on your data classification, contracts, data residency rules and sector regulations, and those decisions belong to your compliance and legal teams. If the answer is no, self-host Langfuse in infrastructure you control, which uses the same codebase as Langfuse Cloud. DeployOpen can plan and deploy that self-hosted environment and prepare the configuration and evidence your assessors will ask for, but it does not issue audit reports or certifications. Independent auditors and certification bodies do that work.
When is OpenTelemetry a better fit than the native Dify Langfuse integration?
Choose the native Dify integration when your goal is LLM-specific tracing of Dify workflows, chatflows and messages, with node executions, token counts and run metadata already mapped. Consider OpenTelemetry when you need one telemetry pipeline across many services, or when Langfuse must receive data from applications outside Dify. Langfuse documents an OpenTelemetry integration path, but that path requires instrumenting your own code, which Dify's built-in tracing does not do for you. Confirm which trace fields you need before choosing, because the Dify docs list other tracing backends, and each one exports a different set of fields.
Protecting prompts and keys in the tracing path
Tracing sends prompts, outputs, inputs and errors out of Dify and into a second system, so the tracing path needs the same care as the apps it observes. The cards below cover the credentials that connect the two, the masking and access choices in Langfuse, the transport and network placement, and how long trace data is kept.
Scope keys per app
Dify stores one Langfuse secret key, public key and host for each app's Monitoring page, so each app is a separate tracing configuration. Create a dedicated Langfuse project and key pair for each app or environment where your team can, so a leaked key exposes one project rather than all traces. Confirm with your Langfuse administrator how keys are issued and revoked in your self-hosted version.
Store and rotate the secret key
The secret key is the credential that lets Dify write traces into a Langfuse project, and it is entered in the app's Monitoring settings. Restrict who can open those settings in Dify, and record which app holds which key. Plan rotation as a runbook: create a new key in Langfuse, update the app, confirm new traces arrive, then revoke the old key. Confirm in your environment whether Dify keeps the value in a readable form after saving.
Masking gap in Community tier
Trace fields include inputs, outputs and errors, which can carry customer data, personal data or confidential prompt text. Server-side data masking is listed among the self-hosted Langfuse features that need an Enterprise license key, so a Community deployment should not assume masking happens automatically. Decide what may reach a trace before enabling tracing, and confirm the current masking options with Langfuse before relying on them.
Control UI access with RBAC or SSO
Anyone with access to a Langfuse project can usually read the prompts and outputs stored there, so the Langfuse UI is part of the data boundary. Project-level RBAC roles are an Enterprise license feature, and SSO for self-hosted Langfuse is covered in its authentication documentation. Map who may view traces per project, remove access when people change roles, and confirm which login methods your version supports.
Encrypt the Dify to Langfuse path
Keys and trace payloads travel from Dify to the Langfuse host, so the host address entered in Dify should use HTTPS and a certificate your internal clients trust. Check that the certificate chain is trusted by the Dify api and worker containers, not only by your browser. Confirm whether any internal CA bundle must be added to the Dify images, and test the connection with a non-sensitive app before enabling production traces.
Place the Langfuse host deliberately
Langfuse runs web, worker, PostgreSQL, ClickHouse, Redis or Valkey and blob storage, so it holds a full copy of trace content. Place it on a network segment that Dify can reach but that most users and external networks cannot, and limit access to the database and blob storage to the Langfuse services. Document which network paths carry traces, and check them against your data classification before go-live.
Set trace retention before go-live
Traces accumulate in ClickHouse and blob storage until something removes them, and retention is the control that limits how long prompts and outputs exist. Self-hosted data retention policies are an Enterprise license feature, so the Community tier may require a scheduled cleanup or storage lifecycle rule that your team owns. Agree the retention period with the data owner, test deletion, and include backups of Langfuse data in the same retention decision.
Why traces are missing or incomplete in Langfuse
This table lists the failures that most often leave Dify traces missing or partial in a self-hosted Langfuse project, with the cause and fix for each. Read it in order when traces do not appear: confirm the app configuration and endpoint first, then the key pair and project, then the Langfuse processing path. The main takeaway is that most gaps come from configuration or network reachability, while delays and dropped data usually point to Langfuse capacity.
| Symptom or failure | Likely cause | Fix |
|---|---|---|
| No traces at all after enabling tracing | Host value points to a URL the Dify api or worker container cannot reach, such as localhost or an address only the browser can resolve | Set the host to a URL resolvable from inside the Dify containers, then test from the api container with a simple HTTP request before re-running the app |
| Authentication errors or empty project | Public and secret keys come from different projects or different Langfuse instances | Copy the public key, secret key and host from the same project in the same Langfuse instance, and re-paste all three into the app's Monitoring page |
| Traces appear in a different project | The key pair belongs to another Langfuse project than the one you are reviewing | Confirm the project name that owns the key pair in Langfuse settings, then either change the keys in Dify or move your review to that project |
| Connection fails over HTTPS only | Langfuse uses a certificate from a private or internal CA that the Dify containers do not trust | Add the internal CA to the trust store of the Dify api and worker images, and confirm the host uses the exact name on the certificate |
| Traces arrive late or in bursts | Langfuse Worker has a processing backlog, so asynchronous event processing lags behind ingestion | Check worker CPU load and queue depth, then scale worker containers on CPU load as the Langfuse scaling guide recommends |
| Ingestion slows or traces are dropped under load | ClickHouse lacks CPU or memory for the write and query volume, or langfuse-web handles ingestion and UI on one deployment | Size ClickHouse to the scaling guide minimums and raise memory for larger volumes; under heavy ingestion, split langfuse-web into ingestion and UI deployments |
| Some apps show traces and others do not | Tracing was never enabled or saved for those specific apps, since configuration is set per app | Open each missing app's Monitoring page, confirm the Langfuse provider is enabled with saved keys, then run a fresh test message |
| Workflow traces show fewer node details than expected | The run failed or stopped early, or the trace was exported before all node executions completed | Check the run's status and errors in Dify, then compare the run ID with the trace in Langfuse to confirm which step ended the run |
When OpenTelemetry or another backend fits better than Langfuse
Choose Langfuse when the people reviewing traces are AI application owners and evaluators who need Dify-specific views: workflow runs, node executions, prompts, inputs, outputs and token totals arranged around LLM work. The Dify integration sends these fields directly, so a team gets useful LLM views without building its own mapping. The trade-off is that Langfuse becomes one more stateful system to run. Its self-hosted deployment uses web, worker, PostgreSQL, ClickHouse, Redis or Valkey, and S3-compatible storage, so the platform team should decide before rollout who owns that stack and its upgrades.
Choose OpenTelemetry when the organization is standardizing telemetry across applications, services and infrastructure, and wants one collection path into one set of backends. The Langfuse OpenTelemetry documentation describes how Langfuse can receive OpenTelemetry data, which matters if your Dify-adjacent services already emit OTel signals. Confirm with your own engineers whether Dify's per-app Monitoring page, as currently configured, covers the trace depth you need, or whether you would instrument around Dify at the gateway and service layers. Expect the Collector pipeline and its data handling to become a shared platform responsibility.
Dify's docs also list LangSmith, Opik, W&B Weave, Arize, Phoenix and Alibaba Cloud Monitor as tracing options. Each has its own sibling page in this group, covering setup, the trace fields it receives and where it can run. This page does not rank them. Shortlist the options against three questions: where prompt data may be stored, which team will operate the backend, and whether your observability standard already has a backend in place that the Dify traces should join.
How DeployOpen scopes and delivers the Langfuse tracing integration
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure. For Dify and Langfuse tracing, we start with a written scope covering which apps are traced, where Langfuse runs and who owns the keys, then build and hand over the configuration with runbooks your team can operate.
How we scope
- Inventory which Dify apps, workflows and chatflows need traces and which should stay untraced
- Confirm where the self-hosted Langfuse project runs and who holds project API credentials
- Agree which trace fields, such as token counts and node executions, your reviewers need
- Record data handling decisions for prompts, outputs and user inputs before any trace is sent
- Agree in writing the scope, deliverables and timelines before work starts, as most engagements are fixed-scope
How we build
- Create Langfuse project credentials and configure tracing per app on the Monitoring page
- Run test conversations and workflow executions to confirm traces arrive with expected run and node details
- Check that Langfuse Web and Worker containers, PostgreSQL, ClickHouse and blob storage are sized for the planned volume
- Verify that the Langfuse host is reachable from the Dify api and worker containers under your network rules
- Test the configuration against a staging Dify instance before enabling it on production apps
How we hand over
- Document each traced app, its key rotation owner and the Monitoring settings used
- Provide a runbook for disabling tracing, rotating keys and checking trace delivery after a Dify upgrade
- Record the Langfuse version, major upgrade path and backup approach your team must follow
- Walk your operators through trace review in Langfuse and the fields exported from Dify
- Deliver the configuration and documentation inside your infrastructure, with no external dependency
How we support
- Offer ongoing support, upgrades and continuous testing for Dify and Langfuse as a retainer
- Retest tracing after each Dify minor release, which arrives roughly monthly, and after Langfuse upgrades
- Review trace volume and Langfuse sizing when new apps or workflows are added to tracing
- Confirm the scope of any change in writing before it is implemented
- Ask for a quote built from the written scope, since DeployOpen does not publish a price list
