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。

更多

Sentry 开发者贡献指南 - SDK 开发(性能监控：Sentry SDK API 演进)