Dify (tracing)

Dify  exposes chat, completion, workflow, conversation, file, Knowledge Base, and Workspace operations through its Service API clients. Respan’s Dify instrumentation observes those client requests and converts them into canonical chat, text, workflow, or task spans without changing where the Dify request is sent.

Paste this into your coding agent:

Help me set up Respan tracing with the Dify integration.
Follow https://www.respan.ai/docs/integrations/dify.md

Availability

This integration is explicit-only. Add DifyInstrumentor to Respan; Dify is not enabled as a zero-configuration leaf-model integration.

Python setup

pip install respan-ai respan-instrumentation-dify "dify-client>=0.1.10,<0.2.0"

git clone https://github.com/respanai/respan.git

python -m pip install \
  "dify-client @ git+https://github.com/langgenius/dify-python-sdk.git@a3ce501021906e23535c268f0b60fea3864864a6" \
  -e ./respan/python-sdks/respan-sdk \
  -e ./respan/python-sdks/respan-tracing \
  -e ./respan/python-sdks/respan \
  -e ./respan/python-sdks/instrumentations/respan-instrumentation-dify

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export DIFY_CHAT_API_KEY="YOUR_DIFY_CHAT_APP_KEY"

# Optional for self-hosted Dify or a test endpoint; this must remain a Dify URL.
export DIFY_BASE_URL="https://api.dify.ai/v1"

import os

from dify_client import ChatClient
from respan import Respan
from respan_instrumentation_dify import DifyInstrumentor

respan = Respan(
    api_key=os.environ["RESPAN_API_KEY"],
    instrumentations=[DifyInstrumentor()],
)

base_url = os.getenv("DIFY_BASE_URL")
try:
    client = ChatClient(
        api_key=os.environ["DIFY_CHAT_API_KEY"],
        **({"base_url": base_url} if base_url else {}),
    )
except TypeError:
    # Released dify-client 0.1.10 accepts only api_key; set its mutable URL.
    client = ChatClient(os.environ["DIFY_CHAT_API_KEY"])
    if base_url:
        client.base_url = base_url.rstrip("/")

try:
    response = client.create_chat_message(
        inputs={},
        query="Summarize tracing in one sentence.",
        user="respan-user",
        response_mode="blocking",
    )
    response.raise_for_status()
    print(response.json()["answer"])
finally:
    respan.flush()
    respan.shutdown()

JavaScript setup

npm install @respan/respan @respan/instrumentation-dify@0.1.0 dify-client@3.1.0

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export DIFY_CHAT_API_KEY="YOUR_DIFY_CHAT_APP_KEY"

# Optional for self-hosted Dify; this must remain a Dify URL.
export DIFY_BASE_URL="https://api.dify.ai/v1"

import { ChatClient } from "dify-client";
import { Respan } from "@respan/respan";
import { DifyInstrumentor } from "@respan/instrumentation-dify";

const respanApiKey = process.env.RESPAN_API_KEY;
const difyApiKey = process.env.DIFY_CHAT_API_KEY;
if (!respanApiKey || !difyApiKey) {
  throw new Error("RESPAN_API_KEY and DIFY_CHAT_API_KEY are required");
}

const respan = new Respan({
  apiKey: respanApiKey,
  instrumentations: [new DifyInstrumentor()],
});
await respan.initialize();

const client = new ChatClient({
  apiKey: difyApiKey,
  baseUrl: process.env.DIFY_BASE_URL,
});

try {
  const response = await client.createChatMessage({
    inputs: {},
    query: "Summarize tracing in one sentence.",
    user: "respan-user",
    response_mode: "blocking",
  });
  if (Symbol.asyncIterator in response) {
    throw new Error("Expected a blocking response");
  }
  console.log(response.data?.answer);
} finally {
  await respan.shutdown();
}

Confirmed API coverage

