How to Implement Sentry Client Reports in Your SDK

Basic Operations

Client reports

are a protocol feature that lets a client send status reports to Sentry. They are primarily used to report outcomes for events that were never sent. A client report is sent as an envelope item, either as a separate envelope or attached to an already‑scheduled envelope. Reports should not be sent too frequently nor too rarely; their purpose is to inform developers about SDK‑side actions that affect user experience.

For example, the SDK may drop events in several places, which is invisible to the customer. A client report lets the SDK emit the outcome of these dropped events, providing data on how often this occurs. If the transport reaches its maximum internal queue size, the SDK may discard events because a rate‑limit indicates the SDK is over quota, among other reasons.

Envelope Item Payload

A client report is an item named client_report inside an envelope. Its JSON payload looks like this:

{
  "timestamp": "2020-02-07T14:16:00Z",
  "discarded_events": [
    {
      "reason": "queue_overflow",
      "category": "error",
      "quantity": 23
    },
    {
      "reason": "queue_overflow",
      "category": "transaction",
      "quantity": 1321
    }
  ]
}

The JSON must be included in the envelope, so a complete envelope fragment appears as:

{}
{ "type": "client_report" }
{ "timestamp": "..." }

Fields: timestamp – optional string or number. It records when the client report was created. It must be an ISO‑8601 datetime string or a UNIX timestamp; if omitted, the server uses the current UTC time (recorded as received in the data model). discarded_events – list of outcome objects, each containing: reason: string describing why events were dropped. category: the data category the drop applies to. quantity: number of events discarded.

Currently defined discard reasons are: queue_overflow: internal SDK queue (e.g., transport queue) overflow. cache_overflow: internal SDK cache (e.g., offline event cache) overflow. ratelimit_backoff: events dropped because a prior rate‑limit signal told the SDK to back off. network_error: events dropped due to a network error without retry. sample_rate: events dropped because of the configured sampling rate.

Additional reasons exist but are not expected during normal SDK operation: before_send: events dropped in the before_send hook. event_processor: events dropped by an event processor.

SDK Recommendations

SDKs are encouraged to reduce unnecessary traffic. The recommended approach is to track counts of discard reasons directly in the transport and periodically flush them as separate envelope items or attach them to a scheduled envelope. Some SDKs still send legacy events instead of envelopes for backward compatibility with older Sentry servers; in that case, send the client report as a separate envelope or attach it to a pending session envelope.