推送遥测数据至自有可观测平台

​

开始之前

• 一个 Dify 部署可访问的 OpenTelemetry Collector，并已启用与所选传输协议匹配的 OTLP receiver（按惯例 HTTP 用 4318 端口，gRPC 用 4317）。出口连接由平台内置的 Dify Enterprise Collector 发起。
• 企业管理后台的访问权限。

​

推送哪些数据

​

配置连接

1. 在企业管理后台侧边栏打开 数据推送。
2. 点击右上角 参数配置，打开配置弹窗。
3. 选择 配置模式：统一配置 将 Metrics 和 Traces 推送到同一个端点（使用 OpenTelemetry Collector 时推荐）；分别配置 在 Traces 和 Metrics 两个标签页中分别设置端点。
4. 填写连接参数：
   • Endpoint URL：OpenTelemetry Collector 端点地址，协议头须为 http://、https://、grpc:// 或 grpcs://（如 http://otel-collector:4318）。使用 https:// 或 grpcs:// 端点即启用 TLS；协议头不决定传输格式，传输格式由 Transport Protocol 单独选择，需与 Collector 的 receiver 匹配。
   • Transport Protocol：http/protobuf（推荐）、grpc（性能更高，适合企业内部稳定网络）或 http/json（仅用于调试，性能较低）。
   • Compression：gzip（推荐）或 none。
   • Timeout：推送超时时间，以秒为单位的时长写法，如 5s。
   • Headers：用于鉴权等用途的键值对（如 Authorization: Bearer <token>），点击 添加 Header 逐条添加。
   • 高级设置（TLS 端点适用）：上传 Certificate File (CA)，即签发 Collector 服务端证书的 CA 证书（自签名证书上传自有 CA，公网可信证书上传对应公共 CA 的证书，如 Let’s Encrypt 根证书）。仅在开启 跳过证书验证 时可省略（生产环境不建议跳过）。如需 双向 TLS (mTLS)，再上传 Client Key File 与 Client Certificate File。
5. 点击 测试连通性，校验连接并提示成功或失败原因（网络不通、证书无效等）。
6. 点击 保存配置，在确认弹窗中点击 确认重启并应用。服务运行中保存会自动重启推送服务，可能产生短暂的数据传输中断。

​

启动与停止推送服务

• 启动：未运行状态下，点击 连接并推送数据 并确认，状态变为 服务运行中。
• 停止：运行中状态下，点击 停止推送服务 并确认，状态变为 服务未运行；停止会中断数据传输。

​

验证配置

1. 在 数据推送配置 页面确认状态显示为 服务运行中。
2. 触发运行已发布工作流，确认 Prometheus 可查询到 dify_requests_total{type="workflow"}。
3. 运行多节点工作流，确认 Jaeger 可查看到完整 dify.workflow.run 与 dify.node.execution 链路。
4. 在 Studio（Dify 应用编排界面）调试工作流，确认 Prometheus 可查询到 dify_requests_total{type="draft_node"}，Jaeger 中出现 dify.node.execution.draft Span。
5. 验证工具调用、知识库检索与内容审核事件可正确在日志平台展现（依赖「推送哪些数据」一节所述的标准输出日志管道）。
6. 在内容推送关闭（默认状态，见「控制 Input/Output 内容推送」）的情况下，验证敏感字段已被 ref:{id_type}={uuid} 脱敏替代。门控字段清单见 数据推送数据字典。

​

监控推送服务

• 页面提示「未连接，请配置参数并启动连接」。
• 点击右侧 连接并推送数据 开始连接，或点击右上方 参数配置 进入配置流程。

• 状态标识：绿色指示灯 + 服务运行中。
• 本次连接起始时间：当前连接的开始时间（YYYY-MM-DD HH:mm:ss）。
• 数据统计：已推送数据量（实时更新，单位 MB/GB）与 未推送积压数据量（缓冲区暂存数据）。
• 最近数据推送记录：展示 OpenTelemetry 反馈的异常日志、网络异常日志等。

• 状态标识：橙色指示灯 + 服务异常。需检查 最近数据推送记录 中的日志并修复异常，避免数据丢失。

​

控制 Input/Output 内容推送

• 关闭（默认）：内容字段以 ref:{id_type}={uuid} 格式的引用串替代，Message ID、用户 ID、应用 ID 等元数据仍会推送；可凭引用串中的 UUID 在 Dify 数据库中回查对应记录（如工作流运行、消息）。
• 开启：推送请求输入与模型输出的原文。

​

生产环境规划

​

架构与责任边界

Dify API/Worker
    ↓ OTLP gRPC（异步，内置 Buffer）
Dify Enterprise Collector（平台内置，负责接收和转发）
    ↓ OTLP（客户配置 Endpoint）
客户 OTel Collector（客户自行部署）
    ├──► Prometheus（pull 抓取 /metrics）→ Grafana
    └──► Jaeger / Tempo（Traces）

Dify API/Worker 标准输出（JSON 事件日志）
    └──► 自备日志采集器（Promtail / Fluent Bit / Vector）──► Loki / OpenSearch

1. Dify API 生成业务 Metric、Trace 和业务事件，先写入内置缓冲区，再由 OTel SDK 异步发送。
2. Dify Enterprise Collector 通过 OTLP gRPC 接收数据，使用 batch、aggregation 等 Processor 处理，同时将推送服务的运行状态（连接时间、已推送量等）写入 Enterprise DB 供管理后台展示。
3. 其 Exporter 将数据发送到客户提供的 OpenTelemetry Collector；出口地址、协议、TLS 和鉴权由数据推送配置决定。
4. 客户 Collector 将数据路由到 Prometheus/Thanos（Metrics）、Jaeger/Tempo（Traces）等后端，Grafana 或企业 BI 工具从这些后端查询展示数据。

​

规划 Collector 资源

每日 Trace 规模
≈ 正式工作流运行数 + 正式节点执行数 + 调试节点执行数

每日业务事件规模
≈ 消息数 + 工具调用数 + 审核数 + 检索数
+ 建议问题生成数 + 会话名称生成数 + 提示词生成数 + 反馈数

​

数据保留

• Metrics 常见起始保留期：15～30 天，趋势分析可延长至 90 天。
• Trace 常见起始保留期：3～7 天。

​

故障排查

• 无法连接到 OpenTelemetry Collector：检查 Endpoint URL 是否正确、网络是否连通；TLS 端点需检查 CA、客户端证书与私钥的有效性和格式。使用 测试连通性 查看具体报错并修正配置。
• 数据推送中断：查看 最近数据推送记录，排查网络波动或 Collector 异常；检查 Collector 是否正常运行、是否达到接收上限。
• 数据积压持续增加：Collector 消费速度慢于数据产生速度，或网络延迟较高。积压数据暂存缓冲区，连接恢复后继续推送；缓冲区满载时丢弃新数据。建议优化 Collector 资源配置或扩容实例。
• 配置保存失败：检查必填项是否填写完整；TLS 端点需确认相关证书文件已正确上传。
• 数据丢失：可能发生在服务异常、缓冲区溢出或系统重启时（这是保护主业务的降级策略）。若关键数据不可丢失，建议提升 Collector 处理能力，避免长期积压。