diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index b824451590bf9..281c06cbc1134 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 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 @@ -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 outcome quantity, [as defined above](#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)).