傳送您的第一個結構化事件

這個範例會將一個模擬的 API 執行結果傳送到 Telemetry。收到 200 回應後，還要確認事件欄位能用於 SQL、儀表板、警示及除錯。事件中不要包含原始請求內容。

開始之前

已從首頁複製設定提示詞？使用其中的 anon_… 金鑰，即可在沒有帳戶的情況下傳送和查詢事件。

如果已有帳戶，請在團隊設定 → API 金鑰中建立 read-and-write 金鑰，因為下一步需要讀取事件。只傳送事件的應用程式可使用 ingest 金鑰。

將金鑰存放在本機環境變數或機密管理工具中：

export TELEMETRY_API_KEY="replace-with-your-key"

匿名金鑰、唯讀金鑰及讀寫金鑰都應保密。瀏覽器和行動應用程式記錄事件時，可以使用 Ingest only 金鑰；它不能查詢或管理資料。這類金鑰仍可能被複製並用來傳送不需要的事件，請監控使用情況，並在遭到濫用時撤銷。權限與金鑰輪替方式，請參閱 API 金鑰與身分驗證。

選擇一個已完成的工作流程

先選擇一個應用程式已知道執行結果的時間點。適合的第一個事件包括：

• api_request_completed
• background_job_completed
• webhook_processing_completed
• checkout_completed
• agent_run_completed

使用代表已完成操作的事件名稱，避免 something_happened 這類籠統訊息。固定的事件名稱，能讓產生事件的程式與查詢對「每筆紀錄代表什麼」有一致的定義。

這個範例使用一個模擬的 API 請求：

{
  "route_template": "/api/reports/:report_id",
  "method": "POST",
  "status": "success",
  "status_code": 200,
  "latency_ms": 184,
  "release": "local-demo",
  "environment": "development",
  "request_id": "req_demo_001"
}

URL 使用路由範本，不包含真實識別碼。事件記錄狀態分類與不含機密資訊的關聯識別碼，不包含請求本文、授權標頭、cookie 或客戶內容。

使用 cURL 傳送事件

curl https://api.telemetry.sh/log \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "telemetry_quickstart",
    "data": {
      "route_template": "/api/reports/:report_id",
      "method": "POST",
      "status": "success",
      "status_code": 200,
      "latency_ms": 184,
      "release": "local-demo",
      "environment": "development",
      "request_id": "req_demo_001"
    }
  }'

如果使用的 SDK 或 API 版本與範例不同，請以事件寫入 API 說明的請求格式為準。

從 JavaScript 傳送相同的事件

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("telemetry_quickstart", {
  route_template: "/api/reports/:report_id",
  method: "POST",
  status: "success",
  status_code: 200,
  latency_ms: 184,
  release: "local-demo",
  environment: "development",
  request_id: "req_demo_001"
});

這個範例在可信任的伺服器端程式碼中初始化 SDK。不同服務應使用一致的欄位名稱與單位。例如，將耗時存放在 latency_ms，統一使用毫秒。

成功意味著什麼

匿名查詢在首個事件後可用 24 小時。請在 7 天內建立帳戶，以保留事件和原金鑰。註冊會識別目前瀏覽器中的試用。在其他瀏覽器中，先選擇已有匿名 API 金鑰？，貼上金鑰並點擊尋找我的資料，再註冊。已有帳戶的使用者可在保留我的資料中復原金鑰，然後登入。未傳送事件的試用在建立 7 天後到期。

傳送成功只代表 API 接受了事件。接著閱讀驗證事件寫入，檢查資料表名稱、推斷的型別、產生的時間戳記及指定紀錄。先確認第一個事件可查詢且不含敏感內容，再為更多流程加入事件紀錄。

這個範例是虛構資料，只用來檢查 API 呼叫是否正常。要完成應用程式整合，請在一個真實流程完成時記錄事件，實際執行該流程，再查詢已儲存的事件。只有 telemetry_quickstart 資料表中的一筆資料並不代表設定已完成。

若要設計更完整的資料結構，請閱讀設計事件結構。敏感欄位的處理方式，請參閱遮蔽敏感資料。