Dify and Arize Phoenix tracing integration

How Dify Arize Phoenix tracing works for regulated teams

If you run self-hosted Dify and need traces for LLM apps without sending prompts to a SaaS service, the integration works like this: Dify exports traces to a Phoenix project endpoint authenticated with a project key, and Phoenix can be self-hosted on your own infrastructure starting from a single container. The Dify docs describe this as the method for connecting the two, and Phoenix is open source and OpenTelemetry-based, so the trace data can remain inside the network you control. Phoenix can also run as Arize's hosted Phoenix Cloud, which would send prompt data outside your environment, so confirm which deployment your governance rules allow before you copy any endpoint into Dify.

For a regulated team, the decision sits in the Phoenix deployment, not in Dify. Traces carry prompts, model outputs and node inputs, so the Phoenix instance needs the same access control, retention and backup treatment as any other store holding customer or internal data. Plan who can open the Phoenix UI, where its storage lives and how long traces are kept. Dify itself also runs with its own SECRET_KEY, outbound SSRF filtering and workspace encryption, and those controls do not extend to Phoenix, so review the Phoenix side separately.

Before rollout, confirm the exact trace fields, span hierarchy and node-level behavior against the Dify version you run and the Phoenix version you deploy, since both projects change frequently. The Dify Phoenix integration guide is the natural starting point for the endpoint and key format. Test with a non-production app first, check that the spans you need appear, and record which fields are missing so your team can decide whether prompt content or token counts must be handled another way.

What you need before connecting Dify to Phoenix

Tracing from Dify into Phoenix depends on three things lining up: a Dify deployment that meets its baseline, a Phoenix instance your team can reach, and network paths that let Dify's own containers send spans out. Work through the cards in order before you open the app tracing settings, because most failed first connections trace back to one of these items.

Dify deployment baseline

The Docker Compose deployment needs at least 2 CPU cores, 4 GB of RAM and Docker Compose 2.24.0 or later. The stack starts the api, worker, web and plugin daemon services along with PostgreSQL, Redis, Weaviate, Nginx, a code sandbox and an SSRF proxy. Tracing adds little load on its own, but the host must already be sized for the workflows you plan to trace. Confirm the Dify release you run before you begin, since minor releases arrive roughly monthly and settings can change between them.

Phoenix hosting choice

Decide whether Phoenix runs in your own network or as Arize's hosted Phoenix Cloud. Dify's docs describe Phoenix as open source and OpenTelemetry-based, able to run locally, on your own infrastructure from a single container, or as Phoenix Cloud. Only the self-hosted option keeps prompts, completions and node inputs inside your network. Confirm the Phoenix version and deployment method with your Phoenix documentation before you install it.

Project endpoint and API key

Dify needs the Phoenix endpoint and credentials for the project that receives its traces. Create a dedicated Phoenix project for each Dify environment so staging and production spans stay apart. Store the API key in your secrets manager and enter it only in the Dify tracing settings for the app. Ask your Phoenix administrator who can rotate the key and how revocation is logged.

Network routes from Dify containers

The api and worker containers send the traces, not your browser, so the route must exist from those containers to Phoenix. Test the path from inside the containers, for example with a request to the Phoenix endpoint, rather than from your laptop. Check DNS resolution, firewall rules and any TLS certificate chain that the containers must trust. If Dify runs on one network segment and Phoenix on another, confirm the rule in both directions before you blame the integration.

SSRF proxy allowlisting

Dify's SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges. If Phoenix sits on an internal host, the request may be blocked before it leaves Dify. Review the proxy rules with your network team and allow only the Phoenix host and port you intend to use. Keep this change narrow and record it, because widening the proxy affects every outbound call Dify makes.

Release and configuration check

Before you change any variable, confirm the Dify release, read its upgrade notes, and check .env.example for variables added since your last upgrade. Back up the environment file and the database first, since the Compose docs advise a backup before every upgrade. Changing SECRET_KEY after deployment logs out all users, so do not touch it while setting up tracing. Record the release, the Phoenix version and the endpoint in your change ticket.

How to configure Dify tracing to a Phoenix project

This sequence connects one Dify app to a Phoenix project you control, then proves with a test run that workflow and node spans arrive with token data intact.

