How Dify sends app traces to Opik
Dify's docs describe a built-in Opik integration that is configured per app, so a team that wants to see Dify workflow and message behavior in an evaluation and monitoring tool can enable tracing without writing custom instrumentation. This section covers the method, the settings that matter and the choice between a self-hosted Opik server and Comet's hosted service. Dify's docs describe Opik as an open-source platform developed by Comet for evaluating, testing and monitoring LLM applications. Because Opik can run in your own infrastructure or be used as Comet's hosted service, the pairing works in either direction of hosting, and the first decision is where the trace data should land.
Start by deciding where prompts and completions may be stored. Trace payloads usually contain user inputs, retrieved knowledge snippets and model outputs, so a self-hosted Opik server keeps that content inside your network, while the hosted service moves it to a third party under Comet's terms. Confirm with your security and legal owners before enabling tracing on any app that handles customer or regulated data. Next, create the Opik project and API credentials that Dify will use, and record the workspace and project names exactly as Opik shows them, since mismatches are a common cause of traces that appear to be missing. Check the current Opik setup steps against the Dify Opik integration guide before you copy any values, because field names and console labels can change between releases.
What you need before connecting Dify to Opik
Tracing from Dify into Opik depends on four things lining up: the Dify version you run, the Docker Compose host that runs it, an Opik endpoint with a project and key, and a clear decision about where prompt and output data travels. Check each card before you open the Dify app tracing settings, because a gap in any one of them shows up later as missing traces or unexpected data flows.
Dify release line and Compose baseline
Confirm which Dify release you run and check that release against the GitHub releases page before work starts, since minor releases arrive roughly monthly and tracing behavior can change between them. The self-hosting docs require at least 2 CPU cores, 4 GB of RAM and Docker Compose 2.24.0 or later for the Docker Compose deployment. Record the exact image tags, because you will need them to reproduce a working tracing setup after an upgrade.
Opik endpoint, project and API key
Decide whether Opik runs on your own server or on Comet's hosted service, then create the workspace, project and API key that Dify will use. Dify's Opik integration needs these values in the app's tracing settings, so write them down before configuring any app. Ask who owns key rotation and who can view project data, because the key grants write access to every trace sent under that project.
Outbound reachability from api and worker
Tracing is sent from Dify's backend, so the api and worker containers must reach the Opik host on the network path and port you choose. Test that connectivity from inside those containers, not from your workstation, because Docker networks, proxies and firewalls often behave differently. Also check whether the SSRF proxy configured in Dify's environment settings will block the destination, since it filters outbound requests to internal and private address ranges.
Data residency for hosted Opik
Traces from Dify can include prompts, model outputs and node inputs, so choosing Comet's hosted service means that content leaves your network. Get written confirmation from your data owner and security team that this data class may be sent to a third-party SaaS service before any key is created. If that answer is no, a self-hosted Opik server inside your own infrastructure keeps the trace content on your side of the boundary.
Secrets and environment handling
The Opik API key should be stored with the same care as other credentials in your Dify deployment, not pasted into shared documents or chat threads. Confirm where your team keeps environment values for the Compose stack, who can read them, and how a key is rotated without breaking running apps. Dify's SECRET_KEY controls encryption of stored OAuth credentials, so changing it is a separate operation with user impact and should not be mixed into a tracing change.
Backup before changing tracing
Dify's Compose docs recommend a backup before every upgrade, and the same caution applies before you change app configuration in bulk. Take a backup of the database and environment file before enabling tracing across several apps, so you can compare behavior and restore a known state if a configuration proves wrong. Plan a test app first, confirm that a trace appears in the correct Opik project, and only then roll the setting out to production apps.
Configuration sequence for Opik tracing in Dify
This sequence connects one Dify app to one Opik project, from choosing the Opik deployment through a verified test trace. Each step ends with a check, so you can confirm tracing works before you repeat it for other apps.
Choose the Opik deployment and endpoint
Decide whether traces go to a self-hosted Opik server or to Comet's hosted service, then record the endpoint, workspace and project names you will use. Your security and platform team should own this decision because it determines where prompts, responses and token counts are stored. Confirm the exact endpoint format and any required fields for your deployment in the Dify Opik integration guide before you enter anything in Dify. Done when the team has a written note naming the deployment, endpoint and project for each Dify app that will be traced.
Create the Opik workspace and project
In your Opik deployment, create or select the workspace for this Dify environment, then create a dedicated project for the app or group of apps being traced. Use a separate project for each app whose traces you need to read on their own, since traces are grouped by project. The project should be empty before the first test run. Done when the project appears in Opik and you can open it, which confirms the name you will enter in Dify is correct.
Generate and store the Opik credentials
Create the API key or credential that Dify will use to send traces, scoped to the workspace from the previous step. Store it in your approved secrets manager or in the environment configuration controlled by your platform team, and limit who can view it. Avoid pasting it into tickets, chat or prompt fields. Done when the credential is recorded in your secrets store and you have confirmed which workspace and project it can write to.
Enable Opik tracing for one Dify app
Open the target app in Dify, go to its monitoring or tracing settings, and select Opik. Enter the endpoint, credential, workspace and project name you recorded earlier. Tracing settings are per app, as the Dify docs describe, so enabling Opik in one app does not turn it on for any other app. Done when the settings save without an error message and the app's tracing configuration shows Opik as saved.
Run a test conversation in the app
Open the app's debug or preview view in Dify and send a short test message that exercises the path you care about, such as a knowledge retrieval step or a tool call if the app uses one. Use test data rather than production records, because prompts and responses are sent to Opik. Done when the conversation completes and returns a response in Dify, which confirms the app ran and can produce a trace.
Confirm the trace in the target project
Open the Opik project you created and find the trace from your test message. Check that it sits in the intended project, that the timestamp matches your test, and that the expected steps appear, including model calls and token fields where the app produces them. If the trace is missing, check the endpoint, credential and project name before you retest. Done when the trace is visible in the intended project and in no other project.
Repeat the mapping for each app
For each additional app, repeat the enablement, test and trace check against its own project, and record the app name, project and credential scope in your deployment notes. Do not share one project across unrelated apps unless the team has agreed that their traces may be read together. Done when every traced app has a documented project and one confirmed test trace, so monitoring owners know where to look.
Self-hosted Opik or Comet's hosted service
With a self-hosted Opik server, the prompts, responses and trace payloads that Dify exports are stored in databases and storage that your team provisions inside your own network. You control the storage location, retention period and backup schedule, and you also own the upgrade calendar. Confirm the components, sizing and supported versions in the Opik documentation before you plan capacity.
- Where prompts and responses live: In the data stores of your Opik deployment. Confirm which stores Opik uses and whether they can be encrypted at rest with keys you manage.
- Upgrades and backups: Your team or your implementation partner runs them. Dify's own Docker Compose guidance recommends a backup before every upgrade, so apply the same discipline to Opik and test restores on a schedule.
- Network path: Dify must reach the Opik endpoint on a private address. Check whether Dify's outbound requests pass through the SSRF proxy, since its settings block internal and private IP ranges by design. Dify environment variables describes that behavior.
- Access model: Users and projects are governed by the access settings of your Opik instance. Confirm which roles and project separation Opik provides before you assign teams.
Confirm that the Opik version you run is supported by your Dify tracing setup, and record who holds upgrade and restore responsibility.
Comet develops Opik and also offers it as a hosted service, so trace data leaves your network and is stored in Comet's infrastructure. Operations, upgrades and backups are Comet's responsibility under the terms you agree. Plan terms, data regions, retention and any charges depend on your agreement with Comet, so confirm them directly with Comet before you configure anything.
- Where prompts and responses live: In Comet's hosted environment. Ask which regions are available, how long traces are retained and whether prompts or fields can be excluded or masked before export.
- Upgrades and backups: Comet handles them. Ask for backup, recovery and change-notice commitments in writing, including notice before changes that could affect the Dify integration.
- Network path: Dify sends traces to Comet's endpoint over outbound HTTPS, so the Dify host's egress rules and proxy settings must allow that destination. Confirm that the SSRF proxy configuration does not block it.
- Access model: Workspaces, projects, roles, API keys and any single sign-on options are managed in Comet. Ask how key rotation and offboarding work on your plan.
- Plan terms and cost: Do not assume a tier, price or usage limit. Request current plan terms and any charges tied to trace volume, and ask for them in a written quote.
Before approval, get Comet's data handling terms, region and retention in writing and have your security and legal teams review them against your data classification.
The choice usually comes down to where prompts may be stored, whether your team has capacity to operate a service, and what your network allows. Compare both options on the same dimensions so the decision is documented and repeatable. The points below are the questions that tend to separate the two options in practice.
- Data residency: If prompts or responses contain regulated or confidential data that cannot leave your network, evaluate self-hosting first.
- Operating capacity: Self-hosting moves upgrades, backups, monitoring and restore testing to your team or partner. A hosted service moves those tasks to the vendor under contract.
- Network constraints: Air-gapped or tightly filtered Dify hosts cannot reach a hosted endpoint without an approved egress path, and a self-hosted server must be reachable from Dify without weakening the SSRF controls.
- Access and audit: Compare project separation, role assignment, key rotation and audit logging in each product's current documentation before you decide.
- Recurring cost: Self-hosting carries infrastructure and staff time, while hosting carries subscription terms. Ask each provider for a written quote based on your expected trace volume.
Run a short proof of concept against a non-sensitive Dify app in each option, and record the result alongside the answers to these questions.
Dify trace fields and where they land in Opik
This table maps the categories of Dify run data that the Dify Opik integration docs describe to the trace and span concepts Opik uses. Field names and how Opik displays them depend on the Opik version you run, so treat the middle column as a hypothesis to confirm. Any row you cannot see in your own instance during a test run should be treated as unsupported until you have verified it.
| Dify run data | Opik concept (to confirm) | What to verify in your Opik instance |
|---|---|---|
| Workflow or chatflow run | Top-level trace for one run | One Dify run appears as one trace, named so you can match it to the Dify app |
| Node executions | Spans nested under the trace | Each node appears as a span, and nesting follows the workflow order |
| Message input and output | Input and output fields on the trace or spans | Prompts and completions are visible, and your viewer access allows seeing them |
| Token counts | Usage values on LLM spans, if mapped | Usage appears on LLM spans and totals match a test run's provider usage |
| Latency and timestamps | Start and end times on traces and spans | Span durations are plausible against a test workflow with a known delay |
| Failed nodes and errors | Error or status on the affected span | A deliberately failing node shows an error status in the correct span |
| App, conversation or user identifiers | Metadata or thread fields, if exported | Confirm the Dify docs and your version expose these before using them for per-user review |
Protecting prompts, keys and trace data
Tracing Dify into Opik copies prompts, user inputs and model outputs to a second system, and the Opik credentials are a second secret to protect. The cards below cover where the key lives, how Dify encrypts and proxies its outbound calls, what the trace content contains, and who can read it in Opik. Confirm each point against the Opik version you run.
Treat the Opik key as a secret
The Opik API key is entered into the Dify tracing configuration for an app, so it is stored by Dify rather than in your application code. Treat it like any other service credential: issue it from a dedicated Opik account or service identity, record its owner, and plan rotation before go-live. Confirm where the key is held in your Dify version and who can open the app's monitoring settings, since those users may be able to view or replace it. Scope the key to one Opik workspace where Opik allows it.
SECRET_KEY protects stored credentials
The Dify environment reference states that SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and that changing it after deployment logs out all users. Set it once, generate it randomly, and store it in your secrets manager so backups and restores use the same value. Confirm with your Dify version whether tracing credentials fall under this encryption, because the reference describes OAuth credentials specifically and does not name tracing keys.
Route Opik calls through SSRF_PROXY
Dify's SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges. A self-hosted Opik server on a private address may therefore be unreachable from Dify, and the failure can look like a tracing error rather than a network block. Decide whether Opik sits on a private host, then test the connection from the Dify API container with the proxy in place. Confirm which hosts your proxy allowlist must include before you open a rule, and keep the allowlist narrow.
Classify prompts and user inputs first
Traces carry the content that flowed through the app: prompts, user messages, retrieved context and model responses. If those fields can include personal data, customer records or regulated information, the Opik deployment inherits that classification. Decide which apps may trace full content, which may trace metadata only, and which must not trace at all, before enabling tracing in production. Confirm with your data protection owner which Opik fields hold this content in your version.
Control project access in Opik
Opik organizes traces into projects, and access decisions are made at the workspace and project level in the Opik console. Give each Dify app or environment its own project, limit membership to the people who debug that app, and avoid sharing one project across unrelated teams. Confirm how your Opik version assigns roles, whether self-hosted and hosted Comet accounts are managed the same way, and how removing a user revokes their access to existing traces.
Set retention and deletion rules
Trace data outlives the conversation that produced it, so a retention rule is part of protection. Ask who deletes traces on request, how long they persist in each environment, and whether deleting a Dify app removes its traces from Opik. For a self-hosted Opik server, include its database and object storage in the backup scope and in the same deletion process. Confirm these behaviors in your Opik version before you promise retention periods to a data owner.
When Opik is preferred over Langfuse
Choose Opik when evaluation and testing matter as much as monitoring, or when your team already works within Comet's ecosystem. Opik is described in Dify's docs as an open-source platform from Comet for evaluating, testing and monitoring LLM applications, so a team that wants trace data and evaluation runs to live in one tool has a clear reason to start here. The same applies to an organization that already uses Comet for experiment tracking and wants LLM traces next to it. Opik also offers a choice of deployment: you can run a self-hosted Opik server inside your network or use Comet's hosted service. That option matters if you want a hosted environment for some projects and a self-hosted one for projects with sensitive prompts, since you can keep both behind a single tracing approach.
Choose Langfuse when self-hosted tracing with prompt management is the main requirement. The separate Langfuse integration page covers that path, and it is the stronger fit when your team wants prompt versioning and prompt management alongside traces, and wants a self-hosted tracing store with the operational footprint that implies. Opik is not a universal replacement for it. Compare the two on the features your reviewers will actually use: prompt management, evaluation workflows, dataset handling and how each one stores and exports data. Confirm current capabilities for both products in their own documentation, because the feature sets in this area change between releases.
The decision depends on three things: operations capacity, data residency and evaluation needs. Running either backend yourself means owning its database, storage, upgrades and backups, so count that capacity before choosing self-hosting. Data residency decides whether a hosted service is acceptable for prompts and completions, or whether the trace store must sit inside your network. Evaluation needs decide whether Opik's testing features are worth the switch. Before committing, send traces from the same Dify app to both a Langfuse project and an Opik project, then compare the fields that arrive, the cost of storing them and how easily your team can find a failing run. That short trial shows more than any comparison table.
Why traces are missing or land in the wrong project
This table pairs each common Opik tracing failure with its likely cause and the check to run first. Read it top to bottom when traces never arrive, arrive late, or show up in a project you did not expect. Most failures come from configuration values or network paths, so verify those before changing app logic.
| Failure | Likely cause | Check to run |
|---|---|---|
| Traces never appear in Opik | Wrong endpoint, workspace or project name, or a typo in the tracing settings | Compare the endpoint, workspace and project values in the Dify tracing panel against your Opik instance, character by character, then send a test message and reload the project. |
| Traces land in an unexpected project | Project name entered differently from the intended one, so Opik created a new project | Open the project list in Opik and confirm whether a similarly named project exists. Correct the project name in the app's tracing settings and send a new test run. |
| Authentication fails silently | API key was created in a different Opik workspace than the one configured in Dify | Regenerate or locate the key in the workspace you intend to use, then update the key in Dify and confirm the workspace value matches that same workspace. |
| Dify container cannot reach the Opik host | Network policy, firewall rules or missing routes between the Dify containers and the Opik server | From inside the Dify API container, test a basic connection to the Opik host and port. Check firewall and network policy rules for that path and confirm DNS resolves the name. |
| Outbound request blocked by SSRF proxy rules | SSRF proxy settings block requests to internal or private address ranges, which often include a self-hosted Opik on a private network | Review the SSRF_PROXY settings in the environment file and confirm how your Opik host resolves. Coordinate any allowlist change with your security team, then test again. |
| Tracing enabled on the wrong app | Tracing was turned on for a different app, or a duplicate app was created during testing | List the apps in the workspace, open each app's tracing settings, and confirm which one is enabled. Send a test message to the intended app only. |
| Traces stop after an upgrade | A Dify upgrade changed configuration keys or defaults, so the tracing values were not carried over | Read the upgrade guide for the target version, compare your environment file with the current .env.example, and re-enter the Opik settings if needed. Take a backup before each upgrade. |
| TLS handshake fails against an internal Opik | Self-signed or private CA certificate that the Dify container does not trust | Confirm the certificate chain used by Opik, check whether your deployment supports adding a trusted CA to the Dify containers, and confirm the approach with your platform team before changing trust stores. |
Questions buyers ask about Dify and Opik tracing
What does it cost to connect Dify to Opik, and who pays for Opik hosting?
The connection itself is configuration work: creating an Opik workspace and project, generating the credentials, and setting tracing per app in Dify. The cost comes from the hours spent on that configuration and testing, plus whoever runs the Opik service. If you self-host Opik, your team or your infrastructure budget pays for the servers, storage, backups and upgrades. If you use Comet's hosted service, the hosting is billed by Comet under its own terms, so confirm those terms directly with Comet. DeployOpen does not publish prices. A quote follows from a written scope that separates one-time setup from recurring operations such as upgrades and monitoring, and it should state which hosting costs sit outside the quote.
How long does a Dify and Opik tracing connection take?
Duration depends on how many apps need tracing, whether Opik is already running, and how many approvals sit between the teams. A single app with an existing Opik project is a short configuration task. Work grows when you add a self-hosted Opik deployment, network routes from Dify to Opik, separate projects for each business unit, or a review of which trace fields are acceptable to store. Ask any partner for a timeline tied to a written scope with named tasks, and check which of those tasks depend on your change board or security review.
What does our team need to provide before the integration can start?
Expect to provide an Opik account or workspace owner, access to the Dify console with an admin role for each app to be traced, and a network path from the Dify api service to the Opik endpoint. If Opik is self-hosted, you also need the hosting environment, TLS certificates and the Opik project credentials handled under your secrets policy. A data owner should sign off on which prompts, outputs and user inputs may appear in traces, because trace content is the main compliance question. Network approvals for outbound calls from Dify should go through the same egress review you use for other services.
Can our own team connect Dify to Opik without outside help?
Yes, a team with Dify administration experience and someone who can run Opik can complete the basic connection using the Dify integration documentation. The harder parts are the ones that are easy to skip: scoping credentials to a single project, deciding what trace data may leave a given app, testing that traces appear with the expected fields, and writing down how the setup survives Dify and Opik upgrades. Outside help is most useful when you need those decisions documented for an audit or when several environments must match. Whichever route you take, agree on acceptance checks before starting.
Can Dify traces stay entirely inside our network?
Traces can stay inside your network when both Dify and Opik run in infrastructure you control and the Dify api service can reach the self-hosted Opik endpoint without leaving that network. Using Comet's hosted service means trace data is sent to a third-party service, which may not meet your data residency rules. Confirm where Comet stores data and what it does with it before choosing that path. Inside your own network, also review the outbound request controls on Dify, since the SSRF proxy blocks internal and private IP ranges by default and the Opik address may need an explicit allowance. Your security team should test that the route works and that nothing unexpected leaves the network.
How do Dify or Opik upgrades affect the tracing setup?
Each upgrade can change the Dify environment settings, the Opik server version or the way traces are exported, so the setup needs a re-test after every change. Dify recommends a backup before every upgrade and checking the example environment file for new variables. Dify minor releases have arrived roughly monthly, so plan a recurring check rather than treating tracing as a one-time task. For Opik, confirm the compatibility of the server version with the Dify release you run, and keep a rollback plan. A retainer or an operations runbook can cover this recurring work, and a quote should state whether upgrade testing is included.
When is Opik a better choice than Langfuse for Dify tracing?
Choose Opik when your team already uses Comet or Opik for evaluation and monitoring, or when you want one tool for testing, evaluation and tracing of LLM applications, which is how Dify describes Opik. Choose Langfuse when you want a self-hosted tracing and prompt management service that your team already runs or prefers. Both can be self-hosted, so the decision usually rests on existing tooling, the evaluation features you need and staff familiarity. Compare the trace fields each integration exports against the reporting your audit or operations team requires before deciding.
Keeping Opik tracing working through Dify upgrades
Treat the Opik connection as part of the Dify upgrade scope, not as something that survives upgrades by default. Dify minor releases arrive roughly monthly, according to the Dify releases page, so a team running a traced app will face this check often. Before each upgrade, take a backup of the Dify database and storage, as the Docker Compose docs recommend. Then follow the upgrade guide for the target version, and after the upgrade compare the .env.example file in the new release with your .env file to find new or renamed variables. Do not assume that the tracing settings you saved in the Dify console will still behave the same way on the new version.
Re-test a trace after every upgrade, even when nothing in the tracing configuration changed. Send one test message through a traced app, then confirm in Opik that the trace arrived in the expected project, that the node structure and token counts look as they did before the upgrade, and that no errors appear in the Dify worker logs. Keep a short written record of the Dify version, the Opik version and the test result. This gives you a baseline to compare against when a later upgrade changes how fields are exported. Confirm with your Opik deployment or Comet's documentation which Opik version your team has validated against, since the Dify integration docs do not establish a compatibility matrix.
Pin the Opik version you test against and treat it as a controlled dependency. If you run a self-hosted Opik server, record its image tag and move it only through a change request that includes a trace re-test. The same applies to the Opik endpoint URL and the project API key stored in Dify: put them under change control, record who holds the key, and rotate it through the same process when staff change. A changed endpoint or a revoked key can make traces silently stop arriving, which is easy to miss when Dify itself looks healthy. Agree in advance who checks Opik after an upgrade, and what happens if the test trace does not appear.
How DeployOpen scopes and delivers Dify and Opik tracing
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including Dify tracing into Opik. We start from a written scope that states which Opik deployment model, which Dify apps and which trace fields are in play, then build and hand over the configuration with the evidence your team needs to run it.
How we scope
- Confirm whether Opik runs as a self-hosted server in your network or as Comet's hosted service, and record the choice in the written scope.
- List the Dify apps, workflows and chatflows to be traced, and whether each one is in your workspace or a separate instance.
- Agree which trace data may leave your environment, and document how prompt content and user input are handled before any tracing is enabled.
How we build
- Create the Opik workspace and project, then configure Dify tracing per app with the project endpoint and key handled as secrets.
- Verify that exported trace fields, such as token counts and node executions, appear as expected in Opik for representative test runs.
- Confirm outbound network paths from Dify to the Opik endpoint, including any SSRF proxy rules, and test them in a staging environment first.
How we hand over
- Deliver a written configuration record covering the Opik deployment model, project structure, key ownership and rotation steps.
- Provide a runbook for adding new Dify apps to tracing and for disabling tracing for apps that handle sensitive data.
- Walk your operators through trace review, retention settings in Opik, and the checks to run after each Dify upgrade.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer, including re-verification of trace fields after Dify releases.
- Ask for the written scope to name the Dify version, Opik version and hosting model, so changes are tracked against a known baseline.
