Telemetry

Telemetry 快速入门

给编程 Agent 装上”仪表盘”：它改完代码后自己埋点、自己发事件、自己查 SQL 验证效果，你只看结果。

这是什么?适合谁?

Telemetry（telemetry.sh）是一个面向 AI 编码场景的事件可观测性服务。传统流程里 Agent 改完代码说”好了”，你只能选择相信；Telemetry 的思路是让 Agent 自己做三件事：给代码加结构化事件埋点 → 跑真实工作流把结果事件发到 Telemetry → 用只读 SQL 把事件查回来核对值是否合理。整个过程有数据回流，“改完是否真的有效”从口说变成了可查证。

数据模型很直接：发 JSON 事件，Telemetry 按事件名自动建表并推断 schema（每行自动加 timestamp_utc），之后用 DataFusion SQL 查询、聚合、建图表仪表盘。匿名 anon_ key 无需注册即可发事件、跑同步 SQL、查表结构（仪表盘/保存查询/告警需注册账号，匿名工作区可通过私有 claim 链接事后认领，数据与 key 保持绑定）。

适合谁：重度使用 AI 编码 Agent 的开发者、想量化 Agent 改动效果（重试率、延迟、成本、失败率）的团队、需要快速搭业务事件分析而懒得自建日志管道的人。不适合：需要重型 APM（分布式 tracing、基础设施指标）的场景——它定位是”结构化事件表 + SQL 分析”，不是全栈监控。

准备工作

• 设备要求：任意可联网设备；埋点走 HTTP API，无语言限制
• 账号要求：起步无需注册——官网首页提供带真实匿名 API key 的 prompt，复制粘贴即用
• 付费要求：发事件、SQL 查询、表结构查看均免费（匿名可用）；仪表盘、保存查询、告警需免费账号
• 前置知识：基本 SQL（SELECT/GROUP BY 级别）、了解自己代码里哪些是”关键操作”
• 关键端点：POST https://api.telemetry.sh/log（发事件）、POST https://api.telemetry.sh/query（查询）

3 步快速上手

第 1 步：复制官方 prompt 给你的 Agent

打开 telemetry.sh 首页，复制那段自带真实匿名 API key 的 prompt（无 MCP server、无注册），粘贴进你的编码 Agent，让它按 prompt 里的规范给代码库埋点。

第 2 步：跑真实工作流并发事件

让 Agent 为关键操作（如订单完成、任务执行、Agent 工具调用）各发一个结构化事件，例如：

telemetry.log("checkouts", {
  status: "completed",
  duration_ms: 842,
  release: "v43",
})

注意：要跑一个真实工作流让它产生真事件；合成 telemetry_quickstart 事件只能验证通道，不能验证业务埋点。

第 3 步：SQL 查询验证

用同一个 key 跑只读 SQL 确认事件真的入库且值合理：

SELECT status, COUNT(*) AS runs
FROM agent_runs
GROUP BY status
ORDER BY runs DESC

预期产出：事件表存在、预期列齐全、行值合理——Agent 改动的效果有了数据证据。

常见踩坑

• 现象：发事件返回 200 就以为成功了。 原因：HTTP 200 只是投递确认，不证明数据可用。 解决：必须再做一次 SQL 回读（官方 skill 明确要求”send response alone is not proof”），核对列与值。

• 现象：发空批次 data: [] 报 HTTP 400。 原因：这是 empty_batch 校验错误，不是负载过大，也不是”成功的空操作”。 解决：批次至少含一个事件再发。

• 现象：想建仪表盘但 Agent 反复重试报 anonymous_account_required。 原因：仪表盘/保存查询/告警需要注册账号，匿名 key 权限不够。 解决：用工作区私有 claim 链接认领账号（或在 register 页输入已有匿名 key），认领后原 key 与数据不变；Agent 应把”建仪表盘”报告为 pending signup 而非重试。

• 现象：时间字段查询结果混乱。 原因：缺省时 Telemetry 自动加 timestamp_utc；如果你又传业务时间戳，命名不当会造成两个”timestamp”。 解决：业务时间用有语义的名字（scheduled_at、completed_at），避免再叫 timestamp。

• 现象：null 字段时有时无。 原因：入库规范化会递归删除 null、{}、[]，但保留 ""、0、false。 解决：写查询前先了解这条规则，别把”字段缺失”误判为数据丢失。

初级用法

• Agent 改动自证：让 Agent 改完队列逻辑后埋”job finished”事件，再用 SQL 对比重试率变化。
• LLM 成本追踪：每次模型调用发 input_tokens / output_tokens / cost_usd 事件，按 feature 维度算成本。
• 免注册探索：用匿名 key 直接跑通”发事件→查表→聚合”全链路，满意再注册认领。

高级玩法

• AI 辅助 SQL：在查询工作区用自然语言描述问题，Telemetry 按表元数据起草 DataFusion 查询或图表建议，生成后可读可改再保存。
• Dashboard + 告警：注册后用 JSON API 定义仪表盘（widgets 内嵌 SQL、图表类型、布局），配上告警把异常率、p95 延迟变成可订阅信号。
• 宽事件设计：按官方指南把 dimensions（route/outcome）、measures（latency_ms/cost_usd）、identity（request_id/trace_id）分层建模，为后续 join 与漏斗分析留好结构。
• 官方 Agent Skill：telemetry.sh/skill.md 提供完整 skill（含验收要点与失败模式），把它装进编码 Agent 即可让它自主完成整套埋点-验证-建盘流程。

小技巧

1. 表名自动规范化为小写 snake_case，别用驼峰命名事件。
2. 每个关键操作只发一个”终态事件”（outcome 已知时），比过程事件流更省也更清晰。
3. 默认别把 prompt 原文、密钥、用户隐私塞进事件——官方指南明确建议排除。
4. Explore 标签页可以不写 SQL 先过滤事件、搭图表，适合非技术同事。
5. 匿名工作区的 claim 链接要保存好——丢了就找不回该工作区。

常见问题 FAQ

Q1: Telemetry 免费吗？

A: 发事件、SQL 查询、查表结构匿名即可用（免费）；仪表盘、保存查询、告警需要免费注册账号。官网未标注强制付费档，具体商用限额以官方定价页为准。

Q2: 和传统日志（ELK/ClickHouse）有什么区别？

A: 不用自建管道与集群：JSON 直接入表、schema 自动推断、SQL 即查即用；代价是它不做全栈 APM（tracing/基础设施指标），定位是”结构化事件表 + 事件分析”。

Q3: 必须配 MCP server 吗？

A: 不用。官方主打”无 MCP、无注册”——一段带 key 的 prompt 贴进 Agent 即可。

Q4: 支持哪些语言？

A: 事件走 HTTP POST（api.telemetry.sh/log），任何能发 HTTP 的语言都能埋点；官网示例为 JavaScript 风格 SDK 调用。

Q5: 数据安全吗？

A: 你自己控制事件内容；官方指南建议默认排除密钥、原始请求体、prompt 文本与客户私有内容。敏感数据建议脱敏后再发。

参考链接

• Telemetry 官网
• 快速开始文档
• Telemetry Skill（Agent 埋点规范）
• SQL 可观测性指南
• AI 辅助查询