@evlog/telemetry 将 evlog 的 wide-event 模型带到了在他人机器上运行的工具中：CLI、GitHub Actions、开发脚本和 CI 作业。理念与 HTTP 日志记录相同：一次命令执行 → 一个结构化事件，而不是一连串分析调用。
pnpm add @evlog/telemetry
bun add @evlog/telemetry
yarn add @evlog/telemetry
npm install @evlog/telemetry
你会自动获得命令名称、经过清理的标志、持续时间和结果。只有在需要额外计数器时才调用 telemetry.set()，数字和布尔值默认即可。永远不会读取原始 argv；披露内容根据运行时配置生成，因此不会与实际收集的内容产生偏差。
为我的 CLI 或脚本添加匿名遥测
从 CLI 到你的后端
磁盘 outbox（~/.config/{toolName}/telemetry/outbox.ndjson）是一个可靠性缓冲区，而不是遥测长期存放的位置。每次运行都会在本地追加一条事件，然后 HTTP drain 会将积压数据 POST 到你的采集端点。生命周期很短的 CI 作业和离线机器会在下次调用时继续排空。
- 运行：
my-tool doctor在用户的机器上执行 - 捕获：
@evlog/telemetry清理标志、检查同意状态，并记录一个RunEvent - 缓冲：事件追加到
~/.config/{toolName}/telemetry/outbox.ndjson - 发送：刷新时，将
{ events: RunEvent[] }POST 到你的采集 URL - 验证：
parseIngestBody()对工具和自定义键执行允许列表校验（接收） - 存储：根据
idempotencyKey去重，然后写入 DB／warehouse／evlog drain - 确认：收到
2xx后，已交付的键会从 outbox 中移除
CLI → @evlog/telemetry → outbox.ndjson → POST /ingest → validate → store
在你配置端点并且服务器返回成功状态之前，不会发送任何内容。在此之前，事件会保留在 outbox 中（或者在选择退出时被清除）。
为什么安装它
你可以自行接入匿名使用遥测：outbox 文件、同意标志、标志清理、披露 Markdown、接收验证、首次运行通知。或者添加一个依赖，直接获得内置 evlog 实践方案。
约 28 KB 你能得到什么
| 发布体积 | ~28 KB ESM（@evlog/telemetry），~8.6 KB gzip —— 独立运行，不依赖 evlog 核心 |
| 仅服务器摄取 | @evlog/telemetry/ingest ~5 KB（~1.7 KB gzip）——在不把 citty 绑定引入你的 API 的情况下使用 parseIngestBody() |
| 运行时依赖 | 仅 citty + std-env —— 二者均为 sideEffects: false，可进行 ESM 树摇优化 |
| Node | 18+ · ESM · 包级别 sideEffects: false |
适用于代码运行的任何地方
| 使用场景 | 入口 | 集成行数 |
|---|---|---|
| citty CLI | 根命令上的 withTelemetry() | 一个包装器 + 可选的 defineTelemetryCommands() |
| 脚本／迁移器 | createTelemetry() + t.run() | 为每次逻辑运行包一层 |
| GitHub Actions | createGitHubActionsTelemetry() | 与脚本相同；自动注入 ghaAction／ghaEvent |
| 你的 API（摄取） | 来自 @evlog/telemetry/ingest 的 parseIngestBody() | 一个校验器 + 一个 POST 路由 |
不绑定任何框架。不使用 PostHog／Segment／自定义分析 SDK。无需维护第二套 schema，因为披露内容是从 CLI 在运行时使用的同一 collect 配置生成的。
你无需再构建的内容
- 隐私安全的标志采集（从不读取原始
argv） DO_NOT_TRACK／EVLOG_TELEMETRY／带出站文件清理的持久化退出- 带锁文件、过期锁恢复和积压清空的磁盘出站文件
- 自动生成的披露（
TELEMETRY.md+telemetry status） - 带退出提示的首次运行通知
- 带允许列表字符串字段的类型化
telemetry.set() - 与 CLI 信封保持一致的服务端摄取校验
- 硬性保证：遥测永不抛错，永不阻塞退出
价值回报
一旦摄取上线，你就能回答 CLI 作者通常只能猜测的产品问题：
- 实际使用了哪些命令（
doctorvssyncvstelemetry status） - 运行在哪些地方失败（
outcome、errorCode、版本分布） - 操作耗时多久（每个命令的
durationMs） - 还有哪些版本仍在被使用（每个事件上的
tool.version） - CI 还是本地开发占主导（
env.ci、env.agent、env.tty）
所有信息都来自每次运行的一个 wide event，与服务器端的 evlog 使用相同的思维模型，无需将浏览器分析技术栈强行接入终端工具。
examples/telemetry-playground：pnpm run cli -- doctor，使用 EVLOG_TELEMETRY_DEBUG=1 检查负载，使用 telemetry status 查看披露内容