respan-instrumentation-dify 0.1.0__tar.gz

respan_instrumentation_dify-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: respan-instrumentation-dify
+Version: 0.1.0
+Summary: Respan instrumentation plugin for Dify
+License: Apache 2.0
+Author: Respan
+Author-email: team@respan.ai
+Requires-Python: >=3.11,<3.14
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: dify-client (>=0.1.10)
+Requires-Dist: opentelemetry-semantic-conventions-ai (>=0.4.1)
+Requires-Dist: respan-sdk (>=2.6.1)
+Requires-Dist: respan-tracing (>=2.17.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Respan Dify instrumentation
+
+Trace the `dify-client` Python package with Respan.
+
+This package patches Dify's Service API client methods and emits canonical
+Respan spans for chat, completion, workflow, file, feedback, application, and
+conversation requests. Streaming responses are traced when the returned stream
+is consumed.
+
+## Install
+
+```bash
+pip install respan-ai respan-instrumentation-dify dify-client
+```
+
+## Usage
+
+```python
+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()],
+)
+
+client = ChatClient(os.environ["DIFY_CHAT_API_KEY"])
+response = client.create_chat_message(
+    inputs={},
+    query="Reply with one concise sentence about tracing.",
+    user="respan-example-user",
+    response_mode="blocking",
+)
+response.raise_for_status()
+print(response.json()["answer"])
+
+respan.flush()
+respan.shutdown()
+```
+
+Use `Respan.propagate_attributes(...)` to attach customer, thread, trace group,
+metadata, or prompt context to Dify spans.
+

respan_instrumentation_dify-0.1.0/README.md

@@ -0,0 +1,45 @@
+# Respan Dify instrumentation
+
+Trace the `dify-client` Python package with Respan.
+
+This package patches Dify's Service API client methods and emits canonical
+Respan spans for chat, completion, workflow, file, feedback, application, and
+conversation requests. Streaming responses are traced when the returned stream
+is consumed.
+
+## Install
+
+```bash
+pip install respan-ai respan-instrumentation-dify dify-client
+```
+
+## Usage
+
+```python
+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()],
+)
+
+client = ChatClient(os.environ["DIFY_CHAT_API_KEY"])
+response = client.create_chat_message(
+    inputs={},
+    query="Reply with one concise sentence about tracing.",
+    user="respan-example-user",
+    response_mode="blocking",
+)
+response.raise_for_status()
+print(response.json()["answer"])
+
+respan.flush()
+respan.shutdown()
+```
+
+Use `Respan.propagate_attributes(...)` to attach customer, thread, trace group,
+metadata, or prompt context to Dify spans.

respan_instrumentation_dify-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[tool.poetry]
+name = "respan-instrumentation-dify"
+version = "0.1.0"
+description = "Respan instrumentation plugin for Dify"
+authors = ["Respan <team@respan.ai>"]
+license = "Apache 2.0"
+readme = "README.md"
+packages = [
+    { include = "respan_instrumentation_dify", from = "./src" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<3.14"
+respan-tracing = "^2.17.0"
+respan-sdk = ">=2.6.1"
+dify-client = ">=0.1.10"
+opentelemetry-semantic-conventions-ai = ">=0.4.1"
+
+[tool.poetry.plugins."respan.instrumentations"]
+dify = "respan_instrumentation_dify:DifyInstrumentor"
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: live network tests (requires API keys)",
+]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

respan_instrumentation_dify-0.1.0/src/respan_instrumentation_dify/__init__.py

@@ -0,0 +1,7 @@
+"""Respan instrumentation for the Dify Python client."""
+
+from respan_instrumentation_dify._instrumentation import DifyInstrumentor
+
+DifyAIInstrumentor = DifyInstrumentor
+
+__all__ = ["DifyInstrumentor", "DifyAIInstrumentor"]

respan_instrumentation_dify-0.1.0/src/respan_instrumentation_dify/_constants.py

@@ -0,0 +1,68 @@
+"""Dify instrumentation constants."""
+
+from respan_sdk.constants.span_attributes import (
+    RESPAN_SPAN_HANDOFFS,
+    RESPAN_SPAN_TOOL_CALLS,
+    RESPAN_SPAN_TOOLS,
+)
+
+DIFY_INSTRUMENTATION_NAME = "dify"
+DIFY_CLIENT_MODULE = "dify_client.client"
+DIFY_CHAT_SPAN_NAME = "dify.chat"
+DIFY_COMPLETION_SPAN_NAME = "dify.completion"
+DIFY_WORKFLOW_SPAN_NAME = "dify.workflow"
+DIFY_API_SPAN_NAME = "dify.request"
+
+ANSWER_KEY = "answer"
+CONVERSATION_ID_KEY = "conversation_id"
+CREATED_AT_KEY = "created_at"
+DATA_KEY = "data"
+ENDPOINT_KEY = "endpoint"
+EVENT_KEY = "event"
+FILES_KEY = "files"
+ID_KEY = "id"
+INPUTS_KEY = "inputs"
+LATENCY_KEY = "latency"
+MESSAGE_ID_KEY = "message_id"
+METADATA_KEY = "metadata"
+METHOD_KEY = "method"
+MODE_KEY = "mode"
+PARAMS_KEY = "params"
+QUERY_KEY = "query"
+RESPONSE_MODE_KEY = "response_mode"
+STATUS_KEY = "status"
+TASK_ID_KEY = "task_id"
+TOTAL_TOKENS_KEY = "total_tokens"
+USAGE_KEY = "usage"
+USER_KEY = "user"
+WORKFLOW_RUN_ID_KEY = "workflow_run_id"
+
+PROMPT_TOKENS_KEY = "prompt_tokens"
+COMPLETION_TOKENS_KEY = "completion_tokens"
+OUTPUTS_KEY = "outputs"
+ERROR_KEY = "error"
+
+CHAT_MESSAGES_ENDPOINT = "/chat-messages"
+COMPLETION_MESSAGES_ENDPOINT = "/completion-messages"
+WORKFLOW_RUN_ENDPOINT = "/workflows/run"
+FILES_UPLOAD_ENDPOINT = "/files/upload"
+PARAMETERS_ENDPOINT = "/parameters"
+MESSAGES_ENDPOINT = "/messages"
+CONVERSATIONS_ENDPOINT = "/conversations"
+
+STREAMING_RESPONSE_MODE = "streaming"
+
+OFF_CONTRACT_ALIASES = {
+    "completion_tokens",
+    "has_tool_calls",
+    "model",
+    "parallel_tool_calls",
+    "prompt_tokens",
+    RESPAN_SPAN_HANDOFFS,
+    RESPAN_SPAN_TOOL_CALLS,
+    RESPAN_SPAN_TOOLS,
+    "span_tools",
+    "tool_calls",
+    "tools",
+    "total_request_tokens",
+}

respan_instrumentation_dify-0.1.0/src/respan_instrumentation_dify/_context.py

@@ -0,0 +1,51 @@
+"""Package-local context for Dify-specific call options."""
+
+from __future__ import annotations
+
+import contextvars
+from collections.abc import Mapping
+from contextlib import contextmanager
+from typing import Any
+
+
+_RESPAN_PARAMS: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar(
+    "respan_dify_params",
+    default={},
+)
+
+
+def _to_mapping(value: Any) -> Mapping[str, Any] | None:
+    if value is None:
+        return None
+    if isinstance(value, Mapping):
+        return value
+    for method_name in ("model_dump", "dict"):
+        method = getattr(value, method_name, None)
+        if callable(method):
+            try:
+                converted = method()
+            except Exception:
+                continue
+            if isinstance(converted, Mapping):
+                return converted
+    value_dict = getattr(value, "__dict__", None)
+    if isinstance(value_dict, Mapping):
+        return value_dict
+    return None
+
+
+@contextmanager
+def use_respan_params(value: Any):
+    """Temporarily attach optional Respan params to the current Dify call."""
+    mapping = _to_mapping(value) or {}
+    parent = _RESPAN_PARAMS.get()
+    merged = {**parent, **dict(mapping)}
+    token = _RESPAN_PARAMS.set(merged)
+    try:
+        yield
+    finally:
+        _RESPAN_PARAMS.reset(token)
+
+
+def read_respan_params() -> dict[str, Any]:
+    return dict(_RESPAN_PARAMS.get())

respan_instrumentation_dify-0.1.0/src/respan_instrumentation_dify/_instrumentation.py

@@ -0,0 +1,300 @@
+"""Dify SDK instrumentation plugin for Respan."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+from typing import Any
+
+from respan_instrumentation_dify._constants import (
+    DIFY_CLIENT_MODULE,
+    DIFY_INSTRUMENTATION_NAME,
+)
+from respan_instrumentation_dify._context import use_respan_params
+from respan_instrumentation_dify._otel_emitter import capture_call_context
+from respan_instrumentation_dify._otel_emitter import emit_dify_span
+from respan_tracing.core.tracer import RespanTracer
+
+logger = logging.getLogger(__name__)
+
+_PATCHED_METHODS: dict[tuple[type[Any], str], Any] = {}
+_IS_PATCHED = False
+_INCLUDE_CONTENT = True
+
+
+def _arg(args: tuple[Any, ...], index: int, kwargs: dict[str, Any], name: str, default: Any = None) -> Any:
+    if len(args) > index:
+        return args[index]
+    return kwargs.get(name, default)
+
+
+def _pop_respan_params(kwargs: dict[str, Any]) -> Any:
+    return kwargs.pop("respan_params", None)
+
+
+def _parse_sse_event(line: Any) -> Any:
+    if isinstance(line, bytes):
+        text = line.decode("utf-8", errors="replace")
+    else:
+        text = str(line)
+
+    text = text.strip()
+    if not text:
+        return None
+    if text.startswith("data:"):
+        text = text.split("data:", maxsplit=1)[1].strip()
+    if text == "[DONE]":
+        return None
+    try:
+        return json.loads(text)
+    except Exception:
+        return text
+
+
+class _InstrumentedStreamingResponse:
+    def __init__(self, *, response: Any, call_context: Any) -> None:
+        self._response = response
+        self._call_context = call_context
+        self._events: list[Any] = []
+        self._emitted = False
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._response, name)
+
+    def __enter__(self) -> "_InstrumentedStreamingResponse":
+        enter = getattr(self._response, "__enter__", None)
+        if callable(enter):
+            enter()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> Any:
+        if exc is not None:
+            self._emit_once(error=exc if isinstance(exc, Exception) else Exception(str(exc)))
+        else:
+            self._emit_once(error=None)
+        exit_method = getattr(self._response, "__exit__", None)
+        if callable(exit_method):
+            return exit_method(exc_type, exc, tb)
+        return None
+
+    def close(self) -> Any:
+        self._emit_once(error=None)
+        return self._response.close()
+
+    def iter_lines(self, *args: Any, **kwargs: Any) -> Any:
+        try:
+            for line in self._response.iter_lines(*args, **kwargs):
+                event = _parse_sse_event(line)
+                if event is not None:
+                    self._events.append(event)
+                yield line
+        except Exception as exc:
+            self._emit_once(error=exc)
+            raise
+        else:
+            self._emit_once(error=None)
+
+    def iter_content(self, *args: Any, **kwargs: Any) -> Any:
+        chunks: list[Any] = []
+        try:
+            for chunk in self._response.iter_content(*args, **kwargs):
+                chunks.append(chunk)
+                yield chunk
+        except Exception as exc:
+            self._emit_once(error=exc)
+            raise
+        else:
+            if not self._events:
+                self._events.extend(_parse_sse_event(chunk) for chunk in chunks)
+                self._events = [event for event in self._events if event is not None]
+            self._emit_once(error=None)
+
+    def _emit_once(self, *, error: Exception | None) -> None:
+        if self._emitted:
+            return
+        self._emitted = True
+        emit_dify_span(
+            call_context=self._call_context,
+            response=self._response,
+            stream_events=self._events,
+            error=error,
+            include_content=_INCLUDE_CONTENT,
+        )
+
+
+def _wrap_send_request(original: Any) -> Any:
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        respan_params = _pop_respan_params(kwargs=kwargs)
+        with use_respan_params(respan_params):
+            method = _arg(args, 0, kwargs, "method", "")
+            endpoint = _arg(args, 1, kwargs, "endpoint", "")
+            request_json = _arg(args, 2, kwargs, "json")
+            request_params = _arg(args, 3, kwargs, "params")
+            stream = bool(_arg(args, 4, kwargs, "stream", False))
+            call_context = capture_call_context(
+                method=str(method),
+                endpoint=str(endpoint),
+                request_json=request_json,
+                request_params=request_params,
+                stream=stream,
+            )
+            try:
+                response = original(self, *args, **kwargs)
+            except Exception as exc:
+                emit_dify_span(
+                    call_context=call_context,
+                    error=exc,
+                    include_content=_INCLUDE_CONTENT,
+                )
+                raise
+
+            if stream:
+                return _InstrumentedStreamingResponse(
+                    response=response,
+                    call_context=call_context,
+                )
+            emit_dify_span(
+                call_context=call_context,
+                response=response,
+                include_content=_INCLUDE_CONTENT,
+            )
+            return response
+
+    return wrapper
+
+
+def _wrap_send_request_with_files(original: Any) -> Any:
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        respan_params = _pop_respan_params(kwargs=kwargs)
+        with use_respan_params(respan_params):
+            method = _arg(args, 0, kwargs, "method", "")
+            endpoint = _arg(args, 1, kwargs, "endpoint", "")
+            request_data = _arg(args, 2, kwargs, "data")
+            files = _arg(args, 3, kwargs, "files")
+            call_context = capture_call_context(
+                method=str(method),
+                endpoint=str(endpoint),
+                request_data=request_data,
+                files=files,
+            )
+            try:
+                response = original(self, *args, **kwargs)
+            except Exception as exc:
+                emit_dify_span(
+                    call_context=call_context,
+                    error=exc,
+                    include_content=_INCLUDE_CONTENT,
+                )
+                raise
+            emit_dify_span(
+                call_context=call_context,
+                response=response,
+                include_content=_INCLUDE_CONTENT,
+            )
+            return response
+
+    return wrapper
+
+
+def _wrap_high_level_method(original: Any) -> Any:
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        respan_params = _pop_respan_params(kwargs=kwargs)
+        with use_respan_params(respan_params):
+            return original(self, *args, **kwargs)
+
+    return wrapper
+
+
+def _patch_method(cls: type[Any], method_name: str, wrapper_factory: Any) -> None:
+    key = (cls, method_name)
+    if key in _PATCHED_METHODS:
+        return
+    original = getattr(cls, method_name, None)
+    if original is None:
+        return
+    _PATCHED_METHODS[key] = original
+    setattr(cls, method_name, wrapper_factory(original))
+
+
+class DifyInstrumentor:
+    """Respan instrumentor for the Dify Python Service API client."""
+
+    name = DIFY_INSTRUMENTATION_NAME
+
+    def __init__(self, *, include_content: bool = True) -> None:
+        self._include_content = include_content
+        self._is_instrumented = False
+
+    @staticmethod
+    def _is_respan_tracing_enabled() -> bool:
+        tracer = getattr(RespanTracer, "_instance", None)
+        if tracer is None:
+            return True
+        return bool(getattr(tracer, "is_enabled", True))
+
+    def activate(self) -> None:
+        """Monkey-patch the Dify client."""
+        global _IS_PATCHED, _INCLUDE_CONTENT
+        if self._is_instrumented:
+            return
+        if not self._is_respan_tracing_enabled():
+            logger.info("Dify instrumentation skipped because Respan tracing is disabled")
+            return
+
+        try:
+            module = importlib.import_module(DIFY_CLIENT_MODULE)
+            dify_client_cls = getattr(module, "DifyClient")
+            chat_client_cls = getattr(module, "ChatClient")
+            completion_client_cls = getattr(module, "CompletionClient")
+        except (AttributeError, ImportError) as exc:
+            logger.warning(
+                "Failed to activate Dify instrumentation - missing dependency: %s",
+                exc,
+            )
+            return
+
+        _INCLUDE_CONTENT = self._include_content
+
+        if not _IS_PATCHED:
+            _patch_method(dify_client_cls, "_send_request", _wrap_send_request)
+            _patch_method(
+                dify_client_cls,
+                "_send_request_with_files",
+                _wrap_send_request_with_files,
+            )
+            for method_name in (
+                "message_feedback",
+                "get_application_parameters",
+                "file_upload",
+            ):
+                _patch_method(dify_client_cls, method_name, _wrap_high_level_method)
+            for method_name in (
+                "create_chat_message",
+                "get_conversation_messages",
+                "get_conversations",
+                "rename_conversation",
+            ):
+                _patch_method(chat_client_cls, method_name, _wrap_high_level_method)
+            _patch_method(
+                completion_client_cls,
+                "create_completion_message",
+                _wrap_high_level_method,
+            )
+            _IS_PATCHED = True
+
+        self._is_instrumented = True
+        logger.info("Dify instrumentation activated")
+
+    def deactivate(self) -> None:
+        """Restore patched Dify client methods."""
+        global _IS_PATCHED
+        for (cls, method_name), original in list(_PATCHED_METHODS.items()):
+            setattr(cls, method_name, original)
+        _PATCHED_METHODS.clear()
+        _IS_PATCHED = False
+        self._is_instrumented = False
+        logger.info("Dify instrumentation deactivated")
+
+
+DifyAIInstrumentor = DifyInstrumentor

respan_instrumentation_dify-0.1.0/src/respan_instrumentation_dify/_otel_emitter.py

@@ -0,0 +1,124 @@
+"""Build and inject Dify spans into the active Respan OTEL pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import time
+from typing import Any
+
+from opentelemetry import context as context_api
+from opentelemetry import trace
+from opentelemetry.semconv_ai import SpanAttributes
+
+from respan_instrumentation_dify._context import read_respan_params
+from respan_instrumentation_dify._translator import build_dify_span_data
+from respan_sdk.utils.data_processing.id_processing import (
+    format_span_id,
+    format_trace_id,
+)
+from respan_tracing.utils.span_factory import build_readable_span
+from respan_tracing.utils.span_factory import inject_span
+from respan_tracing.utils.span_factory import read_propagated_attributes
+
+
+@dataclass
+class DifyCallContext:
+    method: str
+    endpoint: str
+    request_json: Any = None
+    request_params: Any = None
+    request_data: Any = None
+    files: Any = None
+    stream: bool = False
+    start_time_ns: int = field(default_factory=time.time_ns)
+    trace_id: str | None = None
+    parent_id: str | None = None
+    workflow_name: str | None = None
+    propagated_attributes: dict[str, Any] = field(default_factory=dict)
+    respan_params: dict[str, Any] = field(default_factory=dict)
+
+
+def _current_otel_parent() -> tuple[str | None, str | None]:
+    current_span = trace.get_current_span()
+    try:
+        span_context = current_span.get_span_context()
+    except Exception:
+        return None, None
+
+    trace_id = getattr(span_context, "trace_id", 0)
+    span_id = getattr(span_context, "span_id", 0)
+    if not isinstance(trace_id, int) or not isinstance(span_id, int):
+        return None, None
+    if trace_id == 0 or span_id == 0:
+        return None, None
+    return format_trace_id(trace_id=trace_id), format_span_id(span_id=span_id)
+
+
+def capture_call_context(
+    *,
+    method: str,
+    endpoint: str,
+    request_json: Any = None,
+    request_params: Any = None,
+    request_data: Any = None,
+    files: Any = None,
+    stream: bool = False,
+) -> DifyCallContext:
+    trace_id, parent_id = _current_otel_parent()
+    workflow_name = context_api.get_value(SpanAttributes.TRACELOOP_ENTITY_NAME)
+    return DifyCallContext(
+        method=method,
+        endpoint=endpoint,
+        request_json=request_json,
+        request_params=request_params,
+        request_data=request_data,
+        files=files,
+        stream=stream,
+        trace_id=trace_id,
+        parent_id=parent_id,
+        workflow_name=str(workflow_name) if workflow_name else None,
+        propagated_attributes=read_propagated_attributes(),
+        respan_params=read_respan_params(),
+    )
+
+
+def emit_dify_span(
+    *,
+    call_context: DifyCallContext,
+    response: Any = None,
+    stream_events: list[Any] | None = None,
+    error: Exception | None = None,
+    include_content: bool = True,
+) -> None:
+    span_name, attributes = build_dify_span_data(
+        method=call_context.method,
+        endpoint=call_context.endpoint,
+        request_json=call_context.request_json,
+        request_params=call_context.request_params,
+        request_data=call_context.request_data,
+        files=call_context.files,
+        response=response,
+        stream_events=stream_events,
+        error=error,
+        include_content=include_content,
+        respan_params=call_context.respan_params,
+        propagated_attributes=call_context.propagated_attributes,
+        current_workflow_name=call_context.workflow_name,
+    )
+    status_code = getattr(response, "status_code", 200)
+    if not isinstance(status_code, int):
+        status_code = 200
+    if error is not None:
+        status_code = 500
+    span = build_readable_span(
+        name=span_name,
+        trace_id=call_context.trace_id,
+        parent_id=call_context.parent_id,
+        start_time_ns=call_context.start_time_ns,
+        end_time_ns=time.time_ns(),
+        attributes=attributes,
+        status_code=status_code,
+        error_message=str(error) if error is not None else None,
+        merge_propagated=False,
+    )
+    inject_span(span=span)

respan_instrumentation_dify-0.1.0/src/respan_instrumentation_dify/_translator.py

@@ -0,0 +1,514 @@
+"""Translate Dify client requests and responses into Respan span attributes."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAIAttributes,
+)
+from opentelemetry.semconv_ai import LLMRequestTypeValues
+from opentelemetry.semconv_ai import SpanAttributes
+
+from respan_instrumentation_dify._constants import (
+    ANSWER_KEY,
+    CHAT_MESSAGES_ENDPOINT,
+    COMPLETION_MESSAGES_ENDPOINT,
+    COMPLETION_TOKENS_KEY,
+    CONVERSATION_ID_KEY,
+    DATA_KEY,
+    DIFY_API_SPAN_NAME,
+    DIFY_CHAT_SPAN_NAME,
+    DIFY_COMPLETION_SPAN_NAME,
+    DIFY_WORKFLOW_SPAN_NAME,
+    ENDPOINT_KEY,
+    ERROR_KEY,
+    EVENT_KEY,
+    FILES_KEY,
+    ID_KEY,
+    INPUTS_KEY,
+    LATENCY_KEY,
+    MESSAGE_ID_KEY,
+    METADATA_KEY,
+    METHOD_KEY,
+    MODE_KEY,
+    OFF_CONTRACT_ALIASES,
+    OUTPUTS_KEY,
+    PARAMS_KEY,
+    PROMPT_TOKENS_KEY,
+    QUERY_KEY,
+    RESPONSE_MODE_KEY,
+    STATUS_KEY,
+    TASK_ID_KEY,
+    TOTAL_TOKENS_KEY,
+    USAGE_KEY,
+    USER_KEY,
+    WORKFLOW_RUN_ID_KEY,
+)
+from respan_sdk.constants.llm_logging import LOG_TYPE_CHAT
+from respan_sdk.constants.llm_logging import LOG_TYPE_TASK
+from respan_sdk.constants.llm_logging import LOG_TYPE_TEXT
+from respan_sdk.constants.llm_logging import LOG_TYPE_WORKFLOW
+from respan_sdk.constants.llm_logging import LogMethodChoices
+from respan_sdk.constants.span_attributes import (
+    RESPAN_CUSTOMER_PARAMS_ID,
+    RESPAN_LOG_METHOD,
+    RESPAN_LOG_TYPE,
+    RESPAN_METADATA,
+    RESPAN_SPAN_ATTRIBUTES_MAP,
+    RESPAN_THREADS_ID,
+    RESPAN_TRACE_GROUP_ID,
+)
+from respan_sdk.utils.serialization import serialize_value
+
+
+def safe_json(value: Any) -> str:
+    """Serialize arbitrary Dify values into an OTEL-safe JSON string."""
+    try:
+        return json.dumps(
+            serialize_value(value=value),
+            default=str,
+            separators=(",", ":"),
+        )
+    except Exception:
+        return json.dumps(str(value), separators=(",", ":"))
+
+
+def _to_mapping(value: Any) -> Mapping[str, Any] | None:
+    if isinstance(value, Mapping):
+        return value
+    for method_name in ("model_dump", "to_dict", "dict", "json"):
+        method = getattr(value, method_name, None)
+        if not callable(method):
+            continue
+        try:
+            converted = method()
+        except Exception:
+            continue
+        if isinstance(converted, Mapping):
+            return converted
+        if isinstance(converted, str):
+            try:
+                parsed = json.loads(converted)
+            except Exception:
+                continue
+            if isinstance(parsed, Mapping):
+                return parsed
+    value_dict = getattr(value, "__dict__", None)
+    if isinstance(value_dict, Mapping):
+        return value_dict
+    return None
+
+
+def _get(value: Any, key: str, default: Any = None) -> Any:
+    mapping = _to_mapping(value)
+    if mapping is not None:
+        return mapping.get(key, default)
+    return getattr(value, key, default)
+
+
+def _status_code(response: Any) -> int:
+    status_code = getattr(response, "status_code", 200)
+    if isinstance(status_code, int):
+        return status_code
+    return 200
+
+
+def _response_json(response: Any) -> Mapping[str, Any]:
+    if response is None:
+        return {}
+    json_method = getattr(response, "json", None)
+    if callable(json_method):
+        try:
+            value = json_method()
+        except Exception:
+            return {}
+        mapping = _to_mapping(value)
+        return mapping or {}
+    mapping = _to_mapping(response)
+    return mapping or {}
+
+
+def _endpoint_kind(endpoint: str) -> str:
+    if endpoint == CHAT_MESSAGES_ENDPOINT:
+        return "chat"
+    if endpoint == COMPLETION_MESSAGES_ENDPOINT:
+        return "completion"
+    if endpoint.startswith("/workflows/") or endpoint == "/workflows":
+        return "workflow"
+    return "api"
+
+
+def _default_span_name(endpoint: str) -> str:
+    kind = _endpoint_kind(endpoint)
+    if kind == "chat":
+        return DIFY_CHAT_SPAN_NAME
+    if kind == "completion":
+        return DIFY_COMPLETION_SPAN_NAME
+    if kind == "workflow":
+        return DIFY_WORKFLOW_SPAN_NAME
+    return f"{DIFY_API_SPAN_NAME}:{endpoint.strip('/') or 'root'}"
+
+
+def _log_type(endpoint: str) -> str:
+    kind = _endpoint_kind(endpoint)
+    if kind == "chat":
+        return LOG_TYPE_CHAT
+    if kind == "completion":
+        return LOG_TYPE_TEXT
+    if kind == "workflow":
+        return LOG_TYPE_WORKFLOW
+    return LOG_TYPE_TASK
+
+
+def _request_input(request_json: Any, request_params: Any, request_data: Any) -> Any:
+    if request_json is not None:
+        return request_json
+    if request_data is not None:
+        return request_data
+    if request_params is not None:
+        return request_params
+    return {}
+
+
+def _string_content(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return safe_json(value=value)
+
+
+def _completion_prompt(request_json: Mapping[str, Any]) -> str:
+    query = request_json.get(QUERY_KEY)
+    if query:
+        return _string_content(query)
+    inputs = request_json.get(INPUTS_KEY)
+    if isinstance(inputs, Mapping) and inputs.get(QUERY_KEY):
+        return _string_content(inputs.get(QUERY_KEY))
+    return _string_content(inputs)
+
+
+def _response_output(response_data: Mapping[str, Any], stream_events: Sequence[Any]) -> Any:
+    if stream_events:
+        text = _stream_answer(stream_events=stream_events)
+        if text:
+            return text
+        return stream_events
+    if ANSWER_KEY in response_data:
+        return response_data.get(ANSWER_KEY)
+    data = response_data.get(DATA_KEY)
+    if isinstance(data, Mapping):
+        if OUTPUTS_KEY in data:
+            return data.get(OUTPUTS_KEY)
+        if ERROR_KEY in data and data.get(ERROR_KEY):
+            return data.get(ERROR_KEY)
+    return response_data
+
+
+def _metadata_usage(response_data: Mapping[str, Any]) -> Mapping[str, Any]:
+    metadata = response_data.get(METADATA_KEY)
+    usage = _get(metadata, USAGE_KEY)
+    mapping = _to_mapping(usage)
+    if mapping is not None:
+        return mapping
+
+    data = response_data.get(DATA_KEY)
+    if isinstance(data, Mapping):
+        return data
+    return {}
+
+
+def _stream_answer(stream_events: Sequence[Any]) -> str:
+    parts: list[str] = []
+    for event in stream_events:
+        mapping = _to_mapping(event)
+        if mapping is None:
+            if isinstance(event, str) and event and not event.startswith("["):
+                parts.append(event)
+            continue
+        answer = mapping.get(ANSWER_KEY)
+        if answer:
+            parts.append(str(answer))
+            continue
+        data = mapping.get(DATA_KEY)
+        if isinstance(data, Mapping):
+            for key in ("text", ANSWER_KEY):
+                value = data.get(key)
+                if value:
+                    parts.append(str(value))
+                    break
+    return "".join(parts)
+
+
+def _stream_usage(stream_events: Sequence[Any]) -> Mapping[str, Any]:
+    for event in reversed(stream_events):
+        mapping = _to_mapping(event)
+        if mapping is None:
+            continue
+        usage = _metadata_usage(mapping)
+        if usage:
+            return usage
+    return {}
+
+
+def _int_value(mapping: Mapping[str, Any], key: str) -> int | None:
+    value = mapping.get(key)
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return None
+
+
+def _set_metadata(attributes: dict[str, Any], key: str, value: Any) -> None:
+    if value is None:
+        return
+    if isinstance(value, bool):
+        attributes[f"{RESPAN_METADATA}.{key}"] = str(value).lower()
+    elif isinstance(value, (str, int, float)):
+        attributes[f"{RESPAN_METADATA}.{key}"] = str(value)
+    else:
+        attributes[f"{RESPAN_METADATA}.{key}"] = safe_json(value=value)
+
+
+def _apply_response_metadata(
+    attributes: dict[str, Any],
+    response_data: Mapping[str, Any],
+) -> None:
+    for key in (
+        EVENT_KEY,
+        TASK_ID_KEY,
+        ID_KEY,
+        MESSAGE_ID_KEY,
+        CONVERSATION_ID_KEY,
+        WORKFLOW_RUN_ID_KEY,
+        MODE_KEY,
+        STATUS_KEY,
+    ):
+        _set_metadata(attributes=attributes, key=f"dify.{key}", value=response_data.get(key))
+
+    data = response_data.get(DATA_KEY)
+    if isinstance(data, Mapping):
+        for key in ("workflow_id", "elapsed_time", "total_steps", TOTAL_TOKENS_KEY):
+            _set_metadata(attributes=attributes, key=f"dify.{key}", value=data.get(key))
+
+
+def _apply_request_context(
+    attributes: dict[str, Any],
+    *,
+    request_json: Mapping[str, Any],
+    request_params: Mapping[str, Any],
+) -> None:
+    user = request_json.get(USER_KEY) or request_params.get(USER_KEY)
+    if user:
+        attributes.setdefault(RESPAN_CUSTOMER_PARAMS_ID, str(user))
+
+    conversation_id = request_json.get(CONVERSATION_ID_KEY) or request_params.get(
+        CONVERSATION_ID_KEY
+    )
+    if conversation_id:
+        attributes.setdefault(RESPAN_THREADS_ID, str(conversation_id))
+
+    response_mode = request_json.get(RESPONSE_MODE_KEY)
+    if response_mode:
+        _set_metadata(
+            attributes=attributes,
+            key=f"dify.{RESPONSE_MODE_KEY}",
+            value=response_mode,
+        )
+    files = request_json.get(FILES_KEY)
+    if isinstance(files, Sequence) and not isinstance(files, (str, bytes, bytearray)):
+        _set_metadata(attributes=attributes, key="dify.files_count", value=len(files))
+
+
+def _apply_usage(
+    attributes: dict[str, Any],
+    *,
+    usage: Mapping[str, Any],
+) -> None:
+    prompt_tokens = _int_value(mapping=usage, key=PROMPT_TOKENS_KEY)
+    completion_tokens = _int_value(mapping=usage, key=COMPLETION_TOKENS_KEY)
+    total_tokens = _int_value(mapping=usage, key=TOTAL_TOKENS_KEY)
+    if total_tokens is None and (
+        prompt_tokens is not None or completion_tokens is not None
+    ):
+        total_tokens = (prompt_tokens or 0) + (completion_tokens or 0)
+
+    if prompt_tokens is not None:
+        attributes[GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS] = prompt_tokens
+        attributes[SpanAttributes.LLM_USAGE_PROMPT_TOKENS] = prompt_tokens
+    if completion_tokens is not None:
+        attributes[GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS] = completion_tokens
+        attributes[SpanAttributes.LLM_USAGE_COMPLETION_TOKENS] = completion_tokens
+    if total_tokens is not None:
+        attributes[SpanAttributes.LLM_USAGE_TOTAL_TOKENS] = total_tokens
+
+    _set_metadata(attributes=attributes, key=f"dify.{LATENCY_KEY}", value=usage.get(LATENCY_KEY))
+
+
+def _apply_llm_content(
+    attributes: dict[str, Any],
+    *,
+    endpoint: str,
+    request_json: Mapping[str, Any],
+    output: Any,
+) -> None:
+    kind = _endpoint_kind(endpoint)
+    if kind not in {"chat", "completion"}:
+        return
+
+    attributes[SpanAttributes.LLM_SYSTEM] = "dify"
+    # Respan's backend prompt/completion parser is keyed by llm.request.type=chat
+    # even for text-style Dify completion apps, which return answer-shaped
+    # message payloads rather than raw completion choices.
+    attributes[SpanAttributes.LLM_REQUEST_TYPE] = LLMRequestTypeValues.CHAT.value
+
+    prompt_content = (
+        _string_content(request_json.get(QUERY_KEY))
+        if kind == "chat"
+        else _completion_prompt(request_json=request_json)
+    )
+    if prompt_content:
+        attributes[f"{SpanAttributes.LLM_PROMPTS}.0.role"] = "user"
+        attributes[f"{SpanAttributes.LLM_PROMPTS}.0.content"] = prompt_content
+
+    output_text = _string_content(output)
+    if output_text:
+        attributes[f"{SpanAttributes.LLM_COMPLETIONS}.0.role"] = "assistant"
+        attributes[f"{SpanAttributes.LLM_COMPLETIONS}.0.content"] = output_text
+
+
+def _apply_respan_params(
+    *,
+    attributes: dict[str, Any],
+    respan_params: Mapping[str, Any],
+    current_workflow_name: str | None,
+    default_span_name: str,
+) -> str:
+    span_name = str(respan_params.get("span_name") or default_span_name)
+    workflow_name = (
+        respan_params.get("workflow_name")
+        or respan_params.get("span_workflow_name")
+        or current_workflow_name
+    )
+    if workflow_name:
+        attributes.setdefault(SpanAttributes.TRACELOOP_WORKFLOW_NAME, str(workflow_name))
+    if respan_params.get("workflow_name") and "trace_group_identifier" not in respan_params:
+        attributes.setdefault(RESPAN_TRACE_GROUP_ID, str(respan_params["workflow_name"]))
+
+    for key, value in respan_params.items():
+        if key in {
+            "parent_span_id",
+            "span_id",
+            "span_name",
+            "trace_id",
+            "trace_name",
+            "workflow_name",
+            "span_workflow_name",
+        }:
+            continue
+        attr_key = RESPAN_SPAN_ATTRIBUTES_MAP.get(str(key))
+        if attr_key is None:
+            continue
+        if attr_key == RESPAN_METADATA and isinstance(value, Mapping):
+            for metadata_key, metadata_value in value.items():
+                _set_metadata(
+                    attributes=attributes,
+                    key=str(metadata_key),
+                    value=metadata_value,
+                )
+        else:
+            attributes[attr_key] = value
+    return span_name
+
+
+def build_dify_span_data(
+    *,
+    method: str,
+    endpoint: str,
+    request_json: Any = None,
+    request_params: Any = None,
+    request_data: Any = None,
+    files: Any = None,
+    response: Any = None,
+    stream_events: Sequence[Any] | None = None,
+    error: Exception | None = None,
+    include_content: bool = True,
+    respan_params: Mapping[str, Any] | None = None,
+    propagated_attributes: Mapping[str, Any] | None = None,
+    current_workflow_name: str | None = None,
+) -> tuple[str, dict[str, Any]]:
+    """Build canonical span name and attributes from a Dify client call."""
+    endpoint = endpoint or ""
+    method = (method or "").upper()
+    request_json_mapping = _to_mapping(request_json) or {}
+    request_params_mapping = _to_mapping(request_params) or {}
+    response_data = _response_json(response)
+    stream_events = list(stream_events or [])
+    output = str(error) if error is not None else _response_output(response_data, stream_events)
+    default_span_name = _default_span_name(endpoint=endpoint)
+
+    attributes: dict[str, Any] = {
+        RESPAN_LOG_METHOD: LogMethodChoices.TRACING_INTEGRATION.value,
+        RESPAN_LOG_TYPE: _log_type(endpoint=endpoint),
+        SpanAttributes.TRACELOOP_ENTITY_NAME: default_span_name,
+        SpanAttributes.TRACELOOP_ENTITY_PATH: default_span_name,
+    }
+
+    _set_metadata(attributes=attributes, key=f"dify.{METHOD_KEY}", value=method)
+    _set_metadata(attributes=attributes, key=f"dify.{ENDPOINT_KEY}", value=endpoint)
+    if files:
+        _set_metadata(attributes=attributes, key="dify.file_upload", value=True)
+
+    _apply_request_context(
+        attributes=attributes,
+        request_json=request_json_mapping,
+        request_params=request_params_mapping,
+    )
+    _apply_response_metadata(attributes=attributes, response_data=response_data)
+
+    usage = (
+        _stream_usage(stream_events=stream_events)
+        if stream_events
+        else _metadata_usage(response_data=response_data)
+    )
+    _apply_usage(attributes=attributes, usage=usage)
+
+    if include_content:
+        request_input = _request_input(
+            request_json=request_json,
+            request_params=request_params,
+            request_data=request_data,
+        )
+        attributes[SpanAttributes.TRACELOOP_ENTITY_INPUT] = safe_json(
+            value=request_input
+        )
+        attributes[SpanAttributes.TRACELOOP_ENTITY_OUTPUT] = _string_content(output)
+        _apply_llm_content(
+            attributes=attributes,
+            endpoint=endpoint,
+            request_json=request_json_mapping,
+            output=output,
+        )
+
+    span_name = _apply_respan_params(
+        attributes=attributes,
+        respan_params=respan_params or {},
+        current_workflow_name=current_workflow_name,
+        default_span_name=default_span_name,
+    )
+    attributes[SpanAttributes.TRACELOOP_ENTITY_NAME] = span_name
+    attributes[SpanAttributes.TRACELOOP_ENTITY_PATH] = span_name
+
+    for key, value in (propagated_attributes or {}).items():
+        attributes[key] = value
+
+    for alias in OFF_CONTRACT_ALIASES:
+        attributes.pop(alias, None)
+
+    return span_name, attributes