# 数据收集政策

Source: https://langbot.app/docs/zh/insight/data-collection-policy

可选遥测、执行链路、数据范围与关闭方法

LangBot 向 `space.url` 配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送产品遥测，用于了解使用情况和改进可靠性。**遥测默认开启，可以关闭。** 以下说明对应 4.11 当前的执行遥测协议（`schema: 2`）；旧版本数据另见下文。

## 执行遥测

符合上报条件的一次执行由共享 `event_id` 的独立记录组成：每个工作流节点完成时生成一条 `execution_node`，执行结束时生成一条 `execution_chain`。Core 将记录放入有界缓冲区，后台批量发送；Space 将节点重组为执行链路。当前发送端不再使用旧的功能窗口计数或在本地拼装完整链路。

**平台事件没有命中业务路由，或最终命中 `discard`（忽略/丢弃）且没有匹配的插件订阅时，不上报任何执行节点或链路结束记录。** 路由禁用、事件类型或过滤条件不匹配也属于此范围；本地日志和监控仍保留原有行为。主路由未命中但插件事件处理器匹配时，保留实际处理的执行，省略未命中和丢弃旁支的遥测。

命中业务路由后，目标不可用、执行失败、超时或 Pipeline 内部过滤仍可上报。有效交互回调恢复原处理器、WebUI/API 调试及显式指定 Pipeline 的独立调用也可上报；无效回调不会单独取得上报资格。此过滤先于采样和失败兜底，对 Cloud 同样生效。升级 Core 后生效；旧客户端及已有历史记录不受追溯修改。

| 数据    | 内容                                                                                          |
| ----- | ------------------------------------------------------------------------------------------- |
| 标识与环境 | `instance_id`、`workspace_uuid`、`event_id`、版本、部署版本类型、时间戳、调试标记与采样信息                           |
| 执行节点  | 平台事件、路由、Pipeline、Runner、平台 API 和工具调用的操作标识、处理模式、结果、起止时间、父子节点与顺序、路由目标和 Runner 运行标识            |
| 链路结束  | 整体结果、关闭原因、耗时、节点数、因采样未上报的节点数、来源、模型名称、适配器、Runner 与管道插件                                        |
| 绑定资源  | Pipeline 或 Agent 获准使用的插件、MCP 服务器、知识库、工具及来源、技能、模型、平台 API 的标识或名称，以及资源选择字段、能力与授权标记；实际字段取决于执行路径 |
| 错误    | 经过长度限制和空白清理的简短错误文本，可能包含异常类型与异常消息前缀                                                          |

绑定资源表示这次执行被配置或授权使用哪些资源，**不等于实际调用、检索或消耗了这些资源**。路由目标使用 `type:uuid`，不使用用户自定义规则名。

执行记录不会主动采集消息正文、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果、凭据或完整异常堆栈。**但错误文本截断并非可靠脱敏，异常消息前缀以及自定义的模型、技能或资源名称仍可能含有敏感信息。** 实例与工作区标识可能关联到部署或账户，不能将这些记录视为匿名数据或保证不含用户内容。

### 采样与调试执行

社区版通过 `space.execution_trace` 控制执行上报：

| 模式         | 行为                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------- |
| `all`（默认）  | 记录所有符合上报条件的执行的节点和结束记录                                                                     |
| `sampled`  | 根据事件标识的稳定哈希，在入口决定是否采样；成功执行约保留 `1/N`，N 为 `space.execution_trace_sample`（默认 20），同一次执行共享采样决定 |
| `failures` | 普通执行不保留节点，只在失败、取消、超时或有链路失败原因时上报结束记录                                                       |
| `off`      | 关闭节点和链路结束记录；没有继续上报的独立窗口计数，工作区心跳仍由总开关控制                                                    |

`sampled` 未命中的执行如果失败，仍会上报链路结束记录，但不会追补已跳过的节点，因此可能只有摘要而没有完整链路。WebUI 调试执行在 `all`、`sampled` 和 `failures` 下均保留，并带有调试标记；`off` 或总开关关闭后不再上报。

**Cloud 在产品遥测启用时固定使用 `all`**，以避免对成功执行的采样影响活动计数；实例运维方仍可使用 `space.disable_telemetry` 关闭本页所述产品遥测。

### 发送与完整性

记录通过 `POST /api/v1/telemetry` 发送。默认刷新间隔为 180 秒，可通过 `space.telemetry_flush_seconds` 调整。每次刷新最多发送 128 条，内存缓冲最多 512 条；发送成功后才移除对应记录，失败会重试，缓冲满时丢弃最旧记录。停机时尝试在有限时间内发送剩余记录。

网络故障、超时或服务端错误不会使业务执行因遥测失败而报错，上报失败详情记录在 DEBUG 日志中。采样、缓冲溢出、进程退出或跨任务关联失效可能造成不完整链路，**全量模式不保证完整送达**。平台 API 返回成功也不代表用户已阅读消息。

## 心跳、问卷与旧版本数据

活跃工作区在启动约 30 秒后首次发送 `instance_heartbeat`。普通部署此后每天发送，Cloud runtime 每 5 分钟刷新。心跳包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、适配器类型，以及机器人、Pipeline、插件、Agent、事件处理器、事件绑定、MCP、知识库和技能等资源数量；不主动包含资源正文或连接凭据。

自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容。

Space 仍兼容旧版本的 `query` 和 `feature_execution` 数据。旧查询记录可能含模型名称、功能使用计数、自定义技能/MCP 名称及原始 traceback。当前执行记录的字段限制不会追溯清理这些历史数据，也不会改变仍在运行的旧客户端的上报内容。

## 存储与保留

数据存储在所配置的 Space 服务。执行列表、链路详情和汇总仅供获授权的遥测管理用户或服务客户端访问。`execution_node`、`execution_chain` 及旧 `feature_execution` 原始记录按 30 天窗口定期分批清理；服务中断或积压可能延迟删除。该期限不改变旧查询遥测、心跳、问卷、账户或服务日志的保留规则。

关闭遥测会停止后续上报，但不会删除服务端已有记录。如需处理历史数据，请联系 <hello@langbot.app> 或所用 Space 的管理员。

## 关闭遥测

在 `data/config.yaml` 的现有 `space` 节点中设置以下值，保留其他配置，然后重启 LangBot：

```yaml
space:
  disable_telemetry: true
```

此开关统一关闭本页所述产品遥测，并关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。

如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。

Cloud 的 Plugin Runtime 运维健康上报独立于产品遥测，由 `plugin.runtime_ops.enabled` 控制，不能通过 `space.disable_telemetry` 关闭。

参见[系统环境设置](https://langbot.app/docs/zh/deploy/settings.md)。