Confirm the Phoenix instance is reachable
Your platform or observability team confirms a Phoenix instance is running inside your network, either as a single container or as part of a larger deployment you operate. Phoenix is open source and OpenTelemetry-based, so the instance needs to be reachable from the Dify api and worker services, not only from a browser. Confirm the base address that Dify will call, the protocol, and any certificate chain your internal authority issued. Done means someone outside the Dify host can open the Phoenix interface, and the Dify containers can open a connection to the same address.
Create the Phoenix project and access key
In the Phoenix interface, create a project that will hold traces from this Dify app or workspace, and generate the credential Dify will use to send data. Name the project so that a reviewer can tell which environment and which Dify app it belongs to, for example a separate project for staging and production. Store the key in your secrets manager, not in a shared document. Done means the project exists, is empty, and you have the endpoint, project identifier and key ready for the next step.
Check network path from Dify to Phoenix
Before you change any Dify setting, confirm that the containers that export traces can reach the Phoenix endpoint. Check outbound rules, the Docker network the Dify services share, and any proxy in the path. If your Dify deployment routes outbound requests through the SSRF proxy, confirm that the Phoenix address is allowed and that the proxy does not block a private address range your internal Phoenix uses. Done means a connection test from the Dify api container succeeds with the same address you plan to configure.
Enter the endpoint and key in app tracing settings
In the Dify console, open the app you want to trace, go to its monitoring or tracing settings, and select the Phoenix provider. Enter the endpoint and the project key from the previous step, and keep the field names and any project identifier exactly as the Dify Phoenix integration guide describes for your version. Save the configuration for this app only. Confirm the field names against the guide, because Dify versions can change labels. Done means the Phoenix provider shows as enabled for this app and the saved values match what you generated in Phoenix.
Run a test workflow with known input
Run the app once with a short, fixed input that you can recognize in the trace, such as a test phrase that has no customer data. Use a workflow or chatflow that includes at least one LLM node and one knowledge retrieval or tool node, so that more than one span type is produced. Record the run output and the token counts shown in the Dify run log. Done means the run completes in Dify and you have a written record of its input, output and token counts to compare against Phoenix.
Confirm the trace appears in the Phoenix project
Open the Phoenix project you created and find the trace from the test run. Check that the trace has one parent span for the app run and child spans for each node that executed, in the same order as the Dify run log. Confirm that the LLM span shows the prompt and completion you expected, and that the input and output match the test you recorded. Done means the trace is visible in the correct project, every executed node has a span, and nothing from the test run is missing.
Match token counts and retain prompt data deliberately
Compare the token counts on the LLM spans in Phoenix with the counts in the Dify run log. Differences can come from how each side counts or from a node that was skipped, so investigate before you accept the integration. Then decide, with your privacy and security owners, how long Phoenix keeps prompts and completions and who can open those traces. Done means the token counts agree or the difference is explained, and the retention and access decision is written down for the Phoenix project.

Which Dify trace data appears in Phoenix and where it stays

This table maps the Dify objects that Phoenix receives (app, workflow, node and message data) to the trace structures Phoenix displays, and shows whether each data type leaves your network. Use it as a checklist to confirm field names and data paths on the exact Dify and Phoenix versions you run, because the mapping is the part most likely to change between releases.

Dify data	Where it appears in Phoenix	Leaves your network?	Verify before go-live
App and project identity	Project associated with the Dify app's tracing configuration	No, if Phoenix runs in your network	Confirm which app maps to which Phoenix project name on your version
Workflow and chatflow runs	Parent trace per run, grouping the node executions beneath it	No, if Phoenix runs in your network	Check whether chatflow and workflow runs produce the same trace shape
Node executions	Child spans, one per node, with start and end times and status	No, if Phoenix runs in your network	Confirm the span names and node types exported by your Dify release
Prompts and model inputs	Input attributes on LLM spans	Only if Phoenix or Dify sends them to an external endpoint	Test with a non-sensitive prompt and inspect where the data is stored
Model outputs and message content	Output attributes on LLM and message spans	Only if Phoenix or Dify sends them to an external endpoint	Confirm whether message content is exported in full or truncated
Token counts and model parameters	Usage attributes on LLM spans	No, if Phoenix runs in your network	Verify the attribute names used for prompt, completion and total tokens
Knowledge retrieval and tool calls	Retriever or tool spans, depending on the node type	Depends on the retrieval or tool endpoint, not Phoenix	Check whether retrieved chunks are exported and where those services run

Self-hosted Phoenix or Phoenix Cloud for prompt data

Running Phoenix in the same network as Dify keeps trace payloads on infrastructure your team controls. Dify exports spans to the endpoint you configure, so the path from the Dify api and worker services to Phoenix can stay on your internal network, and Phoenix writes those spans to storage you choose. Your team owns the container, the storage, access to the Phoenix interface and the retention rules.

Data boundary: Prompts, completions and node inputs and outputs attached to spans stay on hosts you run, provided the endpoint is internal.
Operations: Your platform team patches the Phoenix container, sizes its storage and backs it up separately from Dify's own backups.
Network path: Confirm whether the export path passes through Dify's SSRF proxy, since that proxy blocks internal and private IP ranges, and open only the routes you need.
Retention and access: Set retention in Phoenix and in the storage beneath it, and document who can view, export or delete traces.
Requirements: Container hosting, persistent storage, TLS and authentication for the interface, and an owner for the trace store.

