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

# 遥测

> CLI 会发送什么、绝不发送什么，以及如何关闭遥测。

`e2e` CLI 会发送匿名使用数据：用户使用哪些命令、引擎和功能，以及运行在哪些环节失败。遥测默认开启，只发送计数和版本，绝不发送测试内容、应用内容或凭据。

## 退出遥测

以下任一种方式都可关闭遥测：

<CodeGroup>
```bash npm
npx e2e telemetry disable   # saved in ~/.config/e2e/telemetry.json
export E2E_TELEMETRY_DISABLED=1          # for a shell or a CI job
export DO_NOT_TRACK=1                    # the cross-tool convention
```

```bash pnpm
pnpm exec e2e telemetry disable   # saved in ~/.config/e2e/telemetry.json
export E2E_TELEMETRY_DISABLED=1          # for a shell or a CI job
export DO_NOT_TRACK=1                    # the cross-tool convention
```

```bash bun
bunx e2e telemetry disable   # saved in ~/.config/e2e/telemetry.json
export E2E_TELEMETRY_DISABLED=1          # for a shell or a CI job
export DO_NOT_TRACK=1                    # the cross-tool convention
```
</CodeGroup>

环境变量优先于已保存的设置。`e2e telemetry enable` 会撤销已保存的 `disable`。`e2e telemetry` 输出状态，并在关闭时说明原因。如果设置了 XDG_CONFIG_HOME，偏好设置文件就位于 `$XDG_CONFIG_HOME/e2e/`；Windows 上则位于 `%APPDATA%\e2e\`。

`disable` 也会停止其他终端中已在运行的命令发送遥测。偏好设置目录不可写时，或从 e2e 仓库的源码检出目录运行时，不会发送任何内容。

## 查看将发送的内容

<CodeGroup>
```bash npm
E2E_TELEMETRY_DEBUG=1 npx e2e run
```

```bash pnpm
E2E_TELEMETRY_DEBUG=1 pnpm exec e2e run
```

```bash bun
E2E_TELEMETRY_DEBUG=1 bunx e2e run
```
</CodeGroup>

CLI 会以 `[telemetry] {...}` 格式将确切的载荷输出到标准错误，不发送任何内容。

## 发送的内容

每个命令都会发送一个 `e2e_cli_session` 事件。`run` 和 `explore` 还会发送 `e2e_run_completed`；`init` 发送 `e2e_init_completed`（`explore` 先运行初始化向导时也会发送）；`upgrade` 发送 `e2e_upgrade_completed`；`mcp` 为每个 MCP 会话发送一个 `e2e_mcp_session`。任何命令使用 `--help` 和 `--version` 时都不发送任何内容。`e2e/runner` 中的 `run()` 和 `explore()` 不发送会话事件，只在每次调用返回报告时发送一个 `e2e_run_completed`。

命令、`run()` 或 `explore()` 结束时，事件会在同一个请求中发送，截止时限为两秒。`e2e mcp` 为每个会话事件单独发送请求，`e2e run --watch` 则在每次运行结束时发送该次运行的事件。

事件只包含以下属性。不是大写标记的错误代码会作为 `OTHER` 发送。引擎、平台、模型、机群或 MCP 客户端名称，以及 MCP 客户端版本，如果不是仅由字母、数字、点、连字符和下划线组成的简单标记，都会作为 `other` 发送。不符合 semver 的引擎版本会作为 `unversioned` 发送。在操作和工具调用计数中，项目自有工具统一计为 `tool`，其他任何名称计为 `other`。

<AccordionGroup>
<Accordion title="每个事件">

| 属性 | 值 |
| --- | --- |
| `distinct_id` | 存储在偏好设置文件中的随机 ID。CI 改用 `ci:<vendor>`，机群使用 `fleet:<name>`（参阅[在机群中](#in-a-fleet)） |
| `project_id` | 仓库根提交的哈希值，完整克隆之间共享。在 git 之外和浅克隆中为 `null` |
| `session_id` | 本次调用的随机 ID |
| `first_run`, `days_since_first_run` | 此命令是否创建了偏好设置文件，以及此后经过的完整天数。在 CI、机群中，以及开始记录时间之前的偏好设置文件中为 `null` |
| `os`, `os_release`, `arch`, `cpu_count`, `memory_gb`, `docker`, `wsl`, `tty` | 机器类别 |
| `sandbox` | 内核声明自身所在的 microVM（`firecracker`），否则为 `null` |
| `ci`, `ci_name` | 是否设置了 `CI`，以及 CI 厂商自行标识时的厂商名称（`github-actions`、`gitlab`、`circleci` 等） |
| `fleet` | `E2E_TELEMETRY_FLEET` 的值，未设置时为 `null` |
| `coding_agent` | 在其 Shell 中运行该命令的编码智能体，如果它自行标识（`claude-code`、`cursor`、`codex` 等） |
| `e2e_version`, `package_manager` | e2e 版本，以及启动 CLI 的包管理器 |
| `runtime`, `runtime_version`, `node_version` | `node`、`bun` 或 `deno` 及其版本。`node_version` 是 Node 自身的版本，或 Bun、Deno 下的 Node 兼容版本 |
| `$lib`, `$lib_version`, `$process_person_profile`, `$geoip_disable` | `e2e`、其版本、`false` 和 `true`：PostHog 不保留个人档案，也不推导位置 |

</Accordion>
<Accordion title="e2e_cli_session，每个命令一次">

| 属性 | 值 |
| --- | --- |
| `command` | `init`、`run`、`list`、`cache ls`、`guide`、`telemetry` 等 |
| `flags` | 传入的参数名称，例如 `--headed` 或 `--tag`，绝不包含参数值 |
| `exit_code`, `duration_ms` | 命令如何结束，以及耗时多久 |
| `error_code` | 使命令在执行前停止的失败所对应的运行器代码（`CONFIG_NOT_FOUND`、`INVALID_CONFIG` 等）；CLI 拒绝的选项或参数对应 `CLI_USAGE`，否则为 `null` |

</Accordion>
<Accordion title="e2e_init_completed，每次初始化向导一次">

| 属性 | 值 |
| --- | --- |
| `result` | `scaffolded`、`already-initialized`、`cancelled`、`install-failed`、`not-interactive`、`invalid-project` 或 `example-failed` |
| `yes`, `existing_config` | 是否传入 `--yes`，以及是否已存在配置，因此无需询问引擎或网关 |
| `example` | `--example` 名称（`with-vite`、`with-expo` 等），未提供该参数时为 `null` |
| `engine`, `gateway` | 为新配置选择的引擎和模型网关 ID（`web`、`mobile`、`web,mobile`、`none`；`vercel`、`openrouter`、`openai-compatible`、`chatgpt`、`copilot`、`opencode-console`、`grok`、`none`），未询问时为 `null`。绝不包含为兼容 OpenAI 的网关输入的端点 |
| `skill`, `mcp`, `install` | 是否选择了智能体技能、MCP 注册和依赖项安装 |
| `ci` | 选择的 CI 流水线（`github-actions`、`gitlab` 或 `none`），未询问时为 `null` |

</Accordion>
<Accordion title="e2e_upgrade_completed，每次 e2e upgrade 一次">

| 属性 | 值 |
| --- | --- |
| `result` | `upgraded`、`up-to-date`、`dry-run`、`no-project`、`invalid-project`、`linked`、`unknown-target`、`incompatible`、`registry-failed` 或 `install-failed` |
| `target` | 指定版本时为 `version`，否则为分发标签：`latest`、`nightly`、`canary`、`beta` 或 `other` |
| `from_version`, `to_version`, `prerelease` | 升级前安装的 `e2e` 版本、目标解析出的版本，以及该版本是否为预发布版本。未知时为 `null` |
| `manager` | 命令为项目选择的包管理器：`npm`、`pnpm`、`yarn` 或 `bun`。只在 `upgraded` 时安装。如果命令在选择之前停止，则为 `null` |
| `siblings` | 升级计划中的 `@e2e-dev` 包，去掉作用域：`["web", "kernel"]`。不包含链接包和注册表中不存在的包 |
| `packages_moved`, `packages_linked` | 升级改写了 `package.json` 中多少个 `e2e` 和 `@e2e-dev` 条目，以及多少条目因不是注册表版本（`workspace:`、`file:`、`catalog:`、路径、git、别名）而保持原样。不是锁文件中的包数量 |

</Accordion>
<Accordion title="e2e_run_completed，每次 e2e run、e2e explore 或已完成的 run()、explore() 一次">

| 属性 | 值 |
| --- | --- |
| `command` | `run`、`explore`；`e2e/runner` 中的 `run()` 对应 `runner.run`，`explore()` 对应 `runner.explore` |
| `status`, `exit_code`, `duration_ms` | 运行结果 |
| `flags` | 传给 run 命令的参数名称，绝不包含参数值 |
| `tests_discovered`, `tests_selected`, `tests_executed`, `tests_passed`, `tests_failed`, `tests_interrupted`, `tests_flaky`, `tests_skipped` | 汇总计数 |
| `tests_failed_as_expected` | 失败已由 `test.fail` 覆盖的测试，计为通过 |
| `attempts_total`, `tests_retried` | 本次运行在各测试和串行组中进行了多少次尝试，以及其中多少需要多次尝试 |
| `filters_run`, `filters_timed_out`, `filters_failed`, `filters_skipped`, `filters_changed_files`, `tests_left_out_by_filters` | 本次运行应用了多少个[测试过滤器](https://e2e.com/docs/zh/filters)、多少个超时、多少个失败；带 `--changed-since` 的运行是否未调用任何过滤器（例如没有文件变化时）；变更涉及多少文件；过滤器排除了多少测试。绝不包含过滤器名称、原因、备注、路径或提交 |
| `targets`, `platforms`, `engines` | 测试目标数量、所用平台，以及引擎和版本：`web`、`ios`、`web@0.6.1`，或你自己的引擎名称和版本 |
| `steps_total`, `steps_agent`, `steps_locator`, `steps_assertion`, `steps_screen`, `steps_app`, `steps_session`, `steps_resource` | 按类型统计的步骤数 |
| `steps_agent_act`, `steps_agent_assert`, `steps_agent_extract`, `steps_agent_waitfor` | 按入口统计的智能体步骤数 |
| `tests_with_agent_steps`, `tests_with_act` | 已执行的测试中，多少运行过任意智能体步骤，多少运行过 `agent.act` |
| `agent_steps_replayed`, `agent_steps_partial`, `agent_steps_missed`, `agent_steps_uncached`, `agent_steps_vision` | 回放缓存如何服务智能体步骤、多少 `agent.act` 步骤在关闭缓存时运行，以及多少使用了像素证据 |
| `agent_miss_reasons`, `agent_handoff_reasons` | 步骤未命中缓存的原因，以及回放交给智能体继续处理的原因，使用运行器自身的原因名称：`{"no-entry": 3, "retry": 1}` |
| `tests_code_only`, `tests_replayed`, `tests_assisted`, `tests_live` | 按缓存参与方式统计的已执行测试：没有智能体步骤、所有智能体步骤都从缓存回放、智能体运行但缓存承担了部分步骤、智能体执行了所有智能体步骤 |
| `agent_actions` | 智能体执行各操作的次数，使用运行器自身的名称：`{"tap": 12, "typeText": 3, "scroll": 2}` |
| `model_gateway`, `model_provider`, `model_id`, `model_calls`, `model_tokens`, `model_cached_tokens`, `estimated_cost_usd` | 对于第一个由模型支持的步骤：提供服务的 AI SDK 提供方（Vercel AI Gateway 对应 `gateway`，以及 `openrouter.chat`、`openai.chat` 等）、厂商（`vendor/model` ID 的第一段，否则为提供方）和公开的模型 ID。随后是本次运行的总计 |
| `model_calls_act`, `model_calls_assert`, `model_calls_extract`, `model_calls_waitfor` | 按智能体入口统计的模型调用次数 |
| `cost_source` | 提供方为调用计价时为 `provider`，无人计价时为 `none`，没有模型调用的运行为 `null` |
| `artifact_bytes` | 本次运行写入的产物大小 |
| `errors`, `error_codes` | 运行级错误数量，以及本次运行中出现过的不同错误代码（`LOCATOR_NOT_FOUND`、`APP_UNREACHABLE` 等），最多 20 个 |
| `primary_error_code` | 本次运行记录的、决定其状态的第一个错误：优先使用运行级错误，否则使用失败尝试的判定，再否则使用步骤的判定。无错误的运行为 `null` |
| `error_kinds` | 对于 `ENGINE_FAILURE`、`MODEL_PROVIDER_FAILED` 和 `ERROR`：代码及按封闭列表（`auth`、`rate-limit`、`overloaded`、`timeout`、`network`、`server`、`bad-request`、`device`、`daemon`、`browser`、`permission`、`not-found`、`memory`、`other`）从消息中识别的类别，例如 `MODEL_PROVIDER_FAILED:rate-limit`。只有类别名称离开机器，绝不发送消息 |

配置特性在配置未加载时不存在。每项都是计数、布尔值或运行器自身的选项值，绝不是你编写的文本：

| 属性 | 值 |
| --- | --- |
| `config_workers`, `config_retries` | 本次运行解析出的工作进程数和重试次数 |
| `config_agents`, `config_custom_executor`, `config_separate_judge`, `config_project_tools` | 配置了多少智能体、其中是否有使用自定义执行器或独立判定模型的智能体，以及它们声明了多少个不同的项目工具 |
| `config_credentials`, `config_secrets` | 配置了多少凭据和机密值 |
| `config_cache_mode`, `config_cache_store`, `config_cache_strict` | `off`、`read-only` 或 `read-write`；`file` 或 `custom`；是否开启严格回放 |
| `config_reporters`, `config_custom_reporters`, `config_artifact_store` | 内置报告器 ID（`list`、`json`、`junit`、`markdown`）、配置添加的报告器对象数量，以及是否设置了产物存储 |
| `config_filters` | 配置声明的测试过滤器数量 |
| `config_trace_modes`, `config_video_modes` | 各测试目标中不同的录制模式（`off`、`on`、`retain-on-failure`、`on-first-retry`、`on-all-retries`） |
| `config_app_commands`, `config_environments` | 多少测试目标启动应用命令，以及不同的应用环境（`test`、`staging`、`production`） |

仅在 `e2e explore` 和 `explore()` 中，统计探索所获得的输入和发现：

| 属性 | 值 |
| --- | --- |
| `explore_ended` | 停止原因：`finished`、`skipped`、`step-limit`、`time`、`stuck` 或 `aborted` |
| `explore_max_steps`, `explore_timeout_ms` | 运行时使用的预算 |
| `explore_steps`, `explore_steps_passed`, `explore_steps_failed`, `explore_steps_blocked`, `explore_steps_exhausted` | 按结束方式统计的探索步骤 |
| `explore_assessed` | 智能体是否给出结束评估 |
| `explore_issues`, `explore_warnings`, `explore_findings_by_severity` | 按类型和严重程度统计的发现：`{"1": 0, "2": 1, "3": 0, "4": 0, "5": 1}` |

</Accordion>
<Accordion title="e2e_mcp_session，每个 MCP 会话一次">

`e2e mcp` 服务器为收到的每个 `open_session` 发送一次事件，时机是会话关闭或打开失败时。如果客户端终止服务器时会话仍然打开，则不会发送。

| 属性 | 值 |
| --- | --- |
| `client`, `client_version` | MCP 客户端自报的名称和版本（`claude-code`、`cursor-vscode` 等）。客户端自我介绍之前为 `null` |
| `outcome`, `error_code` | 成功打开的会话为 `closed`；打开失败时为 `open-failed`，并附带失败的运行器代码（`APP_UNREACHABLE`、`ENGINE_FAILURE` 等） |
| `ended_by` | `close_session` 对应 `agent`，空闲结束对应 `idle`，会话时限对应 `step`，服务器关闭对应 `server`。打开失败时为 `null` |
| `platform`, `engine`, `headed` | 与运行事件相同的测试目标平台、引擎及版本，以及是否显示 UI |
| `duration_ms`, `sessions_open` | 会话持续时间，以及它打开时还有多少其他会话处于打开状态 |
| `calls_total`, `calls_failed`, `calls` | 工具调用数、失败调用数，以及按会话自身工具名称统计的调用数：`{"observe": 4, "tap": 9, "locate": 2, "screenshot": 1}` |
| `error_codes` | 每个运行器代码导致调用失败的次数：`{"LOCATOR_NOT_FOUND": 2}`，最多 20 个代码 |

</Accordion>
</AccordionGroup>

## 绝不发送的内容

遥测绝不发送测试标题、文件路径、URL、源、指令、观测、页面内容、截图、错误消息、堆栈追踪、环境变量值、凭据或文件内容。它也绝不发送测试目标、智能体、凭据、机密值或项目工具的名称，MCP 工具参数或结果，探索目标或探索任务，以及发现内容的文字。

## 在 CI 中

CI 运行按 CI 厂商计数，而不是按机器计数，不使用偏好设置文件，也不显示通知。如果编码智能体在 Shell 中设置了 `CI`，但周围没有 CI 厂商环境，则按它所在的机器计数。

在 CI 中，只有环境变量能关闭遥测。在作业的 `env` 中设置 `E2E_TELEMETRY_DISABLED: '1'`。

## 在机群中

如果平台在新机器上为用户运行 e2e，每台机器都会被计为新用户。在这些机器上设置 `E2E_TELEMETRY_FLEET=<name>`。其事件将计为 `fleet:<name>`，与 CI 一样，不使用偏好设置文件，也不显示通知。也可以设置 `E2E_TELEMETRY_DISABLED=1`，不发送任何内容。

## 发送到哪里

事件发送到 `eu.i.posthog.com`，这是 e2e 维护者运营的 PostHog 项目。PostHog 不保留个人档案，不存储请求地址，并为每个事件跳过 GeoIP。数据以汇总形式查看。

遥测受[安全策略](https://github.com/e2e-inc/e2e/blob/main/SECURITY.md)约束。[出站连接](https://e2e.com/docs/zh/reference/security#outbound-connections)列出了运行可能建立的所有其他连接。

## 反馈

[`e2e feedback`](https://e2e.com/docs/zh/reference/cli#e2e-feedback) 不属于遥测。它会将参数中的文字作为一个 `e2e_feedback` 事件发送到同一 PostHog 项目，并附带上述机器信息。遥测开启时，它与遥测事件使用相同的匿名 ID。

已保存的 `e2e telemetry disable` 不会阻止它。`E2E_TELEMETRY_DISABLED=1` 和 `DO_NOT_TRACK=1` 则会阻止。[CLI 参考](https://e2e.com/docs/zh/reference/cli#e2e-feedback)介绍了脱敏、`--dry-run`，以及没有 `--repro` 的 Bug 报告。

## 通知

首个命令，或 `e2e/runner` 中首次调用的 `run()` 或 `explore()`，会在标准错误中打印一条说明如何退出遥测的通知，不影响 `--reporter json` 的输出。`e2e init` 和 `e2e telemetry` 不打印通知，因此通知会等到下一个命令再显示。收集的数据发生重大变化后，通知会再次显示。
