From 99a309e53a8be83c53f1fcb244c3132d6216b770 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 8 Oct 2026 16:15:34 +0200 Subject: [PATCH 1/3] ref(develop): Clarify client report quantity for logs, metrics and spans --- develop-docs/sdk/telemetry/client-reports.mdx | 19 ++++++++++++++- develop-docs/sdk/telemetry/logs.mdx | 14 ++++++++++- develop-docs/sdk/telemetry/metrics.mdx | 14 ++++++++++- develop-docs/sdk/telemetry/spans/index.mdx | 24 ++++++++++++++++++- 4 files changed, 67 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index c40307cc7cb322..6b695b7e2b136c 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.24.0 +spec_version: 1.25.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes version: ">=1.0.0" spec_changelog: + - version: 1.25.0 + date: 2026-10-08 + summary: Clarified that discarded envelopes are counted per contained item, not as a quantity of 1 - version: 1.24.0 date: 2026-09-01 summary: Added `callback_error` discard reason @@ -206,6 +209,20 @@ SDKs **MAY** retry sending the envelope when a network error occurs (connection + + +#### Quantity of Discarded Envelopes + +When SDKs discard an envelope because sending it failed, 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. +- 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 diff --git a/develop-docs/sdk/telemetry/logs.mdx b/develop-docs/sdk/telemetry/logs.mdx index 206fbccb35b012..a1ba8eff6f955b 100644 --- a/develop-docs/sdk/telemetry/logs.mdx +++ b/develop-docs/sdk/telemetry/logs.mdx @@ -2,7 +2,7 @@ title: Logs description: Structured logging protocol with severity levels, trace context, and batched envelope delivery. spec_id: sdk/telemetry/logs -spec_version: 3.0.0 +spec_version: 3.1.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/state-management/scopes/attributes version: ">=1.0.0" spec_changelog: + - version: 3.1.0 + date: 2026-10-08 + summary: Listed client report discard reasons for logs and clarified that the quantity is the number of discarded logs - version: 3.0.0 date: 2026-09-28 summary: Removed the global logs enablement option; retained explicit opt-in for integrations @@ -358,6 +361,15 @@ If `debug` is set to `true` in SDK init, calls to the Sentry logger API **SHOULD SDKs **MUST** report count (`log_item`) and size in bytes (`log_byte`) of discarded log messages. An approximation of log size is sufficient (e.g., by counting as if serialized). +SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) in at least the following cases: + +- `before_send`: `beforeSendLog`/`before_send_log` returned `null`. +- `buffer_overflow`: the log was dropped because the buffer reached its [hard limit](#buffering). +- `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)). + --- diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 19668c02dd4627..8907a754081737 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -2,7 +2,7 @@ title: Metrics description: Counter, gauge, and distribution metrics sent as batched trace_metric envelope items. spec_id: sdk/telemetry/metrics -spec_version: 3.0.0 +spec_version: 3.1.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/state-management/scopes/attributes version: ">=1.0.0" spec_changelog: + - version: 3.1.0 + date: 2026-10-08 + summary: Listed client report discard reasons for metrics and clarified that the quantity is the number of discarded metrics - version: 3.0.0 date: 2026-09-28 summary: Removed the global metrics enablement option; retained explicit opt-in for integrations @@ -268,6 +271,15 @@ These rules exist because auto-emitted metrics can cause a high volume of teleme SDKs **MUST** report count (`trace_metric`) and size in bytes (`trace_metric_byte`) of discarded metrics. An approximation of metric size is sufficient (e.g., by counting as if serialized). +SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) in at least the following cases: + +- `before_send`: `beforeSendMetric`/`before_send_metric` returned `null`. +- `buffer_overflow`: the metric was dropped because the [buffer](#buffering) reached its size limit. +- `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)). + --- diff --git a/develop-docs/sdk/telemetry/spans/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx index 6945d51f13b468..baccc318b29038 100644 --- a/develop-docs/sdk/telemetry/spans/index.mdx +++ b/develop-docs/sdk/telemetry/spans/index.mdx @@ -2,7 +2,7 @@ title: Spans description: Span creation, sampling, filtering, buffering, and wire format for the span-first tracing model. spec_id: sdk/telemetry/spans -spec_version: 1.0.0 +spec_version: 1.1.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/trace-propagation version: ">=1.0.0" spec_changelog: + - version: 1.1.0 + date: 2026-10-08 + summary: Added client reports section listing discard reasons for spans and clarifying that the quantity is the number of discarded spans - version: 1.0.0 date: 2026-06-22 summary: Initial stable release @@ -476,6 +479,25 @@ SDKs **SHOULD** materialize and freeze the DSC as late as possible: + + +### Client Reports + +SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) with the `span` data category in at least the following cases: + +- `sample_rate`: the span was not recorded because its trace was negatively sampled, so a [Noop span](#noop-span) was returned instead. SDKs **SHOULD** record one outcome per Noop span. +- `ignored`: the span matched an `ignoreSpans` pattern. See the [filtering implementation requirements](#implementation-requirements) for how to count ignored segments and their children. +- `no_parent_span`: the span was not started because no parent span was present (for example, auto-instrumented spans that are only created within an active span). +- `buffer_overflow`: the [span buffer](#span-buffer) dropped the span. +- `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)). + +[`beforeSendSpan`](#beforesendspan) cannot remove spans and the [`captureSpan` pipeline](#single-span-processing-pipeline) **MUST NOT** drop spans, so no client reports are recorded at these stages. + + + ### Span Links From dee0d6a54e20fcb0fa9ff33387954437482ae41b Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 8 Oct 2026 16:18:53 +0200 Subject: [PATCH 2/3] remove some fluff --- develop-docs/sdk/telemetry/client-reports.mdx | 2 +- develop-docs/sdk/telemetry/spans/index.mdx | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index 6b695b7e2b136c..bbf7637dbb06d1 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -213,7 +213,7 @@ SDKs **MAY** retry sending the envelope when a network error occurs (connection #### Quantity of Discarded Envelopes -When SDKs discard an envelope because sending it failed, 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: +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. - For logs and metrics, SDKs **MUST** also record the respective [`log_byte`](#log-byte-outcomes) and [`trace_metric_byte`](#metric-byte-outcomes) entries. diff --git a/develop-docs/sdk/telemetry/spans/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx index baccc318b29038..14ede26809eaee 100644 --- a/develop-docs/sdk/telemetry/spans/index.mdx +++ b/develop-docs/sdk/telemetry/spans/index.mdx @@ -494,8 +494,6 @@ SDKs **MUST** record a [client report](/sdk/telemetry/client-reports/) with the 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)). -[`beforeSendSpan`](#beforesendspan) cannot remove spans and the [`captureSpan` pipeline](#single-span-processing-pipeline) **MUST NOT** drop spans, so no client reports are recorded at these stages. - From 20873a8d104e99be8a12f1161326bf442d0814ef Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Fri, 9 Oct 2026 11:48:45 +0200 Subject: [PATCH 3/3] clarify category vs envelope type --- 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 bbf7637dbb06d1..b824451590bf96 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -215,7 +215,7 @@ SDKs **MAY** retry sending the envelope when a network error occurs (connection 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. +- 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).