> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据推送

数据推送配置是企业级数据治理模块的核心功能，基于 OpenTelemetry（OTel）开源标准构建，旨在解决企业数据孤岛问题。通过标准化数据管道，系统管理员可将平台细粒度业务数据（含应用运行指标、Token 消耗、用户行为等）实时推送至企业自有 BI 系统或数据仓库，实现统一数据资产沉淀、精细化运营分析与全局业务洞察。

## 1. 功能简介

在企业级使用场景中，Dify 平台的业务数据分散在各个工作空间与应用内，难以统一汇总到企业自有数据系统，导致以下痛点：

* **数据孤岛**：无法对跨工作空间的应用运行、Token 消耗、用户行为进行全局分析。
* **整合成本高**：缺乏标准化数据输出机制，企业需自行开发定制化数据采集方案。
* **隐私风险**：数据推送过程中缺乏敏感内容的可控性，易导致合规问题。

### 1.1 功能价值

* **标准化兼容**：基于 OpenTelemetry 协议，对接企业现有监控系统、数据仓库或 BI 平台。
* **全链路数据覆盖**：推送细粒度业务数据，支持用户、应用、工作空间等多维度分析。
* **高可靠保障**：通过缓冲区机制应对网络波动，优先保障主业务不受影响。
* **隐私可控**：提供开关控制是否推送 Input/Output 等敏感内容，满足合规要求。
* **实时性推送**：数据实时传输，支持企业及时进行运营复盘与异常响应。

### 1.2 适用场景

* **全局运营分析**：将 Dify 平台应用运行数据同步到自有 BI 系统进行跨部门评估。
* **成本精细化核算**：按工作空间/应用/用户维度统计 Token 消耗，进行成本分摊与优化。
* **性能监控与排查**：监控请求耗时、失败率等指标，快速定位问题。
* **合规数据管理**：严格控制敏感数据输出，仅推送非敏感统计维度数据。

### 1.3 核心概念

**数据传输与标准**

* **数据推送**：将 Dify 平台产生的运行日志、监控指标等数据，通过 OTel 标准协议实时传输至外部系统的服务。

* **OpenTelemetry（OTel）**：用于生成、收集、管理和导出遥测数据（度量、日志、追踪）的开源标准。

* **统一端点**：将 Metrics 和 Traces 数据同时推至同一个 endpoint 端点下

* **分离端点**：将 Metrics 和 Traces 数据分别推至同一个或不同的 endpoints 端点下

**运行与控制机制**

* **缓冲区（Buffer）**：推送服务与接收端之间的临时存储队列（FIFO），用于应对网络抖动或接收端处理缓慢；缓冲区满载时会丢弃新数据以保护主业务。
* **隐私控制开关**：控制是否推送 Input/Output 的具体内容；关闭后仅推送 Message ID 等元数据，需企业自行回查内容。

### 1.4 数据字典

关于数据推送功能的详细数据字段定义、指标说明及日志格式，请参阅 [Data Dictionary](/zh/3.11.x/administer/data-push-data-dictionary)。

## 2. 操作说明

### 2.0 快速开始

数据推送的典型配置流程包括：**进入配置页面 > 填写 OTel 参数 > 测试连通性 > 保存配置 > 启动推送服务**。

1. **进入配置页面**
   登录企业管理后台，进入【数据治理】>【数据推送配置】。
2. **填写 OTel 参数**
   若服务未连接，点击右上角【参数配置】填写 OpenTelemetry Collector 信息。
3. **测试与保存**
   点击【测试连通性】验证网络与配置有效性，确认无误后保存配置并确认重启服务。
4. **启动服务**
   回到主页面点击【连接并推送数据】启动服务。

### 2.1 查看服务运行状态

进入【数据推送配置】页面后，默认展示服务的实时运行状态。

**状态 1：服务未运行**

* 页面提示：“未连接，请配置参数并启动连接”。
* 点击右侧【连接并推送数据】按钮开始连接，或点击右上方【参数配置】进入配置流程。

**状态 2：服务运行中（已连接）**
页面展示以下关键信息：

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

**状态 3：服务运行异常（已连接）**

