Skip to content

feat(develop): document traceIgnoreStatusCodes #15026

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
lcian merged 13 commits into from
Sep 26, 2025
Merged

feat(develop): document traceIgnoreStatusCodes #15026

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
5c2efd2
feat(develop): document `traceIgnoreStatusCodes`
lcian Sep 23, 2025
be05c7d
Merge branch 'master' into lcian-patch-2
lcian Sep 24, 2025
10d3acb
Update index.mdx
lcian Sep 24, 2025
7a65ec9
Update index.mdx
lcian Sep 24, 2025
b63f762
Change log level from info to debug for dropped transactions
lcian Sep 24, 2025
02622df
Update traceIgnoreStatusCodes documentation
lcian Sep 24, 2025
19495d7
Update index.mdx
lcian Sep 24, 2025
3333f4f
Clarify traceIgnoreStatusCodes requirements and defaults
lcian Sep 24, 2025
f0e4dd1
Update index.mdx
lcian Sep 24, 2025
d8c8502
Update index.mdx
lcian Sep 24, 2025
5e88107
Update terminology for default option in SDK docs
lcian Sep 24, 2025
0989b01
Update traceIgnoreStatusCodes documentation
lcian Sep 24, 2025
d338066
Update documentation on SDK response status code handling
lcian Sep 25, 2025
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
28 changes: 28 additions & 0 deletions develop-docs/sdk/telemetry/traces/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,34 @@ Header Format:

The full spec is available in the [W3C Trace Context](https://www.w3.org/TR/trace-context/) specification.

### `traceIgnoreStatusCodes`

This SHOULD be a collection of integers, denoting HTTP status codes.
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.

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.

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 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]]
```
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 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

As of writing, transactions are implemented as an extension of the `Event`
Expand Down
Loading