Skip to content

ref(develop): Define client report quantity instead of discarded envelope section #19966

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sentry-junior wants to merge 5 commits into
base: master
Choose a base branch
from
Open

ref(develop): Define client report quantity instead of discarded envelope section #19966

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
819bdb7
ref(develop): Define client report quantity instead of discarded enve…
sentry-junior[bot] Oct 14, 2026
5293332
ref(develop): Reword client report quantity definition
sentry-junior[bot] Oct 14, 2026
7a9bff1
ref(develop): Tighten client report quantity wording
sentry-junior[bot] Oct 14, 2026
b875e9c
ref(develop): Use em-dashes in client report quantity definition
sentry-junior[bot] Oct 14, 2026
80114e3
ref(develop): Reference quantity definition from payload table
sentry-junior[bot] Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 9 additions & 16 deletions develop-docs/sdk/telemetry/client-reports.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@
title: Client Reports
description: SDK self-reporting protocol for tracking discarded events and their discard reasons.
spec_id: sdk/telemetry/client-reports
spec_version: 1.25.0
spec_version: 1.26.0
spec_status: stable
spec_depends_on:
- id: sdk/foundations/transport/envelopes
version: ">=1.0.0"
spec_changelog:
- version: 1.26.0
date: 2026-10-14
summary: Replaced the Quantity of Discarded Envelopes section with a general definition of quantity
- version: 1.25.0
date: 2026-10-08
summary: Clarified that discarded envelopes are counted per contained item, not as a quantity of 1
Expand Down Expand Up @@ -125,6 +128,10 @@ A **discard reason** is a string that explains why a telemetry item was dropped.

Data categories (e.g., `error`, `transaction`, `span`) identify the type of telemetry item that was discarded. These are the same categories used for [rate limits](/sdk/foundations/transport/rate-limiting/#definitions).

### Quantity

The outcome **quantity** is the number of discarded telemetry items or, for byte categories, their size in bytes. The quantity is not necessarily the same as the number of envelope items: some envelope items — such as `log`, `trace_metric`, and `span` items — contain multiple telemetry items.

---

## Behavior
Expand Down Expand Up @@ -209,20 +216,6 @@ SDKs **MAY** retry sending the envelope when a network error occurs (connection

</SpecSection>

<SpecSection id="network-discarded-quantity" status="candidate" since="1.25.0">

#### Quantity of Discarded Envelopes

When SDKs discard an envelope, they **MUST** record a client report entry for every telemetry item contained in the envelope, not just one entry per envelope or per envelope item. The `quantity` for each data category **MUST** be the number of items of that category in the envelope:

- For `log`, `trace_metric`, and `span` envelope items, which batch multiple items into one envelope item, the quantity is the number of entries in the envelope item's `items` array, not 1. These are recorded under the `log_item`, `trace_metric`, and `span` data categories respectively.
- For logs and metrics, SDKs **MUST** also record the respective [`log_byte`](#log-byte-outcomes) and [`trace_metric_byte`](#metric-byte-outcomes) entries.
- For transactions, SDKs **MUST** also record the [span outcomes](#span-outcomes).

For example, if an envelope containing a `log` item with 100 logs fails to send with an `HTTP 500` response, the SDK records a `send_error` entry with category `log_item` and quantity `100`, plus a `send_error` entry with category `log_byte` and the approximate byte size of these logs.

</SpecSection>

<SpecSection id="span-outcomes" status="stable" since="1.14.0">

### Span Outcomes
Expand Down Expand Up @@ -362,7 +355,7 @@ Each outcome object in `discarded_events` has:
|-------|------|----------|-------------|
| `reason` | String | **REQUIRED** | A discard reason that defines why events were lost (see [Discard Reasons](#discard-reasons)). |
| `category` | String | **REQUIRED** | The [data category](/sdk/foundations/transport/rate-limiting/#definitions) for which the discard reason applies (since 1.2.0). |
| `quantity` | Number | **REQUIRED** | The number of events which were lost. |
| `quantity` | Number | **REQUIRED** | The outcome quantity, [as defined above](#quantity). |

</SpecSection>

Expand Down
2 changes: 1 addition & 1 deletion develop-docs/sdk/telemetry/logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,7 @@ SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) in at lea
- `ratelimit_backoff`: the log was dropped because the `log_item` data category is [rate limited](#data-category-and-rate-limiting).
- `send_error`, `internal_sdk_error`, `network_error`: the envelope containing the log was discarded because sending it failed, as specified in [Network Failure Recording](/sdk/telemetry/client-reports/#network-failure-recording).

The `log_item` quantity **MUST** be the number of discarded logs, not the number of discarded envelopes or envelope items. For example, if a `log` envelope with 100 logs fails to send, the SDK records a `log_item` quantity of 100 (see [Quantity of Discarded Envelopes](/sdk/telemetry/client-reports/#quantity-of-discarded-envelopes)).
The `log_item` quantity **MUST** be the number of discarded logs, not the number of discarded envelopes or envelope items. For example, if a `log` envelope with 100 logs fails to send, the SDK records a `log_item` quantity of 100 (see [Quantity](/sdk/telemetry/client-reports/#quantity)).

</SpecSection>

Expand Down
2 changes: 1 addition & 1 deletion develop-docs/sdk/telemetry/metrics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) in at lea
- `ratelimit_backoff`: the metric was dropped because the `trace_metric` data category is [rate limited](#data-category-and-rate-limiting).
- `send_error`, `internal_sdk_error`, `network_error`: the envelope containing the metric was discarded because sending it failed, as specified in [Network Failure Recording](/sdk/telemetry/client-reports/#network-failure-recording).

The `trace_metric` quantity **MUST** be the number of discarded metrics, not the number of discarded envelopes or envelope items. For example, if a `trace_metric` envelope with 100 metrics fails to send, the SDK records a `trace_metric` quantity of 100 (see [Quantity of Discarded Envelopes](/sdk/telemetry/client-reports/#quantity-of-discarded-envelopes)).
The `trace_metric` quantity **MUST** be the number of discarded metrics, not the number of discarded envelopes or envelope items. For example, if a `trace_metric` envelope with 100 metrics fails to send, the SDK records a `trace_metric` quantity of 100 (see [Quantity](/sdk/telemetry/client-reports/#quantity)).

</SpecSection>

Expand Down
2 changes: 1 addition & 1 deletion develop-docs/sdk/telemetry/spans/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -492,7 +492,7 @@ SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) with the
- `ratelimit_backoff`: the span was dropped because the `span` data category is rate limited.
- `send_error`, `internal_sdk_error`, `network_error`: the envelope containing the span was discarded because sending it failed, as specified in [Network Failure Recording](/sdk/telemetry/client-reports/#network-failure-recording).

The quantity **MUST** be the number of discarded spans, not the number of discarded envelopes or envelope items. For example, if a span envelope with 500 spans fails to send, the SDK records a `span` quantity of 500 (see [Quantity of Discarded Envelopes](/sdk/telemetry/client-reports/#quantity-of-discarded-envelopes)).
The quantity **MUST** be the number of discarded spans, not the number of discarded envelopes or envelope items. For example, if a span envelope with 500 spans fails to send, the SDK records a `span` quantity of 500 (see [Quantity](/sdk/telemetry/client-reports/#quantity)).

</SpecSection>

Expand Down
Loading