From 5c2efd2fb89fc22dd76177a81362f921d3adafc2 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian Date: Tue, 23 Sep 2025 17:56:17 +0200 Subject: [PATCH 01/12] feat(develop): document `traceIgnoreStatusCodes` --- develop-docs/sdk/telemetry/traces/index.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 78eb903dcfcc1..cf45070765a35 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -128,6 +128,18 @@ Header Format: The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trace-context/) specification. +### `traceIgnoreStatusCodes` + +This must be a list/array of integers, denoting HTTP status codes. + +The SDK should honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. +If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. + +This option must default to an empty list/array if it's introduced in a release with a minor SemVer bump. +SDKs should set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. + +The rationale for this option and default is to not consume a user's span quota to trace requests that are useless for debugging purposes (and can often be triggered by scanning bots). + ## `Event` Changes As of writing, transactions are implemented as an extension of the `Event` From 10d3acbf7287a4211e04e674927f3164b7e54248 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 10:09:43 +0200 Subject: [PATCH 02/12] Update index.mdx --- develop-docs/sdk/telemetry/traces/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index cf45070765a35..e411da34ab34a 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -135,6 +135,8 @@ This must be a list/array of integers, denoting HTTP status codes. The SDK should honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. +The SDK should log an info message (when debug logging is enabled with `debug` == `true` in the client options) denoting why the transaction was dropped. + This option must default to an empty list/array if it's introduced in a release with a minor SemVer bump. SDKs should set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. From 7a65ec9de9730fd26440a48e716e562621e51a8a Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 10:20:24 +0200 Subject: [PATCH 03/12] Update index.mdx --- develop-docs/sdk/telemetry/traces/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index e411da34ab34a..8d621cc5d96e4 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -130,14 +130,14 @@ The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trac ### `traceIgnoreStatusCodes` -This must be a list/array of integers, denoting HTTP status codes. +This must be a sequence of integers, denoting HTTP status codes. The SDK should honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. The SDK should log an info message (when debug logging is enabled with `debug` == `true` in the client options) denoting why the transaction was dropped. -This option must default to an empty list/array if it's introduced in a release with a minor SemVer bump. +This option must default to an empty sequence if it's introduced in a release with a minor SemVer bump. SDKs should set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. The rationale for this option and default is to not consume a user's span quota to trace requests that are useless for debugging purposes (and can often be triggered by scanning bots). From b63f762ed1f87a504e8d6fc0a5080ca69011c3fe Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 10:25:16 +0200 Subject: [PATCH 04/12] Change log level from info to debug for dropped transactions --- develop-docs/sdk/telemetry/traces/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 8d621cc5d96e4..2e522551f8b68 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -135,7 +135,7 @@ This must be a sequence of integers, denoting HTTP status codes. The SDK should honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. -The SDK should log an info message (when debug logging is enabled with `debug` == `true` in the client options) denoting why the transaction was dropped. +The SDK should log a debug level message (when debug logging is enabled with `debug` == `true` in the client options) denoting why the transaction was dropped. This option must default to an empty sequence if it's introduced in a release with a minor SemVer bump. SDKs should set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. From 02622df7d56cf8b2570275146aa140404bb4c871 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 10:56:37 +0200 Subject: [PATCH 05/12] Update traceIgnoreStatusCodes documentation Clarify that traceIgnoreStatusCodes applies only to server SDKs and incoming requests. --- develop-docs/sdk/telemetry/traces/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 2e522551f8b68..ace128b2ae8ac 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -132,6 +132,8 @@ The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trac This must be a sequence of integers, denoting HTTP status codes. +The option only applies to incoming requests, and therefore should only be implemented in server SDKs. + The SDK should honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. From 19495d7502e31e772474d561a72d81faf68c8480 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 11:04:17 +0200 Subject: [PATCH 06/12] Update index.mdx --- develop-docs/sdk/telemetry/traces/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index ace128b2ae8ac..ea19570a3cdad 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -138,6 +138,7 @@ The SDK should honor this option by inspecting the [`http.response.status_code`] If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. The SDK should log a debug level message (when debug logging is enabled with `debug` == `true` in the client options) denoting why the transaction was dropped. +If the SDK implements client reports, it should record the dropped transaction with the `event_processor` discard reason. This option must default to an empty sequence if it's introduced in a release with a minor SemVer bump. SDKs should set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. From 3333f4f56513e604c904a0a4d0bfc261e8d7400d Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 14:56:42 +0200 Subject: [PATCH 07/12] Clarify traceIgnoreStatusCodes requirements and defaults Updated language to clarify requirements and defaults for the traceIgnoreStatusCodes option. --- develop-docs/sdk/telemetry/traces/index.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index ea19570a3cdad..2e1a58fe06aad 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -130,18 +130,21 @@ The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trac ### `traceIgnoreStatusCodes` -This must be a sequence of integers, denoting HTTP status codes. +This SHOULD be a sequence of integers, denoting HTTP status codes. +If suitable for the platform, the option MAY also admit pairs of integers (representable by an `Interval`/`Range` type if such type exists as a built-in), denoting HTTP status code ranges. -The option only applies to incoming requests, and therefore should only be implemented in server SDKs. +The option applies exclusively to incoming requests, and therefore MUST only be implemented in server SDKs. -The SDK should honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. -If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK must set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. +The SDK MUST honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. +If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK MUST set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. -The SDK should log a debug level message (when debug logging is enabled with `debug` == `true` in the client options) denoting why the transaction was dropped. -If the SDK implements client reports, it should record the dropped transaction with the `event_processor` discard reason. +Note that a prerequisite to implement this option is that every HTTP server integration MUST record the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute as defined in the OTEL spec. -This option must default to an empty sequence if it's introduced in a release with a minor SemVer bump. -SDKs should set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. +The SDK MUST emit a debug log denoting why the transaction was dropped. +If the SDK implements client reports, it MUST record the dropped transaction with the `event_processor` discard reason. + +This option MUST default to an empty sequence if it's introduced in a release with a minor SemVer bump. +SDKs SHOULD set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. The rationale for this option and default is to not consume a user's span quota to trace requests that are useless for debugging purposes (and can often be triggered by scanning bots). From f0e4dd11b186b9e56f63f1b9f770db985e3d159b Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 15:03:05 +0200 Subject: [PATCH 08/12] Update index.mdx --- develop-docs/sdk/telemetry/traces/index.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 2e1a58fe06aad..539cb06b79f9f 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -131,7 +131,7 @@ The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trac ### `traceIgnoreStatusCodes` This SHOULD be a sequence of integers, denoting HTTP status codes. -If suitable for the platform, the option MAY also admit pairs of integers (representable by an `Interval`/`Range` type if such type exists as a built-in), denoting HTTP status code ranges. +If suitable for the platform, the option MAY also admit pairs of integers, denoting HTTP status code ranges. The option applies exclusively to incoming requests, and therefore MUST only be implemented in server SDKs. @@ -148,6 +148,10 @@ SDKs SHOULD set the default for this option to `[404]` at the earliest release w The rationale for this option and default is to not consume a user's span quota to trace requests that are useless for debugging purposes (and can often be triggered by scanning bots). +Examples: +`[403, 404]`: don't sample transactions with status code 403 or 404 +`[[300, 305], [401, 404]]`: don't sample transactions with status codes between 300 and 305 (inclusive) or between 401 and 404 (inclusive) + ## `Event` Changes As of writing, transactions are implemented as an extension of the `Event` From d8c8502e58b0c558683da5a0540c56927a402b6d Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 15:07:36 +0200 Subject: [PATCH 09/12] Update index.mdx --- develop-docs/sdk/telemetry/traces/index.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 539cb06b79f9f..4577fa71a9801 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -130,7 +130,7 @@ The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trac ### `traceIgnoreStatusCodes` -This SHOULD be a sequence of integers, denoting HTTP status codes. +This SHOULD be a collection of integers, denoting HTTP status codes. If suitable for the platform, the option MAY also admit pairs of integers, denoting HTTP status code ranges. The option applies exclusively to incoming requests, and therefore MUST only be implemented in server SDKs. @@ -144,13 +144,17 @@ The SDK MUST emit a debug log denoting why the transaction was dropped. If the SDK implements client reports, it MUST record the dropped transaction with the `event_processor` discard reason. This option MUST default to an empty sequence if it's introduced in a release with a minor SemVer bump. -SDKs SHOULD set the default for this option to `[404]` at the earliest release with a major SemVer bump following its introduction. +SDKs SHOULD set the default for this option to the following value (or equivalent if the implementation doesn't admit pairs of integers) +``` +[[301, 303], [305, 399], [401, 404]] +``` +at the earliest release with a major SemVer bump following its introduction. The rationale for this option and default is to not consume a user's span quota to trace requests that are useless for debugging purposes (and can often be triggered by scanning bots). Examples: -`[403, 404]`: don't sample transactions with status code 403 or 404 -`[[300, 305], [401, 404]]`: don't sample transactions with status codes between 300 and 305 (inclusive) or between 401 and 404 (inclusive) +`[403, 404]`: don't sample transactions corresponding to requests with status code 403 or 404 +`[[300, 399], [401, 404]]`: don't sample transactions corresponding to requests with status codes between 300 and 399 (inclusive) or between 401 and 404 (inclusive) ## `Event` Changes From 5e88107ac723736f7f72c860bbef4c03e07a4fd4 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 15:08:58 +0200 Subject: [PATCH 10/12] Update terminology for default option in SDK docs Clarified terminology from 'sequence' to 'collection' for default option. --- develop-docs/sdk/telemetry/traces/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index 4577fa71a9801..aa004ef1b409d 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -143,7 +143,7 @@ Note that a prerequisite to implement this option is that every HTTP server inte The SDK MUST emit a debug log denoting why the transaction was dropped. If the SDK implements client reports, it MUST record the dropped transaction with the `event_processor` discard reason. -This option MUST default to an empty sequence if it's introduced in a release with a minor SemVer bump. +This option MUST default to an empty collection if it's introduced in a release with a minor SemVer bump. SDKs SHOULD set the default for this option to the following value (or equivalent if the implementation doesn't admit pairs of integers) ``` [[301, 303], [305, 399], [401, 404]] From 0989b01bd98941901c4256c8e1023568975ff6ad Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Wed, 24 Sep 2025 15:22:43 +0200 Subject: [PATCH 11/12] Update traceIgnoreStatusCodes documentation Clarified the wording regarding HTTP status code ranges for the traceIgnoreStatusCodes option. --- develop-docs/sdk/telemetry/traces/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index aa004ef1b409d..fe39f423fcd6e 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -131,7 +131,7 @@ The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trac ### `traceIgnoreStatusCodes` This SHOULD be a collection of integers, denoting HTTP status codes. -If suitable for the platform, the option MAY also admit pairs of integers, denoting HTTP status code ranges. +If suitable for the platform, the collection MAY also admit pairs of integers, denoting inclusive HTTP status code ranges. The option applies exclusively to incoming requests, and therefore MUST only be implemented in server SDKs. From d338066563888fbf437f9d3d442cc4572732a7cd Mon Sep 17 00:00:00 2001 From: Lorenzo Cian <17258265+lcian@users.noreply.github.com> Date: Thu, 25 Sep 2025 10:40:45 +0200 Subject: [PATCH 12/12] Update documentation on SDK response status code handling --- develop-docs/sdk/telemetry/traces/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index fe39f423fcd6e..c69f5111c4319 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -135,7 +135,7 @@ If suitable for the platform, the collection MAY also admit pairs of integers, d The option applies exclusively to incoming requests, and therefore MUST only be implemented in server SDKs. -The SDK MUST honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span when it's finished. +The SDK MUST honor this option by inspecting the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute on each transaction/root span before it's finished. If the value of this attribute matches one of the status codes in `traceIgnoreStatusCodes`, the SDK MUST set the transaction's [sampling decision](https://develop.sentry.dev/sdk/telemetry/traces/#sampling) to `not sampled`. Note that a prerequisite to implement this option is that every HTTP server integration MUST record the [`http.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#:~:text=1437-,http.response.status_code,-int) attribute as defined in the OTEL spec.