Sentry 開發者貢獻指南 - SDK 開發(客戶端報告)
Client reports 是一種協議特性，允許客戶端向 Sentry 發送關于自己的狀態報告。它們目前主要用于為從未發送的事件發出結果。
基本操作
Client 報告作為 envelope 項發送給 Sentry， 通常是作為單獨的 envelope 或已安排的 envelope 之一。它們不應該被發送得太頻繁，但也不能太少。它們的主要目的是讓人們了解 SDK 端發生的影響用戶體驗的事情。
例如，SDK 可能會在 SDK 中的幾個地方丟棄事件，而這種事件丟失對客戶來說可能是不可見的。 Client 報告讓 SDK 發出此類事件結果，以提供有關這種情況發生頻率的數據。例如，如果傳輸達到其最大內部隊列大小，SDK 可能會丟棄事件， 因為速率限制指示 SDK 在事件超過配額等時丟棄事件。
Envelope(信封)項負載
Client 報告是名為 client_report 的 envelope 中的一項。它包含一個大致如下所示的 JSON 負載：
- {
- "timestamp": "2020-02-07T14:16:00Z",
- "discarded_events": [
- {
- "reason": "queue_overflow",
- "category": "error",
- "quantity": 23
- },
- {
- "reason": "queue_overflow",
- "category": "transaction",
- "quantity": 1321
- }
- ]
- }
請注意，這必須包含在 envelope 中。所以完整的事件看起來像這樣：
- {}
- {"type":"client_report"}
- {"timestamp":"..."}
存在以下字段：
timestamp
- String | Number, optional. 創建 client report 的時間戳。
必須是 ISO 日期時間字符串或 UNIX 時間戳。如果未發送，服務器將采用當前的 UTC 時間戳。在數據模型中，這稱為 received
discarded_events
- outcome 對象列表 {reason, category, quantity}
- reason: 定義事件丟失原因的字符串原因。
- category: 丟棄原因適用的數據類別。
- quantity: 丟失的事件數
目前定義了以下丟棄原因：
- queue_overflow: SDK 內部隊列(例如：傳輸隊列)溢出
- cache_overflow: SDK 內部緩存(例如：離線事件緩存)溢出
- ratelimit_backoff: SDK 丟棄事件是因為較早的速率限制指示 SDK 退出。
- network_error: 由于網絡錯誤，事件被丟棄并且沒有重試。
- sample_rate: 由于配置的采樣率，事件被丟棄。
此外，保留以下丟棄原因，但不期望 SDK 在正常操作下發送這些：
- before_send: 事件在 before_send 中被丟棄
- event_processor: 事件被事件處理器丟棄
SDK 端推薦
鼓勵 SDK 減少不必要的通信總量。因此，推薦的方法是直接跟蹤 transport 中丟棄原因的計數， 并定期將它們作為單獨的 envelope 項沖洗掉或將其附加到已安排好的 envelope 上。由于某些 SDK 仍然發送舊事件而不是 envelope，以便與舊的 Sentry 服務器向后兼容， 因此在這種情況下，建議將其作為單獨的 envelope 發送，或者將其附加到待處理的 session envelope。
