事件寫入

日誌 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 金鑰超過閘道器速率限制