验证事件摄取和架构

接受的 API 请求并不是仪器检查的结束。在将事件复制到更多路由、工作人员或服务之前，请验证结果表和行。

此页面假设您从发送您的第一个结构化事件发送了合成 telemetry_quickstart 事件。

使用匿名 anon_… 密钥？跳至下方的通过 API 验证。同一密钥可在首次发送后 24 小时内读取事件。要使用团队界面，请创建账户并保留试用。在其他浏览器中注册前，选择**已有匿名 API 密钥？**并输入密钥。

找到桌子

打开您的 Telemetry 团队，选择表格，然后打开 telemetry_quickstart。如果该表不存在：

确认 API 请求返回成功响应。
确认密钥属于目标团队并且具有可写范围。
检查规范化后的确切表名。
使用新的合成 request_id 重试一次。
在更改架构之前遵循事件摄取故障排除。

避免在没有新标识符的情况下重复发送同一事件；重试可能会使以后的计数变得不明确。

检查推断的架构

合成的 API 示例应公开类似于以下内容的字段：

领域	预期分析类型	检查
`timestamp_utc`	时间戳	一致添加并以 UTC 格式存储
`route_template`	文字	包含有界路由模板，而不是原始 URL
`status_code`	整数	可以支持数值比较
`latency_ms`	数值	到处都使用毫秒
`status`	文字	使用少量记录的词汇
`request_id`	文字	连接相关事件而不暴露秘密

如果某个重要字段的类型错误，请在发送产量之前停止并修复生产者。从数字更改为任意文本的字段可能会使保存的 SQL 和图表更难以推理。

检查确切的行

使用 Samples或Table 视图并找到 request_id = req_demo_001。确认：

该行属于预期的环境和版本。
latency_ms 是 184，而不是 0.184 或 184000。
该路线不包含真实的报告或帐户标识符。
不包含授权标头、cookie、请求正文、秘密、提示或私人客户内容。
生成的时间与发送窗口匹配。

预期行是事件契约有效的证据。它不是性能基准或代表性的生产分布。

通过API验证

进行以下 API 检查时，请在可信服务器或本地终端使用具有读取权限的密钥。Ingest only 密钥只能发送事件，不能列出数据表、查看结构或执行查询。不要将具有读取权限的密钥放入浏览器或移动客户端代码；使用团队界面验证通过 Ingest only 密钥发送的事件。

您还可以通过编程方式检查表和模式：

curl https://api.telemetry.sh/tables \
  -H "Authorization: Bearer $TELEMETRY_API_KEY"

然后请求表架构：

curl https://api.telemetry.sh/tables/telemetry_quickstart/schema \
  -H "Authorization: Bearer $TELEMETRY_API_KEY"

使用同一工作区中具有读取权限的密钥查询刚发送的事件。如果使用了其他 request_id，请替换下面的 req_demo_001。此查询检查最近 24 小时，最多返回十条匹配记录：

curl https://api.telemetry.sh/query \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"query":"SELECT timestamp_utc, request_id, route_template, status_code, latency_ms, release, environment FROM telemetry_quickstart WHERE request_id = 'req_demo_001' AND timestamp_utc >= now() - INTERVAL '24 hours' ORDER BY timestamp_utc DESC LIMIT 10"}
JSON

检查响应是否包含 status: "success"，以及 data 中是否有预期记录，包括 latency_ms: 184。空的 data 数组不能证明事件已写入；请核对密钥、表名、标识符和发送时间。多条匹配记录可能来自重试，不代表多个独立的应用操作。成功读回示例只验证这次模拟测试。接下来，为一个真实的应用操作添加事件记录，并查询对应的业务表。

使用可读密钥进行自动化验证。表格 API 记录分页、规范化、保留和模式响应。

记录合同

在扩展仪器之前，写下：

事件名称和业务粒度。
必填和可选字段。
字段类型和单位。
允许的状态和错误类别。
同一性和相关性字段。
禁止的字段。
所有者和预期保留期限。

继续编写您的第一个 SQL 查询。有关架构更改策略，请参阅模式演化。

让编程智能体使用这篇文档