批次處理、背壓與優雅關閉
批次處理可以減少請求開銷，但也會改變故障影響和交付延遲。無限制地對事件進行排隊的處理程序可能會在中斷期間消耗記憶體。不考慮待處理工作而退出的處理程序可能會默默地丟失其最新事件。
Telemetry 的日誌 API 接受一個 JSON 物件或一組 JSON 物件。 API 功能並不要求每個生產者都維護記憶體中的後台佇列。
從直接等待交付開始
對於低容量工作流程，傳送一個緊湊的結果事件並在有限的超時時間內等待請求。這是最容易推理和測試的交付路徑。
當測量顯示請求開銷很大或現有工作人員已經擁有持久收集緩衝區時進行批次處理。優先選擇小型、有時間限制的批次，而不是無限期等待大小閾值的大型佇列。
await telemetry.log("api_request_completed", [
{
event_id: "evt_101",
route_template: "/api/projects/:id",
status: "success",
latency_ms: 84,
},
{
event_id: "evt_102",
route_template: "/api/projects/:id",
status: "failed",
latency_ms: 912,
error_type: "database_timeout",
},
]);
保持批次中的每個物件與相同的資料表模式相容。一項無效或不相容的專案可能會使整個請求的結果變得複雜。
繫結每個佇列
如果應用程式緩衝事件，請定義：
- 最大排隊事件計數和序列化位元組。
- 傳送部分批次之前的最長期限。
- 最大批次大小。
- 請求超時並重試預算。
- 溢位行為。
- 關閉行為。
溢位行為必須是明確的。丟棄最舊的低優先順序診斷事件、對嘈雜的成功路徑進行取樣、阻止專用遙測工作人員以及堅持持久發件箱會產生不同的操作後果。不要讓無界佇列透過耗盡處理程序記憶體來決定。
透過安全的診斷路徑記錄佇列深度、最早的事件年齡、傳送的批次、接受的事件、丟棄的事件以及永久傳送失敗。避免透過同一失敗佇列遞迴傳送遙測佇列自己的失敗事件。
將背壓與客戶工作分開
對於大多數產品分析，遙測交付不應消耗客戶請求的全部延遲預算。使用短有界切換或應用程式擁有的工作執行緒。如果佇列已滿，請應用記錄的溢位策略，而不是無限期等待。
對於計費或批准的審查事件，請使用耐用的發件箱並對發件箱工作人員施加背壓，而不是丟失業務事件。 事件傳遞和冪等性指南 解釋了跨嘗試的穩定事件標識。
故意處理關機
在正常關閉訊號上：
- 停止接受新工作。
- 允許執行中的應用程式工作達到定義的邊界。
- 傳送或保留剩餘的遙測批次。
- 強制執行關閉期限。
- 記錄無法交付的數量。
除非特定的 SDK 公開並記錄了這一保證，否則請勿要求客戶沖洗保證。當客戶端立即傳送每個呼叫時，等待所有追蹤的呼叫與重新整理內部佇列不同。無伺服器和邊緣執行時可能會在回應後凍結執行，因此請使用執行時支援的後台工作機制或在需要事件時在返回之前傳遞。
驗證過載行為
測試完整批次、部分時間觸發批次、429、503、連線超時、佇列溢位以及帶有掛起事件的處理程序終止。確認重試嘗試保留事件 ID，並且沒有故障路徑列印憑據或原始負載。
使用 事件攝取故障排除指南 驗證回應，使用 遙測音量指南 衡量是否確實需要分批或取樣。