Both implementations patch the official client’s shared HTTP boundary, so a high-level SDK method and its underlying request produce one Dify span rather than duplicates.

The runnable Python suite also covers propagated Respan context and async chat/workflow behavior when the installed Dify source exposes async clients. The JavaScript / TypeScript suite covers blocking and SSE chat, completion, workflow, Knowledge Base/Workspace, multipart upload, and a controlled HTTP error.

Streaming and async behavior

The lifecycle behavior in this section describes the refreshed Python source and the published JavaScript / TypeScript 0.1.0 package. The refreshed Python behavior remains pending its corresponding release.

A streaming span stays open until the returned stream is exhausted, closed early, leaves its context manager, or raises. Consume or close streams explicitly; abandoning a stream without either action cannot produce an exact completion timestamp.

response = client.create_chat_message(
    inputs={},
    query="Stream one sentence.",
    user="respan-user",
    response_mode="streaming",
)

try:
    for line in response.iter_lines():
        if line:
            print(line)
finally:
    response.close()

import os
from dify_client import AsyncChatClient

async with AsyncChatClient(
    os.environ["DIFY_CHAT_API_KEY"],
    base_url=os.getenv("DIFY_BASE_URL", "https://api.dify.ai/v1"),
) as client:
    response = await client.create_chat_message(
        inputs={},
        query="Stream one sentence.",
        user="respan-user",
        response_mode="streaming",
    )
    try:
        async for line in response.aiter_lines():
            if line:
                print(line)
    finally:
        await response.aclose()

const stream = await client.createChatMessage({
  inputs: {},
  query: "Stream one sentence.",
  user: "respan-user",
  response_mode: "streaming",
});
if (!(Symbol.asyncIterator in stream)) throw new Error("Expected a Dify stream");

for await (const event of stream) {
  console.log(event);
}

In JavaScript / TypeScript, consuming the documented AsyncIterable, calling toText(), or consuming data/toReadable() completes the span without replacing the original stream API. Binary streams are also observed. In Python, sync iter_lines/content methods and async aiter_lines/byte/text methods are preserved by response proxies.

If a blocking call throws or a stream fails, the instrumentation records the exception and error status and then preserves the SDK’s normal exception behavior. HTTP error responses retain their status; continue using raise_for_status() in Python or normal try/catch handling in JavaScript / TypeScript.

Content capture and privacy

The options and recursive credential redaction in this section describe the refreshed Python source and the published JavaScript / TypeScript 0.1.0 package. The refreshed Python behavior remains pending its corresponding release.

Content capture is on by default. Disable it when prompts, inputs, outputs, or streamed content must not be exported:

DifyInstrumentor(include_content=False)

new DifyInstrumentor({ includeContent: false })

With content capture disabled, the span still retains the operation, HTTP/error status, correlation fields, and token usage that Dify reports. Credential-like keys are recursively redacted from captured requests and echoed responses even when content capture is enabled, including Workspace credential-validation payloads.

Use respan.propagate_attributes(...) in Python to attach customer, thread, trace-group, prompt, or custom metadata context to Dify spans. Propagated metadata and Dify operation details are merged into the single canonical respan.metadata JSON attribute.

Limitations

• This is client-side Service API tracing. It does not expose Dify server-internal model, retrieval, or workflow-node spans unless Dify returns that information through the client response.
• Respan Gateway has no Dify Service API-compatible route. Do not point DIFY_BASE_URL at https://api.respan.ai/api; keep Dify requests routed to Dify and use this instrumentor for tracing.
• PyPI’s released dify-client 0.1.10 is sync-only. Python async, dedicated Workflow, Knowledge Base, and Workspace clients require the compatible refreshed source API and should be feature-detected by applications.
• Only calls that pass through the patched official Dify client boundary are traced. Direct HTTP calls and unrelated Dify clients are outside this integration.
• When multiple instrumentor instances overlap, the first active instance’s content policy remains in effect until the last one is deactivated.