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