Client Reports

Client reports are sent as envelope items to Sentry, typically as separate envelopes or with one of the already scheduled envelopes. Their main purpose is to bring visibility into what is happening on the SDK side.

SDKs might drop events in several places — transport queue overflow, rate limit backoff, sampling, before_send, event processors — and this loss can be invisible to a customer. Client reports let an SDK emit such event outcomes to provide data about how often this is happening.

The party that drops an envelope item MUST record and report it.

SDKs can assume client reports are never rate limited (since 1.9.0). The server minimizes the possibility of client reports getting rate limited, but the SDKs shouldn't worry about this edge case as this feature is best-effort.

Bugs in SDKs are out of scope for client reports and are not tracked using client reports (since 1.7.0).

Client reports do not expect 100 percent correct numbers, and it is acceptable for SDKs to lose a small number of client reports. The expectation is to give users an approximation of specific outcomes.

Successful Sends (HTTP 2xx)

When SDKs receive an HTTP 2xx status code response from Sentry, they MUST consider it a successful send. No client report is recorded.

If Sentry returns an HTTP 4xx or HTTP 5xx status code, SDKs:

• MUST discard the envelope.
• MUST record a client report with the discard reason send_error. For HTTP 429 and HTTP 413, follow the dedicated sections below instead, as they have additional requirements.

For an HTTP 413 Content Too Large response, SDKs:

• MUST discard the envelope and record a client report with the discard reason send_error. Upstream usually records a client report for oversized envelopes, but not always. Double-counting is preferable to not counting, so users are aware of all dropped envelopes. Since client reports are not expected to be fully accurate, we accept this tradeoff for now.
• MUST NOT retry sending the envelope.
• SHOULD log an error, informing users that the envelope was discarded due to size limits.
• MAY add information from the response body to the logged error. If doing so, SDKs MUST be aware that Relay can change or remove information in the response body for an HTTP 413 at any time without notice.

For an HTTP 429 Too Many Requests response, SDKs:

• MUST respect the rate limiting rules, such as correctly parsing the retry-header.
• MUST discard the envelope, but MUST NOT record a client report, because the upstream already does this. Doing this would double-count client reports for discarded envelopes.
• MUST NOT retry sending the envelope.

When failures occur that are caused by processing in the SDK itself, SDKs MUST discard the envelope and record a client report with the discard reason internal_sdk_error.

SDKs MAY retry sending the envelope when a network error occurs (connection timeout, DNS resolution failure, connection reset by peer). No client report is required for retried network errors.

When a transaction is dropped, SDKs MUST record an additional span category entry containing the number of spans inside the transaction plus one. The plus one stems from the fact that Relay extracts an additional span from the transaction. If a transaction contains no spans, SDKs still report one dropped transaction and one dropped span. This also applies to transactions that are not sampled.

If certain spans are dropped in beforeSendTransaction, an event processor, etc., SDKs also report those.

When a log is dropped, SDKs MUST record an additional log_byte category entry containing the byte size of the log. This provides visibility into the volume of log data being discarded, complementing the item count reported under the log_item category.

Since client reports use a (reason, category) → quantity map for aggregation, byte sizes are tracked as a separate category rather than an extra field. Each dropped log produces two entries in the map: one incrementing the log_item count by 1, and one incrementing the log_byte count by the log's byte size.

The byte size does not need to be exact. SDKs MAY use an approximation, such as the in-memory size of the log object or the size of its serialized representation. The goal is to provide a useful signal, not a precise measurement.

It is not required, for example:

• to persist the data when an application crashes.
• to move an envelope item with a client report to the next envelope when the cache for envelopes is full.

SDKs SHOULD minimize unnecessary HTTP requests and MUST NOT send an envelope for each discarded event. Adjust these recommendations as needed:

1. For low-frequency apps (mobile/web): Attach discarded events to scheduled envelopes. Fewer client reports are acceptable in such cases.
2. For high-frequency apps (backends): Periodically flush discarded events or attach to scheduled envelopes.

SDKs SHOULD provide a way to turn sending of client reports on and off. This option is called send_client_reports or sendClientReports.

For SDKs still sending legacy events instead of envelopes for backward compatibility with older Sentry servers, the recommendation is to send the client report as a separate envelope or attach it to pending session envelopes.

There is no expectation that such bookkeeping can work transparently for custom transports. Consequently, it's acceptable if client reports are optional for custom transports.

Item type "client_report" contains a client report payload encoded in JSON.

Constraints:

• This Item MAY occur multiple times per Envelope, but SDKs SHOULD avoid sending more client reports than necessary.
• This Item can either be included in an Envelope with other Items, or it MAY be sent by itself.
• No envelope headers are required.
• Size limit: 4 KiB (see Envelopes — Size Limits).

A client report consists of a JSON payload with the following fields:

Each outcome object in discarded_events has:

The following discard reasons are defined for discarded_events:

In case a reason needs to be added, it also has to be added to the allowlist in snuba.

The following outcome types are reserved for relay use:

rate_limited_events, filtered_events, filtered_sampling_events

These function like discarded_events (same {reason, category, quantity} structure) but identify events that were rate limited, filtered, or filtered by dynamic sampling at a relay. Client SDKs MUST NOT emit these unless they are operating as a relay. The reason codes for these need to match the reason codes that relay would emit directly to Sentry.