事件攝取故障排除
當事件未按預期出現時，請單獨請求傳遞、身分驗證、有效負載驗證、架構相容性和查詢新鮮度。成功的應用程式操作並不能證明遙測攝取成功，並且接受的 HTTP 請求也不能證明後面的查詢正在檢視相同的資料表和時間範圍。
診斷時使用具有唯一安全識別符號的合成事件。請勿將生產負載複製到日誌、票證或命令歷史記錄中。
1. 捕獲實際的HTTP結果
暫時傳送一個帶有 cURL 的事件，以便您可以看到回應狀態和正文：
curl -i -X POST https://api.telemetry.sh/log \
-H "Content-Type: application/json" \
-H "Authorization: $API_KEY" \
-d '{
"table": "ingestion_diagnostics",
"data": {
"event_id": "diagnostic-2026-07-28-01",
"source": "manual_check",
"status": "expected"
}
}'
將 API 金鑰儲存在環境變數中。收集診斷資訊時，請勿將其貼上到有效負載中或列印它。
重試之前解釋狀態：
400表示 JSON、資料表名、時間戳、資料形狀或欄位型別必須更改。重試同一身體無法修復它。401表示金鑰丟失、格式錯誤、無效或已撤銷。403表示該鍵沒有操作的寫入範圍。429表示超出當前請求速率或配額。在提供時遵守Retry-After並使用帶抖動的有界指數退避。5xx表示伺服器端對其他有效請求的失敗。重試有限次數，而不會無限期地阻止主應用程式。
請閱讀 速率限制和 API 錯誤 瞭解完整的客戶政策。
2. 確認目的資料表
日誌API規範了請求的資料表名：空格變成下劃線，字母變成小寫。標準化後，只有小寫 ASCII 字母、數字和下劃線有效。
例如，Checkout Events 變為 checkout_events。查詢猜測的名稱（例如 CheckoutEvents）將不會檢查相同的目的地。
在診斷過程中，在請求中使用簡單的顯式名稱，然後檢查 Telemetry 中的資料表列表或模式。如果兩個服務應寫入一個資料表，請確保兩者使用相同的規範化名稱和欄位型別。
3. 驗證接受的資料形狀
data 屬性可能是：
- 一個 JSON 物件
- JSON 物件的陣列
- 解碼為物件的 JSON 字串
- 包含物件和 JSON 字串的陣列，每個字串都解碼為物件
頂級數字、布林值、null 以及解碼為這些值的字串將被拒絕。陣列不能包含任意標量值。超出記錄限制的深層巢狀有效負載也會被拒絕。
將失敗事件減少到三個無害的欄位。以小組形式重新新增欄位，直到請求再次失敗。這會隔離無效形狀，而不會暴露原始客戶負載。
4. 檢查時間戳行為
Telemetry 在缺失或為空時新增 UTC timestamp。當 Unix 時間戳整數和數字字串在支援的範圍內時，它們被解釋為 Unix 秒並標準化為 RFC 3339。客戶端提供的 timestamp_utc 被刪除，因為該欄位由查詢層管理。
如果查詢視窗外出現新事件：
- 刪除自定義
timestamp併傳送新的合成事件 - 透過生成的
timestamp_utc進行查詢 - 比較應用程式時鐘、源時間戳和查詢時區
- 檢查原始時間戳是否意外是毫秒而不是秒
當源事件時間必須與接收時間分開儲存時，請使用 使用時間戳。
5. 檢查模式相容性
第一個接受的事件建立欄位型別。新增新的可選欄位與將現有欄位從數字更改為字串、布林值、時間戳或巢狀物件不同。
檢查表架構並逐個欄位比較失敗的有效負載。常見的漂移包括：
- 一個生產者以整數形式傳送的識別符號，另一個生產者以字串形式傳送的識別符號
- 在一個版本中作為數字傳送的持續時間，在另一個版本中作為
"842ms"傳送 - 巢狀物件替換為標量
- 在整數美分和小數貨幣單位之間變化的貨幣值
- 狀態更改型別，因為 SDK 以不同方式序列化列舉
當概念真正改變型別或單位時，請新增版本化欄位名稱並有意遷移查詢。讀取 事件資料型別與可空性 和 模式演化。
6. 隔離批次故障
對於被拒絕的批次，用一個小的合成子集進行重現。如果需要，拆分批次直至識別出不相容的專案。在重試相同的邏輯事件時保持穩定的 event_id，以便可以測量重複的傳遞。
不要默默地為每次網路嘗試分配新的識別符號。這會將一個結果變成多行，並使重試恢復、計費總計和渠道變得不可靠。使用 重複事件 ID SQL 配方 審查重複項。
7. 使用SQL驗證事件
查詢準確的診斷識別符號和廣泛的 UTC 範圍：
SELECT
event_id,
source,
status,
timestamp_utc
FROM ingestion_diagnostics
WHERE event_id = 'diagnostic-2026-07-28-01'
AND timestamp_utc >= now() - INTERVAL '24 hours'
ORDER BY timestamp_utc DESC;
如果該行存在但儀表板為空，請比較儀表板的資料表、篩選器、時間範圍和預期欄位型別。如果沒有出現來自整個源的新行，請使用 攝入新鮮度配方 使間隙可見。
預防清單
- 將伺服器端金鑰保留在瀏覽器捆綁包之外，並將其範圍限制為所需的操作
- 捕獲攝取失敗的安全狀態、端點、請求 ID 和錯誤類別
- 使用穩定的資料表名稱、事件名稱、欄位型別和顯式單位
- 在生產前透過綜合或暫存檢查傳送架構更改
- 限制重試，這樣遙測就不會耗盡工作人員的精力或改變已完成的客戶回應
- 與業務儀表板分開監控新鮮度和重複識別符號