agentic_huge_data_base / wiki
页面 Dify · 12.2 OpenTelemetry 与 Sentry 集成·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 12.2

12.2 · OpenTelemetry 与 Sentry 集成（OpenTelemetry and Sentry Integration）

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目Dify 章节12.2 状态全文译文 模块接口与服务契约、测试、发布与运维、安装与启动、工作流与编排
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节OpenTelemetry and Sentry Integration 上一章12.1 下一章14
源码线索
  • api/.env.example
  • api/app.py
  • api/app_factory.py
  • api/configs/feature/__init__.py
  • api/configs/middleware/__init__.py
  • api/configs/observability/__init__.py
  • api/configs/observability/otel/otel_config.py
  • api/configs/packaging/__init__.py
  • api/controllers/console/datasets/datasets.py
  • api/core/ops/entities/config_entity.py
模块标签
  • 接口与服务契约
  • 测试、发布与运维
  • 安装与启动
  • 工作流与编排
  • 检索、召回与索引

章节正文

OpenTelemetry 与 Sentry 集成

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/12.2-opentelemetry-and-sentry-integration

OpenTelemetry 与 Sentry 集成

相关源文件

本章引用的主要源码文件：

  • api/.env.example
  • api/app.py
  • api/app_factory.py
  • api/configs/feature/__init__.py
  • api/configs/middleware/__init__.py
  • api/configs/observability/__init__.py
  • api/configs/observability/otel/otel_config.py
  • api/configs/packaging/__init__.py
  • api/controllers/console/datasets/datasets.py
  • api/core/ops/entities/config_entity.py
  • api/core/ops/entities/trace_entity.py
  • api/core/ops/ops_trace_manager.py
  • api/core/ops/utils.py
  • api/core/rag/datasource/vdb/vector_factory.py
  • api/core/rag/datasource/vdb/vector_type.py
  • api/extensions/ext_compress.py
  • api/extensions/ext_otel.py
  • api/extensions/otel/instrumentation.py
  • api/pyproject.toml
  • api/services/ops_service.py
  • api/tasks/ops_trace_task.py
  • api/tests/unit_tests/configs/test_dify_config.py
  • api/tests/unit_tests/core/ops/__init__.py
  • api/tests/unit_tests/core/ops/test_config_entity.py
  • api/tests/unit_tests/core/ops/test_ops_trace_manager.py
  • api/tests/unit_tests/core/ops/test_utils.py
  • api/tests/unit_tests/core/workflow/graph_engine/test_table_runner.py
  • api/uv.lock
  • docker/.env.example
  • docker/README.md
  • docker/docker-compose-template.yaml
  • docker/docker-compose.middleware.yaml
  • docker/docker-compose.yaml
  • docker/envs/core-services/shared.env.example
  • docker/envs/infrastructure/nginx.env.example
  • docker/envs/security.env.example
  • docker/nginx/conf.d/default.conf.template
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/page.tsx](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/page.tsx)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/config-popup.tsx](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/config-popup.tsx)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/config.ts](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/config.ts)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/field.tsx](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/field.tsx)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/provider-panel.tsx](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/provider-panel.tsx)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/tracing-icon.tsx](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/tracing-icon.tsx)
  • [web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/type.ts](web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/type.ts)
  • web/app/components/base/icons/src/public/tracing/index.ts
  • web/package.json

本文详细介绍了 Dify 代码库中 OpenTelemetry 分布式追踪和 Sentry 错误追踪的集成方式。内容涵盖这些可观测性扩展的配置、实现和数据流，帮助理解 Dify 如何利用它们进行监控和调试。

OpenTelemetry 集成

Dify 使用 OpenTelemetry（OTEL）进行分布式追踪和指标收集，能够端到端地观察请求在各个服务和组件间的流转过程，有助于理解性能瓶颈并调试复杂的交互场景。

OTEL 配置

OpenTelemetry 通过基于 Pydantic 的配置系统管理的环境变量进行配置。核心配置包括设置 OTEL 收集器端点以及启用特定的检测功能。

OpenTelemetry 的关键环境变量包括：

  • ENABLE_OTEL：布尔标志，用于启用或禁用 OpenTelemetry 检测 api/extensions/ext_otel.py:144
  • OTEL_EXPORTER_TYPE：定义导出器后端（例如 otlp 或 console）api/extensions/ext_otel.py:79
  • OTLP_BASE_ENDPOINT：指定 OpenTelemetry 收集器的基本端点 api/extensions/ext_otel.py:82
  • OTEL_SAMPLING_RATE：控制追踪的采样率 api/extensions/ext_otel.py:72
  • OTEL_EXPORTER_OTLP_PROTOCOL：配置 OTLP 导出协议，支持 grpc 和 http api/extensions/ext_otel.py:78-80

api/pyproject.toml 文件指定了所需的 OTEL 依赖，包括 opentelemetry-distro 以及针对 Flask、SQLAlchemy、Redis、Celery 和 HTTPX 的特定检测库 api/pyproject.toml:35-41。

OpenTelemetry 初始化