Confirm the deployment mode, storage backend and authentication options against the Dify Phoenix integration guide and Phoenix's own documentation for your version.

Protecting prompt data and the Phoenix key

Traces from Dify carry prompts, model outputs and retrieved content, so the Phoenix project key and the trace data deserve the same care as the application itself. The cards below cover where the key lives, who can read traces, how long they are kept and which Dify apps are allowed to send them.

Treat the project key as a secret

The Phoenix key is entered in the Dify app's tracing settings, and Dify stores it as an encrypted credential. That encryption depends on SECRET_KEY, which also signs session cookies and JWTs and encrypts OAuth credentials. Changing SECRET_KEY after deployment logs out all users, so set it once, back it up in your secrets manager, and rotate the Phoenix key separately by replacing it in each app's tracing settings and revoking the old one in Phoenix.

Limit who can read traces

Trace views expose full prompts, retrieved passages and model responses, which can be more sensitive than the app's own output. Confirm how your Phoenix deployment handles user accounts and project-level access, keep the Phoenix UI off public networks, and grant read access by project to the people who debug these apps. Treat Dify console access and Phoenix access as separate permissions that someone must review together.

Set retention for trace data

Trace data persists in Phoenix until you remove it, so retention is a decision you own. Ask your Phoenix operator which retention controls the version you run provides, whether deletion is per project or global, and whether backups of the Phoenix store follow the same schedule. Write the chosen period into your data handling record so trace data does not outlive the business reason for keeping it.

Plan around the SSRF proxy allowlist

Dify routes outbound requests through the SSRF proxy configured with SSRF_PROXY settings, which blocks internal and private IP ranges. A self-hosted Phoenix on an internal host will therefore be unreachable from Dify unless you deliberately allow that destination. Confirm the exact proxy behavior for your Dify version, then add only the Phoenix host and port to the allowlist, and avoid widening the proxy to whole private subnets.

Scope which apps send traces

Tracing is configured per app, so an app that handles regulated data should only send traces once someone has reviewed what its prompts and retrieved content contain. Keep a list of traced apps, record who approved each one, and disable tracing in apps that are retired or moved to a different data class. Review the list whenever you add a new app or change its knowledge base sources.

Why Dify traces do not show up in Phoenix

This table lists the failures that most often leave Dify traces missing from Arize Phoenix, with the likely cause and the fix for each. Work through the rows in order, since the first two checks (endpoint and key, then network path) rule out most cases before you look at app settings or versions. Confirm the exact configuration fields and version pairing against the Dify Phoenix integration page before changing production settings.

Symptom or cause	Likely cause	Fix and what to confirm
Wrong endpoint or project key	The Phoenix endpoint URL, project name or API key was copied from a different Phoenix instance, or includes a stray path or whitespace.	Re-copy the endpoint and key from the Phoenix instance you run. Confirm the URL format and key field names in the Dify Phoenix integration docs.
Network path blocked	Dify's outbound requests to the Phoenix host are stopped by a firewall rule, a DNS name that does not resolve from the Dify containers, or the SSRF proxy blocking private IP ranges.	Test reachability from the Dify api container, not the host shell. If Phoenix sits on a private address, confirm how SSRF_PROXY handles that destination and add an approved route or allowlist entry.
Tracing not enabled on the app	Tracing was configured in the workspace but switched off for the specific app, or was set up on a different app than the one generating traffic.	Open the app's monitoring settings, enable the Phoenix provider there, and send a fresh test run. Traces from runs before the change will not appear.
Version mismatch	The Dify release and the Phoenix collector or client expectations differ, so spans are accepted but not displayed, or are dropped.	Record the Dify version from the releases page and the Phoenix version you run. Check the integration docs for supported pairings before upgrading either side, and upgrade one component at a time.
Missing spans for some node types	Not every node type emits the same spans, so a workflow can show a trace with gaps, or a node you expected is absent from the tree.	Compare a test run against the node types the Dify docs list as traced. Treat absent node types as a product behavior to confirm with the vendor docs, not as a Phoenix display fault.
Traces visible but prompt data missing	Input or output fields were limited or redacted in the tracing configuration, or the run used a model call type that does not export them.	Review what the integration exports in the Dify docs. Decide with your security team which fields may leave the workflow before you enable full capture.
Data appears in Phoenix but not in your project	The project name in Dify does not match the Phoenix project where you are looking.	Check the project name field in the Dify configuration against the project list in Phoenix, and filter by time range to catch recent runs.

Questions teams ask before connecting Dify to Phoenix

How much effort does connecting Dify to Phoenix take?

