feat!: don't trace 301, 305-399 or 401-404 responses by default

[jamescrosswell]

Closes #4740

Summary

SentryOptions.TraceIgnoreStatusCodes now defaults to [301, (305, 399), (401, 404)] instead of an empty list. The option was added in #5034.

ASP.NET Core and ASP.NET apps, including ASP.NET Core apps instrumented with OpenTelemetry, no longer send a transaction for an incoming request that ends in one of those status codes: mostly infrastructure redirects (e.g. 307 from UseHttpsRedirection, 301 from rewrite rules) and 401–404 responses. Those requests rarely help with debugging, are often triggered by scanning bots, and use up span quota.

The issue originally asked for 404 only. We widened it to cover the other low-value codes so that this default only has to break once.

Why not the spec's default?

The SDK spec recommends [[301, 303], [305, 399], [401, 404]], but getsentry/sentry-docs#19658 adds a disclaimer that this default doesn't suit every framework, because some use 302/303 for successful redirects.

.NET is one of them. MVC's scaffolded Create/Edit/Delete actions end with RedirectToAction(...), and Razor Pages RedirectToPage(), LocalRedirect() after an Identity login, minimal APIs' Results.Redirect and Blazor static SSR's NavigateTo after a form post all send a 302. Those POSTs are where the database writes happen, so ignoring 302 would drop the most useful transactions in a typical app.

We therefore match sentry-ruby's default, which is the spec value minus 302/303. The cost is that cookie-auth challenges (an anonymous request to an [Authorize] page, redirected to the login page with a 302) are still traced.

Migration

To trace every request again, clear the list:

options.TraceIgnoreStatusCodes.Clear();

To ignore only some of these codes, replace the list, e.g. options.TraceIgnoreStatusCodes = [404];, or in appsettings.json:

"Sentry": {
  "TraceIgnoreStatusCodes": [ 404 ]
}

Setting "TraceIgnoreStatusCodes": [] in appsettings.json does not clear the default. Microsoft.Extensions.Configuration binds an empty JSON array as null (checked with the reflection and source-generated binders, 8.0 and 10.0), so the SDK can't tell "empty" from "not set". To opt out from configuration alone, set a status code that no response uses:

"Sentry": {
  "TraceIgnoreStatusCodes": [ 0 ]
}

Configuration can't express ranges yet, so keeping the default and adding a code from appsettings.json means listing every code. See #5644.

Notes for review

• The spec also requires dropped transactions to be logged and recorded as event_processor client-report discards. SentryClient.CaptureTransaction already does both for any transaction processor that returns null.
• Depends on fix: TraceIgnoreStatusCodes no longer drops outgoing HTTP requests traced with OpenTelemetry #5643 reaching version7 first. With OpenTelemetry, an outgoing HttpClient call with no local parent becomes an http.client transaction of its own, and the processor on main drops it when the downstream status matches the list. This PR's default would turn that on for every ASP.NET Core app using OpenTelemetry. fix: TraceIgnoreStatusCodes no longer drops outgoing HTTP requests traced with OpenTelemetry #5643 limits the processor to http.server transactions, as the spec requires. Outgoing calls that are child spans of a request were never affected.
• The sentry-docs migration guide has no 7.x section yet. The Migration section above is written so it can be copied into that guide.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (version7@aa02031). Learn more about missing BASE report.

Additional details and impacted files

@@             Coverage Diff             @@
##             version7    #5632   +/-   ##
===========================================
  Coverage            ?   74.76%           
===========================================
  Files               ?      515           
  Lines               ?    18910           
  Branches            ?     3689           
===========================================
  Hits                ?    14139           
  Misses              ?     3894           
  Partials            ?      877           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sentry]

Bug: Configuring TraceIgnoreStatusCodes via a configuration file incorrectly replaces the new default values instead of appending to them, causing more transactions to be traced.
_{Severity: MEDIUM}

Suggested Fix

Update the configuration binding logic to merge user-provided values from the configuration file with the default values, rather than replacing them. The logic should append values from BindableSentryOptions.TraceIgnoreStatusCodes to the existing options.TraceIgnoreStatusCodes list.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/Sentry/SentryOptions.cs#L954-L961

Potential issue: The configuration binding logic for `TraceIgnoreStatusCodes` replaces
the entire default list if any values are provided in a configuration file, such as
`appsettings.json`. This is due to a null-coalescing assignment (`??`) that was not
updated to handle the new, non-empty default list. As a result, users who customize this
setting to add their own status codes will unintentionally lose the new default ignored
codes (e.g., 401-404). This can lead to an unexpected increase in traced transactions
and higher span quota consumption, as status codes that were intended to be ignored by
default will now be traced.

