跳转到内容
Telemetry
浏览文档

API 参考更新于 2026年10月1日阅读约需 3 分钟

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

打开 Claude Code、Codex、Cursor 或其他编码代理的集中提示包,然后将其适应此处介绍的工作流程。

本页内容
  1. 接受的数据形状
  2. 服务器端规范化
  3. cURL 的用法示例
  4. 使用 JavaScript SDK
  5. 批量记录
  6. 常见错误

事件写入

这些示例使用保留的示例表 telemetry_quickstart 中的虚构数据。它们验证 API 行为,不代表应用已经接入。为自己的应用选择工作流表,并从实际操作发送事件。

日志 API 是您将事件摄取到 Telemetry 中的方式。将其用于应用程序事件、用户活动、指标或结构化日志。

Telemetry 在存储前规范表名、补充时间戳,并移除 null 值、空对象和空数组。

发布 https://api.telemetry.sh/log

标题

名称 类型 描述
内容类型 字符串 应用程序/json
授权 字符串 您的 API 密钥,作为原始密钥或 Bearer <key>

身体

名称 类型 描述
表 字符串 目标表名称。空格转换为下划线,字母小写,标准化后仅允许使用小写 ASCII 字母、数字和 _。
数据 JSON 事件有效负载。支持的形状包括 JSON 对象、JSON 对象数组、解码为 JSON 对象的 JSON 字符串或将 JSON 对象与解码为 JSON 对象的 JSON 字符串混合的数组。

接受的数据形状

API 接受:

  • 单个 JSON 对象
  • JSON 对象的数组
  • 本身解析为 JSON 对象的 JSON 字符串
  • 包含 JSON 对象和解析为 JSON 对象的 JSON 字符串的数组

API 拒绝:

  • 顶级数字、布尔值和 null
  • JSON 解码为非对象值(例如数组、数字、布尔值或 null)的字符串
  • 包含非对象、非字符串项的数组
  • 包含解码为非对象值的 JSON 字符串的数组
  • JSON 有效负载嵌套深度超过 64 层
  • 空事件批次,data: []

服务器端规范化

当 data 包含 JSON 对象时,Telemetry 在摄取之前应用这些规则:

  • 如果缺少 timestamp,则添加当前 UTC 时间
  • 如果 timestamp 是 null,则将其替换为当前 UTC 时间
  • 如果 timestamp 是 Unix 时间戳整数或数字字符串,则将其解释为 Unix 秒并将其转换为 RFC 3339
  • 删除 timestamp_utc(如果存在)
  • 递归删除 null 值、空对象和空数组。保留 ""、0 和 false。

示例:

  • Telemetry Events 变为 telemetry_events
  • timestamp: 1700000000 成为 RFC 3339 时间戳字符串
  • { "user": "alice", "meta": null } 存储时没有 meta

cURL 的用法示例

要使用 cURL 将 Uber 乘车数据发送到名为 telemetry_quickstart 的表,您可以使用以下命令:

curl -X POST https://api.telemetry.sh/log \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "table": "telemetry_quickstart",
    "data": {
      "city": "paris",
      "price": 42
    }
  }'

使用 JavaScript SDK

我们建议使用我们的 SDK 以获得更好的开发人员体验。以下是如何使用我们的 JavaScript SDK 的示例:

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

await telemetry.log("telemetry_quickstart", {
  city: "paris",
  price: 42
});

批量记录

您还可以传入对象数组来批量摄取事件。这对于限制对 API 的请求数量很有用。例如,代替:

await telemetry.log("telemetry_quickstart", { a: 1 })

你可以这样做:

await telemetry.log("telemetry_quickstart", [{a: 1}, {a: 2}])

这会将数据摄取为两行。

常见错误

  • 400 Bad Request 如果 JSON 主体无效
  • 400 Bad Request 如果表名规范化后包含无效字符
  • 400 Bad Request(如果 data 不属于受支持的形状)
  • 如果 data 是空数组,返回 400 Bad Request 和错误码 empty_batch。请至少发送一个事件。减小请求体无法修复此错误。
  • 400 Bad Request 如果 data 中的 JSON 字符串解码为非对象值
  • 如果 Unix 时间戳超出支持的范围,则为 400 Bad Request
  • 401 Unauthorized(如果 API 密钥丢失或无效)
  • 429 Too Many Requests 如果 API 密钥超过网关速率限制

相关功能

记录稳定的事件名称、类型明确的字段,以及经过隐私审核的上下文。

页面作者和参考资料

Telemetry 编辑团队负责维护本文;产品团队审核功能行为、示例和适用范围。

我们如何审核文档