The effort depends mostly on four things: the network path between your Dify instance and Phoenix, whether Phoenix is self-hosted or used as Phoenix Cloud, how many apps need tracing, and how far you verify. Dify's Phoenix integration is configured per app with a project endpoint and key, so a handful of apps on a reachable Phoenix host is a small change. The larger cost usually comes from network approvals, firewall rules, and checking that node-level spans show what your team needs. Ask any partner to price these four drivers separately in a written scope, and ask which of them are assumed to be already in place.

Can our team connect Dify to Phoenix without outside help?

Often yes, for a single test workspace with a reachable Phoenix instance. The configuration itself is a project endpoint and key entered per app, and Dify's own documentation for the Phoenix integration covers those steps. Teams usually bring in help when the Phoenix host sits in a restricted network segment, when many apps need consistent settings, or when they need evidence that prompt data stays in infrastructure they control. Check whether your engineers have time to test trace fields across workflows and chatflows, since that verification is where most gaps appear.

What do we need to provide before the work starts?

You need three things in place. First, Dify admin access to the workspace and the apps to be traced, so the integration can be set per app. Second, a Phoenix host you operate, or a decision to use Phoenix Cloud, along with network paths from Dify to that host. Third, a named owner on your side who can approve network changes, hold the project key, and accept the test results. Without that owner, decisions about key rotation and trace retention tend to stall. Confirm access levels and change windows with your own security team before scheduling anything.

How long does a Phoenix tracing integration take?

No duration was researched for this integration, so treat any number you hear as unverified until it is tied to a written scope. The schedule is driven by the number of apps, whether the Phoenix host already exists, how long network and security approvals take in your organization, and how many test cases you want covered before go-live. A narrow scope covering one or two apps on an existing Phoenix host is a different job from tracing a full app portfolio across several environments. Ask for the timeline to list each phase and the approvals it assumes.

Can Phoenix keep prompt data inside our own network?

Yes, Dify's documentation describes Phoenix as open source and able to run on your own infrastructure, starting with a single container. When you self-host Phoenix, trace data, including prompts and node-level content, is stored on a host you control rather than in a vendor's hosted service. Two points need checking in your design. Confirm which trace fields Dify sends for each app, since sensitive inputs can appear in them. Also confirm where the Phoenix storage volume sits, who can read it, and how long traces are kept. Phoenix Cloud is a different data path and should be assessed separately.

Will upgrading Dify or Phoenix break our tracing?

It can, so treat tracing as part of each upgrade test. Dify ships minor releases roughly monthly, based on the GitHub releases history, and Dify's Docker Compose guidance says to back up before every upgrade and check the example environment file for new variables after upgrading. Phoenix versions can change span handling or endpoints independently of Dify. After any upgrade of either product, send a test workflow and a chatflow through to Phoenix and confirm the spans, token counts and node details still appear. Keep the Phoenix project key and endpoint documented so a rollback is quick.

What should we verify after tracing is switched on?

Verify the path, the content and the access. Path: confirm that every traced app reaches the Phoenix endpoint and that the project key works from the Dify containers, not only from a workstation. Content: run a chat, a workflow with several nodes, and a failing node, then check that node-level spans and errors arrive as your team expects. Access: confirm who can view prompts in Phoenix, that keys are stored and rotated under your normal secrets process, and that outbound traffic follows your proxy and allowlist rules. Record the results so an auditor or security reviewer can see what was tested.

How DeployOpen scopes and delivers Dify tracing with Phoenix

DeployOpen plans and builds the Dify to Arize Phoenix trace path inside your own infrastructure, so prompt data stays where your controls apply. Engagements are fixed-scope, with the endpoint, key handling, span review and handover agreed in writing before work starts.

How we scope

We confirm which Dify apps and workspaces will send traces and which Phoenix deployment, self-hosted or hosted, your policy allows.
We record the Phoenix project endpoint, key ownership, and the node level spans your reviewers need to see in the written scope.
We agree in writing what prompt, output and token data may leave the Dify host, and which fields stay out of the trace.

How we build

We configure tracing per app in Dify, using the Phoenix endpoint and project key held in your secrets store rather than in shared notes.
We run test workflows and chatflows, then check that each node execution, model call and token count appears in the expected Phoenix project.
We confirm outbound traffic from the Dify host reaches only the approved Phoenix address, with the SSRF proxy settings reviewed against that path.

How we hand over

We deliver a runbook covering endpoint and key rotation, the app level tracing settings, and the trace fields your teams should expect.
We document which data categories are traced, where they are stored, who can read them, and how long your Phoenix instance retains them.
We walk your platform and security staff through a test trace review so they can reproduce the checks without DeployOpen present.

How we support

Ongoing support, upgrades and testing are available as a retainer, covering Dify release changes that could affect tracing behavior.
Dify minor releases arrive roughly monthly, so we can review each upgrade for tracing regressions before your production apps move.
Support scope, response expectations and review cadence are set in the written agreement, so you know what is covered before you sign.