* **状态标识**：橙色指示灯 + “服务运行异常”。

> **异常处理机制说明：**
>
> * 推送采用异步机制，**不影响主业务链路**。
> * 推送失败或连接中断时，数据自动存入缓冲区，连接恢复后继续推送。
> * 缓冲区满载时优先丢弃最晚的数据，确保主业务用户交互不被阻塞。
> * *注意：页面会提示可能导致数据丢失的场景（如推送服务异常、下游消费慢导致缓冲区溢出、系统重启）。*

### 2.2 参数配置

点击【参数配置】弹出配置表单，完成以下设置：

**1. 必填配置项**

* **Endpoint URL**：OpenTelemetry Collector 端点地址（如 `http://otel-collector:4318`），需确保 Dify 服务器可访问。
* **Transport Protocol**（传输协议）：
  * **http/protobuf**（推荐默认值）
  * **grpc**（性能更高，适合企业内部稳定网络）
  * **http/json**（仅用于调试，性能较低）
* **Compression**（压缩方式）：
  * **gzip**（推荐默认值）
  * **none**（仅用于调试）

**2. 可选配置项**

* **Timeout**：推送超时时间，默认 5 秒。
* **Headers**：自定义请求头用于鉴权等（如 `Authorization: Bearer <token>`），支持多行输入。
* **启用 TLS 安全连接**：开启后需上传证书文件（Certificate File (CA)、Client Key File、Client Certificate File），**生产环境推荐开启**。

**3. 配置操作**

* **测试连通性**：连接校验，提示成功/失败原因（网络不通、证书无效等）。
* **保存配置**：弹出确认框“保存应用配置并重启服务？”，确认后保存并返回运行状态页面。

### 2.3 隐私控制设置

在【数据推送配置】页面的隐私控制区域，可设置：

* **推送 Input/Output 内容（开关）**：
  * **开启**：推送请求 Input 内容与模型 Output 内容。
  * **关闭**：仅推送 Message ID、用户 ID、应用 ID 等元数据，不包含具体内容。
* 修改后需点击【保存设置】生效。

### 2.4 启动与停止推送服务

* **启动服务**：未连接状态下，点击【连接并推送数据】，状态变为“服务运行中”。
* **停止服务**：运行中状态下，点击【停止推送】，确认后停止，状态变为“未连接”。

## 3. 故障排查

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

## 4. 常见问题 (FAQ)

### 数据推送会影响 Dify 平台主业务性能吗？

不会。数据推送采用异步机制，与主业务链路隔离；缓冲区满载时会丢弃新数据，不会阻塞用户交互或应用运行。

### 数据推送包含哪些内容？

涵盖细粒度信息（以下为示例）：

* **元数据**：Message ID、用户 ID、应用 ID、工作空间 ID、时间戳。
* **运行指标**：Token 消耗（输入/输出）、请求耗时（RT）、运行状态（成功/失败）。
* **用户行为**：点赞/踩反馈。
  *(注：可通过隐私控制开关决定是否推送 Input/Output 具体内容)*。

### 为什么会出现数据积压？

通常是 Collector 处理速度慢于数据产生速度，或网络延迟导致。积压的数据会进入缓冲区，连接恢复后继续推送；若缓冲区满载，新数据会被丢弃。

### 生产环境推荐配置是什么？

建议传输协议使用 `http/protobuf` 或 `grpc`，压缩方式选择 `gzip`。建议开启 TLS 安全连接并配置鉴权 Headers。若有合规要求，建议关闭 Input/Output 内容推送。

## 5. 最佳实践

* **安全合规优先**：生产环境强烈建议开启 TLS，并配置鉴权 Headers；在对数据隐私有严格要求的场景下，务必关闭 Input/Output 内容推送。
* **实时监控与告警**：定期查看管理后台的运行状态与日志；建议在企业 Collector 侧配置监控告警（如连接中断、数据积压超过阈值等），以便及时介入。
* **性能调优**：大规模高并发场景下，优先使用 `grpc` 协议；同时确保下游 Collector 资源充足，避免因消费不及导致平台侧缓冲区溢出和数据丢失。