12.1 · 跟踪管理器与提供方集成

跟踪管理器与提供方集成

追踪管理器与提供商集成

本文详细介绍了 Dify 的追踪系统，重点阐述了 OpsTraceManager 架构及其与各种第三方追踪提供商的集成。内容涵盖实现细节、数据流向以及将追踪数据发送至 Langfuse、LangSmith、Arize Phoenix、Opik、Weave、阿里云和腾讯云等平台所涉及的关键组件。

OpsTraceManager 架构

OpsTraceManager 是负责管理追踪数据并将其分发至已配置追踪提供商的核心组件。它以异步方式运行，避免阻塞主应用流程，主要利用专用的 Celery 队列进行任务处理。

核心组件

• OpsTraceManager 类：该类 api/core/ops/ops_trace_manager.py:188-190 负责编排追踪流程，管理提供商的初始化与任务分发。
• process_trace_tasks：一个 Celery 任务 api/tasks/ops_trace_task.py:47，负责异步处理追踪数据。它会从临时存储中加载追踪信息，并通过管理器进行分发。
• provider_config_map：一个映射表 api/core/ops/ops_trace_manager.py:149-150，将 TracingProviderEnum 值与其对应的配置类（例如 LangfuseConfig、LangSmithConfig）及追踪实例实现关联起来。
• TraceAppConfig 模型：在数据库中存储每个应用对应的追踪提供商配置 api/models/model.py:44。这包括 API 密钥、端点和项目名称，这些信息会经过加密以确保安全。
• ParentTraceContext：一个辅助类 api/core/helper/trace_id_helper.py:19，用于在嵌套工作流中传播追踪 ID，这对于 Phoenix 等提供商尤为重要 api/tasks/ops_trace_task.py:9-16。

数据流向

1. 追踪事件生成：当事件发生时（例如，消息被处理、工作流节点被执行），会实例化一个追踪信息对象（例如 MessageTraceInfo、WorkflowNodeTraceInfo）api/core/ops/entities/trace_entity.py:108, 196。
2. 任务序列化：追踪信息会被序列化并保存到临时存储中 api/tasks/ops_trace_task.py:56-57。
3. 追踪任务入队：调用 process_trace_tasks.delay() 方法，并传入文件信息。
4. 异步处理：Celery 工作进程拾取任务，加载数据，并使用 OpsTraceManager.get_ops_trace_instance(app_id) 识别正确的 trace_instance api/tasks/ops_trace_task.py:61。
5. 提供商分发：管理器解密提供商配置 api/core/ops/ops_trace_manager.py:36-38，并调用提供商的 trace 方法。
6. 重试逻辑：如果提供商抛出 RetryableTraceDispatchError（在嵌套工作流排序中常见），任务会延迟后重试 api/tasks/ops_trace_task.py:95-122。

关键函数与类

• OpsTraceManager.decrypt_tracing_config(tenant_id, provider, config)：解密指定提供商的敏感配置字段 api/core/ops/ops_trace_manager.py:36-38。
• OpsTraceManager.obfuscated_decrypt_token(provider, config)：混淆解密后的令牌，以便在 UI 中安全显示 api/core/ops/ops_trace_manager.py:39。
• TracingProviderEnum：一个 StrEnum，定义了所有支持的追踪提供商，包括 ARIZE、PHOENIX、LANGFUSE、LANGSMITH、OPIK、WEAVE、ALIYUN、MLFLOW、DATABRICKS 和 TENCENT api/core/ops/entities/config_entity.py:8-18。

Dify · 关键函数与类 · 图 1

图示：OpsTraceManager 异步分发流程

追踪信息实体

Dify 定义了特定的实体来捕获细粒度的执行数据：

