事件摄取故障排除
当事件未按预期出现时，请单独请求传递、身份验证、有效负载验证、架构兼容性和查询新鲜度。成功的应用程序操作并不能证明遥测摄取成功，并且接受的 HTTP 请求也不能证明后面的查询正在查看相同的表和时间范围。
诊断时使用具有唯一安全标识符的合成事件。请勿将生产负载复制到日志、票证或命令历史记录中。
1. 捕获实际的HTTP结果
暂时发送一个带有 cURL 的事件，以便您可以看到响应状态和正文：
curl -i -X POST https://api.telemetry.sh/log \
-H "Content-Type: application/json" \
-H "Authorization: $API_KEY" \
-d '{
"table": "ingestion_diagnostics",
"data": {
"event_id": "diagnostic-2026-07-28-01",
"source": "manual_check",
"status": "expected"
}
}'
将 API 密钥保存在环境变量中。收集诊断信息时，请勿将其粘贴到有效负载中或打印它。
重试之前解释状态：
400表示 JSON、表名、时间戳、数据形状或字段类型必须更改。重试同一身体无法修复它。401表示密钥丢失、格式错误、无效或已撤销。403表示该键没有操作的写入范围。429表示超出当前请求速率或配额。在提供时遵守Retry-After并使用带抖动的有界指数退避。5xx表示服务器端对其他有效请求的失败。重试有限次数，而不会无限期地阻止主应用程序。
请阅读 速率限制和 API 错误 了解完整的客户政策。
2. 确认目的表
日志API规范了请求的表名：空格变成下划线，字母变成小写。标准化后，只有小写 ASCII 字母、数字和下划线有效。
例如，Checkout Events 变为 checkout_events。查询猜测的名称（例如 CheckoutEvents）将不会检查相同的目的地。
在诊断过程中，在请求中使用简单的显式名称，然后检查 Telemetry 中的表列表或模式。如果两个服务应写入一个表，请确保两者使用相同的规范化名称和字段类型。
3. 验证接受的数据形状
data 属性可能是：
- 一个 JSON 对象
- JSON 对象的数组
- 解码为对象的 JSON 字符串
- 包含对象和 JSON 字符串的数组，每个字符串都解码为对象
顶级数字、布尔值、null 以及解码为这些值的字符串将被拒绝。数组不能包含任意标量值。超出记录限制的深层嵌套有效负载也会被拒绝。
将失败事件减少到三个无害的字段。以小组形式重新添加字段，直到请求再次失败。这会隔离无效形状，而不会暴露原始客户负载。
4. 检查时间戳行为
Telemetry 在缺失或为空时添加 UTC timestamp。当 Unix 时间戳整数和数字字符串在支持的范围内时，它们被解释为 Unix 秒并标准化为 RFC 3339。客户端提供的 timestamp_utc 被删除，因为该字段由查询层管理。
如果查询窗口外出现新事件：
- 删除自定义
timestamp并发送新的合成事件 - 通过生成的
timestamp_utc进行查询 - 比较应用程序时钟、源时间戳和查询时区
- 检查原始时间戳是否意外是毫秒而不是秒
当源事件时间必须与接收时间分开保存时，请使用 使用时间戳。
5. 检查模式兼容性
第一个接受的事件建立字段类型。添加新的可选字段与将现有字段从数字更改为字符串、布尔值、时间戳或嵌套对象不同。
检查表架构并逐个字段比较失败的有效负载。常见的漂移包括：
- 一个生产者以整数形式发送的标识符，另一个生产者以字符串形式发送的标识符
- 在一个版本中作为数字发送的持续时间，在另一个版本中作为
"842ms"发送 - 嵌套对象替换为标量
- 在整数美分和小数货币单位之间变化的货币值
- 状态更改类型，因为 SDK 以不同方式序列化枚举
当概念真正改变类型或单位时，请添加版本化字段名称并有意迁移查询。读取 事件数据类型与可空性 和 模式演化。
6. 隔离批量故障
对于被拒绝的批次，用一个小的合成子集进行重现。如果需要，拆分批次直至识别出不兼容的项目。在重试相同的逻辑事件时保持稳定的 event_id，以便可以测量重复的传递。
不要默默地为每次网络尝试分配新的标识符。这会将一个结果变成多行，并使重试恢复、计费总计和渠道变得不可靠。使用 重复事件 ID SQL 配方 审核重复项。
7. 使用SQL验证事件
查询准确的诊断标识符和广泛的 UTC 范围：
SELECT
event_id,
source,
status,
timestamp_utc
FROM ingestion_diagnostics
WHERE event_id = 'diagnostic-2026-07-28-01'
AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC;
如果该行存在但仪表板为空，请比较仪表板的表、筛选器、时间范围和预期字段类型。如果没有出现来自整个源的新行，请使用 摄入新鲜度配方 使间隙可见。
预防清单
- 将服务器端密钥保留在浏览器捆绑包之外，并将其范围限制为所需的操作
- 捕获摄取失败的安全状态、端点、请求 ID 和错误类别
- 使用稳定的表名称、事件名称、字段类型和显式单位
- 在生产前通过综合或暂存检查发送架构更改
- 限制重试，这样遥测就不会耗尽工作人员的精力或改变已完成的客户响应
- 与业务仪表板分开监控新鲜度和重复标识符