必须启用opentelemetry全链路追踪，通过trace_id贯穿webhook入口至回调响应各环节，在settings.py中配置otel sdk并早于路由启动，结合arms接入与debug.capture_context显式开启，确保span包含dify.node_id、input/output快照等关键字段。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中精准定位工作流卡顿、LLM响应延迟、异步节点阻塞或RAG召回失败等生产问题，必须让每次用户请求生成的trace_id贯穿Webhook入口→Workflow编排→LLM调用→工具执行→向量库检索→回调响应全路径，不能只依赖离散日志或单点埋点。
启用Dify服务端OpenTelemetry自动注入
进入Dify部署目录，编辑 dify/configs/settings.py 文件，在末尾追加以下配置：
【必须确保OTel SDK初始化早于Gin路由启动】 否则HTTP请求无法携带span上下文，整个链路将断裂为多个孤立trace。
添加如下代码块（注意缩进与Python语法）：
import os<br>from opentelemetry import trace<br>from opentelemetry.sdk.trace import TracerProvider<br>from opentelemetry.sdk.trace.export import BatchSpanProcessor<br>from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter<br><br># 仅开发环境启用本地输出，生产环境请替换为OTLP gRPC exporter<br>if os.getenv("ENV") == "development":<br> exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")<br>else:<br> exporter = OTLPSpanExporter(<br> endpoint="https://tracing.arms.aliyuncs.com/v1/traces",<br> headers={"Authorization": f"Bearer {os.getenv('ARMS_LICENSE_KEY', '')}"}<br> )<br><br>provider = TracerProvider()<br>processor = BatchSpanProcessor(exporter)<br>provider.add_span_processor(processor)<br>trace.set_tracer_provider(provider)
保存后重启Dify服务，此时所有HTTP入口请求将自动创建root span，并向下透传context。
配置Dify控制台可观测性接入参数
登录Dify管理后台 → 进入目标应用 → 左侧导航栏点击「监测」→「追踪应用性能」→「配置」。
在弹出对话框中填写三项必填字段：
• License Key：粘贴从阿里云ARMS控制台「接入中心」复制的鉴权Token（【该值不可为空且区分大小写】）
• Endpoint：替换为实际公网接入点，例如 tracing-cn-heyuan.arms.aliyuncs.com（注意：删除 http:// 前缀，不带端口）
• App Name：建议按“环境-业务-模块”命名，如 prod-customer-support-workflow
点击「保存并启用」后，Dify会自动将 workflow.run()、llm.invoke()、tool.execute() 等关键操作封装为子span，并注入 prompt_template、retrieved_chunk_count、tool_name 等语义属性。
验证链路完整性与关键节点快照捕获
第一步：触发一次测试工作流（例如发送含RAG查询的会话消息）
第二步：打开Jaeger UI（或ARMS链路分析页），按 trace_id 过滤最新请求
第三步：检查是否出现完整调用栈——应包含至少5个连续span：/workflow/run → /llm/invoke → /retrieval/query → /tool/execute → /callback/send
第四步：点击任意span，查看「Tags」面板中是否存在 dify.node_id、dify.workflow_id、dify.input_hash 字段；若缺失，说明 debug.capture_context 配置未生效
第五步：确认每个span的「Events」中是否记录了「input_snapshot」和「output_snapshot」事件；没有则需在 workflow.yaml 中显式开启：
debug:<br> capture_context: ["input", "output", "prompt"]