• MessageTraceInfo：捕获消息处理详情、Token 使用量和流式延迟 api/core/ops/entities/trace_entity.py:108-120。
• WorkflowTraceInfo：整体工作流执行结果、状态以及输入/输出 api/core/ops/entities/trace_entity.py:86-106。
• WorkflowNodeTraceInfo：每个节点的执行数据，包括 node_type、elapsed_time 和 Token 使用量 api/core/ops/entities/trace_entity.py:196-235。
• ToolTraceInfo：工具调用的具体细节 api/core/ops/entities/trace_entity.py:151-162。
• DatasetRetrievalTraceInfo：检索到的文档及检索错误 api/core/ops/entities/trace_entity.py:146-149。

来源： api/core/ops/ops_trace_manager.py:1-47 api/core/ops/entities/config_entity.py:8-18 api/core/ops/entities/trace_entity.py:86-240

提供商集成

Langfuse 与 LangSmith

• Langfuse：配置需要 public_key、secret_key 和 host。Dify 会动态生成项目 URL，格式为 {host}/project/{key} api/services/ops_service.py:59-72。
• LangSmith：需要 api_key、project 和 endpoint。它使用 generate_dotted_order api/core/ops/utils.py:55-66 来维护 LangSmith UI 中的层级关系（父子 Span）。

Arize Phoenix

Arize 和 Phoenix 的集成利用了 OpenTelemetry（OTEL）标准。

• 配置：使用 ArizeConfig 或 PhoenixConfig，需要 api_key、project 和 endpoint。
• URL 处理：OpsService 为项目视图提供默认的回退 URL：https://app.arize.com/ 和 https://app.phoenix.arize.com/projects/ api/services/ops_service.py:41-58。
• 校验：如果项目名称为空，会规范化为 "default" api/tests/unit_tests/core/ops/test_config_entity.py:66-67。

云服务提供商（阿里云与腾讯云）

• 阿里云：与阿里云 ARMS 集成。需要 license_key 和 endpoint。配置确保 app_name 默认为 dify_app api/tests/unit_tests/core/ops/test_config_entity.py:69。
• 腾讯云：与腾讯云 APM 集成。需要 token、endpoint 和 service_name。控制台 URL 默认为 https://console.cloud.tencent.com/apm api/services/ops_service.py:109-116。

其他集成

• Opik：需要 api_key 和 project。项目名称默认为 Default Project api/tests/unit_tests/core/ops/test_config_entity.py:68。
• Weave：与 Weights & Biases Weave 集成。需要 api_key 和 project api/tests/unit_tests/core/ops/test_config_entity.py:36。
• MLflow 与 Databricks：支持在 MLflow 后端内追踪，MLflow 的默认主机为 http://localhost:5000/ api/services/ops_service.py:118-134。

来源： api/core/ops/entities/config_entity.py:8-18 api/services/ops_service.py:41-137 api/core/ops/utils.py:55-135 api/tests/unit_tests/core/ops/test_config_entity.py:14-70

前端集成

Dify Web 前端在应用概览部分为追踪提供商提供了统一的管理界面。

组件

• Panel：位于 web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx 的主入口点。它负责处理状态切换和提供商选择 web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx:28。
• ConfigPopup：一个基于模态框的界面，用于输入提供商特定的凭证 web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/config-popup.tsx:41。
• ProviderPanel：显示带有状态指示器（例如 "使用中"）和配置按钮的单个提供商卡片 web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/provider-panel.tsx:41。

交互逻辑

1. 状态检查：UI 使用 fetchTracingStatus 获取当前追踪状态 web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx:21。
2. 配置：当用户配置提供商时，后端会调用 OpsService.create_tracing_app_config api/services/ops_service.py:140。
3. 校验：凭证在存储前会被加密，在返回给 UI 进行编辑时会被混淆 api/services/ops_service.py:36-39。

Dify · 交互逻辑 · 图 2

图示：前端到后端的追踪配置桥接

来源：

• web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx:1-143
• web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/config-popup.tsx:41-91
• web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/provider-panel.tsx:41-111
• api/services/ops_service.py:11-140