OpenTelemetry SDK 和检测功能在 api/extensions/ext_otel.py 中初始化。init_app() 函数执行以下步骤：

  1. 上下文传播：调用 setup_context_propagation() 确保追踪 ID 在线程和服务间传递 api/extensions/ext_otel.py:54
  2. 资源定义：创建包含语义属性的 Resource 对象，如 SERVICE_NAME、SERVICE_VERSION、PROCESS_PID 和 HOST_NAME api/extensions/ext_otel.py:57-71
  3. 采样器设置：根据配置的采样率初始化 ParentBasedTraceIdRatio 采样器 api/extensions/ext_otel.py:72
  4. 追踪器提供者：使用配置的资源和采样器设置 TracerProvider，然后全局注册 api/extensions/ext_otel.py:73-75
  5. 导出器配置：根据 OTEL_EXPORTER_TYPE 初始化 GRPCSpanExporter 或 HTTPSpanExporter api/extensions/ext_otel.py:79-117
  6. 指标读取器：配置 PeriodicExportingMetricReader，按时间间隔导出指标 api/extensions/ext_otel.py:131-136
  7. 检测：调用 init_instruments(app) 对 Flask、SQLAlchemy、Redis、Celery 和 HTTP 库应用自动检测 api/extensions/ext_otel.py:138
图表：OpenTelemetry 初始化与代码映射

此图表将逻辑初始化步骤映射到代码库中的具体函数和类。

Dify · 图表：OpenTelemetry 初始化与代码映射 · 图 1
Dify · 图表：OpenTelemetry 初始化与代码映射 · 图 1

来源： api/extensions/ext_otel.py:14-141 api/extensions/otel/instrumentation.py:1-20

API 响应中的追踪 ID 传播

为方便调试，Dify 将 OpenTelemetry 的追踪 ID 和跨度 ID 注入到 HTTP 响应头中。这由 Flask 应用工厂中的 @after_request 钩子处理 api/app_factory.py:100-118。

  • X-Trace-Id：32 字符的十六进制字符串，代表 OTEL 追踪 ID api/app_factory.py:111
  • X-Span-Id：16 字符的十六进制字符串，代表 OTEL 跨度 ID api/app_factory.py:113

Sentry 集成

Sentry 用于错误追踪和性能监控。它已集成到 Flask 应用和 Celery 工作进程中。

Sentry 配置

Sentry 设置定义在环境文件中，并通过 Pydantic 设置进行管理。

  • API_SENTRY_DSN：后端 API 的数据源名称 docker/.env.example:128
  • API_SENTRY_TRACES_SAMPLE_RATE：性能追踪的采样率 docker/.env.example:129
  • WEB_SENTRY_DSN：前端 Web 应用的 DSN docker/.env.example:131

前端集成使用 @sentry/react 包 web/package.json:71。

Sentry 初始化与流程

Sentry 在 api/extensions/ext_sentry.py 中初始化。该过程包括：

  1. DSN 检查：确保 dify_config 中配置了 SENTRY_DSN api/app_factory.py:167
  2. SDK 初始化：调用 sentry_sdk.init()，传入环境、发布版本和采样率配置
  3. 集成：启用 Flask 和 Celery 的标准集成，以捕获未处理的异常和性能数据

追踪管理器与外部提供者

除了系统级的 OTEL，Dify 还提供了 OpsTraceManager，允许用户将应用级的大语言模型（LLM）追踪导出到第三方提供者，如 Langfuse、LangSmith 和 Arize Phoenix。

OpsTraceManager

api/core/ops/ops_trace_manager.py 中的 OpsTraceManager 管理这些外部追踪的生命周期。

  • 配置：通过 TraceAppConfig 为每个应用启用追踪 api/core/ops/ops_trace_manager.py:44
  • 凭证管理：使用 batch_decrypt_token 处理 API 密钥的解密，并使用 obfuscated_token 进行 UI 显示 api/core/ops/ops_trace_manager.py:18
  • 任务处理：追踪数据通过 tasks.ops_trace_task.process_trace_tasks 中定义的 Celery 任务异步处理 api/core/ops/ops_trace_manager.py:48
  • 上下文处理：通过 ParentTraceContext 管理父追踪上下文的传播 api/core/ops/ops_trace_manager.py:19
图表：应用追踪数据流

此图表展示了应用特定的大语言模型（LLM）追踪如何通过 OpsTraceManager 从 API 流向外部提供者。

Dify · 图表：应用追踪数据流 · 图 2
Dify · 图表：应用追踪数据流 · 图 2

来源： api/core/ops/ops_trace_manager.py:1-48 api/tasks/ops_trace_task.py:1-50 api/core/ops/entities/trace_entity.py:25-38

支持的提供者

Dify 通过 TracingProviderEnum 支持多种追踪提供者 api/core/ops/entities/config_entity.py:23：

  • 开源/自托管：Arize Phoenix、Langfuse、Opik、MLflow
  • 云原生：LangSmith、阿里云（ARMS）、腾讯云（APM）、Databricks、Weave

这些提供者的前端配置在应用概览追踪面板中管理，允许用户配置 DSN 和 API 密钥 web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/panel.tsx:21。

来源：

  • api/extensions/ext_otel.py:1-145
  • api/app_factory.py:100-186
  • api/core/ops/ops_trace_manager.py:1-120
  • api/core/ops/entities/config_entity.py:1-30
  • api/pyproject.toml:35-41
  • docker/.env.example:128-131