傳送您的第一個結構化事件
本演練將一個合成 API 結果傳送到 Telemetry。目標不僅僅是收到 200 回應。首先是一個事件合約，該合約可以支援 SQL、儀表板、警示和後續除錯，而無需收集原始請求負載。
開始之前
在 團隊設定 → API 金鑰 中建立一個團隊和一個 write 範圍的金鑰。將值儲存在本地環境變數或秘密管理器中：
export TELEMETRY_API_KEY="replace-with-your-key"
請勿在瀏覽器 JavaScript、移動應用程式、公共儲存庫或螢幕截圖中公開團隊金鑰。有關範圍和旋轉指南，請參閱 API 金鑰與身分驗證。
選擇一個已完成的工作流程
從應用程式知道結果的邊界開始。良好的首要活動包括：
api_request_completedbackground_job_completedwebhook_processing_completedcheckout_completedagent_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 是一個路由範本，而不是包含識別符號的原始 URL。該事件包括分類結果欄位和安全相關識別符號，但沒有請求正文、授權標頭、cookie 或客戶內容。
使用 cURL 傳送事件
curl https://api.telemetry.sh/log \
-H "Authorization: Bearer $TELEMETRY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"table": "api_request_completed",
"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("api_request_completed", {
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 中，而不是混合秒和毫秒。
成功意味著什麼
成功傳送僅證明 API 接受了該事件。繼續使用 驗證事件攝取 檢查表名稱、推斷型別、生成的時間戳和確切行。在第一個事件合約可查詢且安全之前，不要檢測更多工作流程。