跳至主要內容
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 編輯團隊負責維護本文;產品團隊審查功能行為、範例和適用範圍。

我們如何審查文件