事件写入

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

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

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

标题

身体

接受的数据形状

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 乘车数据发送到名为 uber_rides 的表，您可以使用以下命令：

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

使用 JavaScript SDK

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

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

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

批量记录

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

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

你可以这样做：

telemetry.log("uber_rides", [{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 密钥超过网关速率限制