Skip to content

ref(develop): Clarify client report quantity for logs, metrics and spans #19854

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

Merged
Lms24 merged 3 commits into from
Oct 9, 2026
Merged

ref(develop): Clarify client report quantity for logs, metrics and spans #19854

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
99a309e
ref(develop): Clarify client report quantity for logs, metrics and spans
Lms24 Oct 8, 2026
dee0d6a
remove some fluff
Lms24 Oct 8, 2026
20873a8
clarify category vs envelope type
Lms24 Oct 9, 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
19 changes: 18 additions & 1 deletion 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.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
Expand Down Expand Up @@ -206,6 +209,20 @@ 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
14 changes: 13 additions & 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 @@ -2,14 +2,17 @@
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
version: ">=1.0.0"
- 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
Expand Down Expand Up @@ -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)).

</SpecSection>

---
Expand Down
14 changes: 13 additions & 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 @@ -2,14 +2,17 @@
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
version: ">=1.0.0"
- 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
Expand Down Expand Up @@ -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)).

</SpecSection>

---
Expand Down
22 changes: 21 additions & 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 @@ -2,14 +2,17 @@
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
version: ">=1.0.0"
- 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
Expand Down Expand Up @@ -476,6 +479,23 @@ SDKs **SHOULD** materialize and freeze the DSC as late as possible:

</SpecSection>

<SpecSection id="client-reports" status="candidate" since="1.1.0">

### 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)).

</SpecSection>

<SpecSection id="span-links" status="stable" since="1.0.0">

### Span Links
Expand Down
Loading