Also affects:

• test/Sentry.Tests/BindableSentryOptionsTests.cs:26~67

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[jamescrosswell]

That's not a bug - it's by design. We provide some defaults but people can override these via configuration. Otherwise there would be no way to remove any of our defaults via configuration (it would have to be configured in code).

[ric-oliv]

Nice! Looks good to me, the Agent found a couple of things regarding outgoing HTTPCalls:

The new default also drops outgoing calls under OpenTelemetry

The description says outgoing HTTP spans are unaffected. That holds for child spans. With OpenTelemetry, though, an HttpClient call with no local parent becomes a transaction of its own, with the operation http.client. That happens in a BackgroundService, a timer, startup code, or a queue consumer that picked up a remote traceparent. SentrySpanProcessor.OnEnd copies http.response.status_code onto that transaction. SentryAspNetCoreOptionsSetup registers TraceIgnoreStatusCodeTransactionProcessor for the whole hub, so the processor drops it.

I reproduced this with a real HttpClient call to a local HttpListener. The call went through the System.Net.Http ActivitySource, SentrySpanProcessor, and a real Hub and SentryClient with a mocked background worker.

Remote status	TraceIgnoreStatusCodes	http.client transaction sent?
404, 401, 403	default	no
200	default	yes
404	cleared	yes

The spec says the option "applies exclusively to incoming requests". The processor has behaved this way since #5034, but until now it only affected people who set the list themselves. This PR turns it on for every ASP.NET Core app that uses OpenTelemetry. A 401 or 403 from a downstream API usually means expired credentials, which people want to see.

Skipping http.client transactions in the processor fixes it:

if (_options.TraceIgnoreStatusCodes.Count == 0 || transaction.Operation == "http.client")

With that change, the SDK sends all three cases again, and SentrySpanProcessorTests and TraceIgnoreStatusCodeTransactionProcessorTests still pass. ASP.NET Core, ASP.NET and the OpenTelemetry server spans all use http.server. Matching on http.server would also work, but the existing processor tests use "operation" as the operation and would need updating. I'd ship this as a small fix: on main that lands before this PR. If we don't, the description's line about outgoing spans needs to change.

Configuration

• I confirmed that "TraceIgnoreStatusCodes": [] keeps the default, and so does "". Setting [ 0 ] does opt out from configuration, though. With it, the SDK traced 301, 307, 401 and 404. The Migration section currently tells configuration-only users they need code to opt out, so it's worth adding this there.
• The bindable property is a List<int>, so configuration can't express ranges. [ "305-399" ] throws InvalidOperationException at startup. To keep the default and add one code from appsettings.json, you'd have to list about 100 integers. This isn't a blocker, but a follow-up could accept strings like "305-399".
• I agree with your reply to the bot. Replacing the list is the only way to remove a default from configuration.

Smaller things

• The repo squash-merges with the commit messages as the body. The first commit's message says the default is [(301, 303), ...] and calls that "the value the SDK spec recommends". That text will end up on the branch, so it's worth trimming when you merge.
• The .NET options page in sentry-docs doesn't document TraceIgnoreStatusCodes. 7.0 needs an entry there as well as the migration guide text.

[jamescrosswell]

Thanks @ric-oliv, great catch on the OpenTelemetry one.

• Outgoing calls under OpenTelemetry: fixed on main in fix: TraceIgnoreStatusCodes no longer drops outgoing HTTP requests traced with OpenTelemetry #5643. Rather than skipping http.client, the processor now only filters http.server transactions. That matches the spec's "applies exclusively to incoming requests" wording, and it also leaves alone any other root transaction that carries a status code. ASP.NET Core, ASP.NET and OTel server spans all use http.server, and I added a test pinning the OTel mapping. This PR's description now notes that fix: TraceIgnoreStatusCodes no longer drops outgoing HTTP requests traced with OpenTelemetry #5643 needs to reach version7 first.
• [ 0 ] from configuration: added to the Migration section as the configuration-only opt-out.
• Ranges in configuration: opened Support status code ranges when configuring TraceIgnoreStatusCodes from appsettings.json #5644, proposing a List<string> bindable that accepts both "404" and "305-399".
• Squash message: I'll trim the first commit's body when merging.
• sentry-docs: agreed. I'll add the options entry and the 7.0 migration text closer to the release.