From 819bdb755d857b88252e2fcac62c577a69478e87 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 08:34:46 +0000 Subject: [PATCH 1/5] ref(develop): Define client report quantity instead of discarded envelope section Co-Authored-By: Daniel SzokeNSTEIN <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/telemetry/client-reports.mdx | 25 +++++++------------ develop-docs/sdk/telemetry/logs.mdx | 2 +- develop-docs/sdk/telemetry/metrics.mdx | 2 +- develop-docs/sdk/telemetry/spans/index.mdx | 2 +- 4 files changed, 12 insertions(+), 19 deletions(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index b824451590bf9..6c45a3d9c76bc 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -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 @@ -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 **quantity** of an outcome is the number of discarded telemetry items, not the number of envelopes or envelope items. For envelope items that contain multiple telemetry items, such as `log`, `trace_metric`, and `span` items, each entry in the item's `items` array counts as one telemetry item. For byte categories (`log_byte`, `trace_metric_byte`), the quantity is the size in bytes. + --- ## Behavior @@ -209,20 +216,6 @@ SDKs **MAY** retry sending the envelope when a network error occurs (connection - - -#### 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. - - - ### Span Outcomes @@ -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 number of telemetry items which were lost, or the size in bytes for byte categories (see [Quantity](#quantity)). | diff --git a/develop-docs/sdk/telemetry/logs.mdx b/develop-docs/sdk/telemetry/logs.mdx index a1ba8eff6f955..b1852ce14eb9a 100644 --- a/develop-docs/sdk/telemetry/logs.mdx +++ b/develop-docs/sdk/telemetry/logs.mdx @@ -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)). diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 8907a75408173..792de8eac2edd 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -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)). diff --git a/develop-docs/sdk/telemetry/spans/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx index 14ede26809eae..513af115dca12 100644 --- a/develop-docs/sdk/telemetry/spans/index.mdx +++ b/develop-docs/sdk/telemetry/spans/index.mdx @@ -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)). From 5293332a81fcb8294e43489e14193b89674cdfdf Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 08:57:15 +0000 Subject: [PATCH 2/5] ref(develop): Reword client report quantity definition --- develop-docs/sdk/telemetry/client-reports.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index 6c45a3d9c76bc..cce8f4d7f2ec4 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -130,7 +130,7 @@ Data categories (e.g., `error`, `transaction`, `span`) identify the type of tele ### Quantity -The **quantity** of an outcome is the number of discarded telemetry items, not the number of envelopes or envelope items. For envelope items that contain multiple telemetry items, such as `log`, `trace_metric`, and `span` items, each entry in the item's `items` array counts as one telemetry item. For byte categories (`log_byte`, `trace_metric_byte`), the quantity is the size in bytes. +The outcome **quantity** is the number of discarded telemetry items, or for byte outcomes, their byte size. This outcome quantity is distinct from the number of envelope items, as some envelope items, such as `log`, `trace_metric`, and `span` items, can contain multiple telemetry items. --- From 7a9bff10bf10e04e8d46a1c7cac525042c0eebbe Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 08:59:44 +0000 Subject: [PATCH 3/5] ref(develop): Tighten client report quantity wording Co-Authored-By: Daniel SzokeNSTEIN <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/telemetry/client-reports.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index cce8f4d7f2ec4..b70c4fed0f402 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -130,7 +130,7 @@ Data categories (e.g., `error`, `transaction`, `span`) identify the type of tele ### Quantity -The outcome **quantity** is the number of discarded telemetry items, or for byte outcomes, their byte size. This outcome quantity is distinct from the number of envelope items, as some envelope items, such as `log`, `trace_metric`, and `span` items, can contain multiple telemetry items. +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. --- From b875e9c4df133e8a7b70dd29d05c6069bc3fb1fc Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 08:59:58 +0000 Subject: [PATCH 4/5] ref(develop): Use em-dashes in client report quantity definition Co-Authored-By: Daniel SzokeNSTEIN <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/telemetry/client-reports.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index b70c4fed0f402..3bead13e22058 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -130,7 +130,7 @@ Data categories (e.g., `error`, `transaction`, `span`) identify the type of tele ### 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. +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. --- From 80114e3f3fd6284fd307f640ffa087127e1a21ec Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 09:03:28 +0000 Subject: [PATCH 5/5] ref(develop): Reference quantity definition from payload table --- develop-docs/sdk/telemetry/client-reports.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index 3bead13e22058..281c06cbc1134 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -355,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 telemetry items which were lost, or the size in bytes for byte categories (see [Quantity](#quantity)). | +| `quantity` | Number | **REQUIRED** | The outcome quantity, [as defined above](#quantity). |