Repository navigation
docs(dotnet): Update OTLP propagation docs for SDK 7.0.0 - #19924
Conversation
sentry-dotnet 7.0.0 stops AddSentryOtlpExporter from installing SentryPropagator and removes the defaultTextMapPropagator parameter (getsentry/sentry-dotnet#5319). Describe what gets propagated by default, how to add SentryPropagator for services that rely on sentry-trace, and when PropagateTraceparent helps. Raise the OpenTelemetry floor to 1.12.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
UseOtlp() stops the SDK creating transactions, so TracesSampleRate and TracesSampler are never read, and the OTLP exporter installs no OpenTelemetry sampler. Replace the "do not set TracesSampleRate" note with a Sampling section that points at the TracerProvider's sampler. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The plan checks client errors on the changed page, overall error volume, and pageload duration. An issue escalates when the changed page emits errors or error volume leaves the measured band. Services: Mention PlanWhat changedThe live .NET OTLP page now documents SDK 7.0.0 propagator behavior. AddSentryOtlpExporter no longer installs SentryPropagator and no longer accepts defaultTextMapPropagator. The page shows a CompositeTextMapPropagator snippet for readers who still need sentry-trace headers. sentry-docs must deploy before this change is live. RiskNew MDX can throw in Alert, code tabs, or PlatformLink during render. That failure hits this page first. A shared code-tab failure can also break other pages. Wrong text can make readers drop sentry-trace propagation after they upgrade. Intended effectThis change is documentation text. Telemetry cannot show that the new wording is live. Absent means the page still shows the old Planned Removal warning. Do not treat missing page views as absent intended effect. Regression watchWatch client failures on this page first. Then watch docs-wide error volume and pageload duration on the shared renderer.
Not observablePage-level pageload duration is not separable. Almost all pages share transaction |
|
PR looks good! We should probably keep it as a Draft until the v7.0.0 to avoid any premature merge risk. |
I've left it ready for review as a way to track what's actually complete vs still needs work on all the docs PRs we're planning for v7. I've added an alert warning at the to of the description instead - I think just you and me, we should be able to avoid merging anything by accident. |
<!-- Keep the urgency section so automation can prioritize this PR. You may delete other sections you don't need. --> ## DESCRIBE YOUR PR This PR adds the migration guide for version 7 of the Sentry SDK for .NET, ready for the public release candidate, `7.0.0-rc.2`. It follows the pattern of the Flutter v10 guide from #19390: - A full guide at `/platforms/dotnet/migration/v6-to-v7/`, built from one include per change in `includes/migration/dotnet-v7/`. - An interactive checklist at `/platforms/dotnet/migration/v6-to-v7/interactive/` that renders the same includes through `<MigrationGuide migration="dotnet-v7" />`. - An agent prompt callout that points at the guide's `.md` URL. - A "Migrating to 7.x" section at the top of the existing .NET migration page, which links to both. Both pages live under `common/`, so they render for every .NET guide, such as ASP.NET Core, MAUI, WPF and Serilog. Xamarin uses a separate SDK, so the new pages exclude it. I didn't move the 6.x, 4.x and 3.x sections, so every existing URL and anchor keeps working and the PR needs no redirects. To register the collection, the PR adds `dotnet-v7` to the `MIGRATIONS` map in the `MigrationGuide` component and to the validator's `COLLECTIONS` map, with specs for both. These changes in `src/components/migrationGuide/` and `scripts/` touch code that the JavaScript and Flutter guides share, so they need an approval from the docs team. For reference, msonnb approved the last change to the component in #19729, and andreiborza approved the JavaScript interactive guide that added it in #19076. The checklist shows one step only on the MAUI guide. Every other step applies to every .NET guide, because .NET apps combine integrations, such as a Serilog sink in an ASP.NET Core app. I checked the guide against `7.0.0-rc.2` from nuget.org and against the `version7` branch at getsentry/sentry-dotnet@a56c63455. The guide describes 7.0.0. Where rc.2 still behaves differently, the release candidate note at the top says so. ### Why this goes live during the release candidate I'd like to merge this as soon as it's approved, while 7.0 is still in release candidate. 7.0.0 GA is planned for 2026-11-30. People who try the release candidate need the guide now, and the agent prompt needs a published `.md` URL to point at. Two develop-docs rules pull in different directions here. [Managing Linear projects](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/managing-linear-projects/#visibility-for-major-releases) says docs "MUST NOT go live before the SDK ships". The [breaking changes playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes/#6-update-docs-and-changelog) says to publish the migration guide "before or alongside the major release". I read the first rule as protecting users from docs for code they can't get. Version `7.0.0-rc.2` is public on nuget.org, and the guide's first block says it's a release candidate and names that version. Other SDKs made the same call: - The Python 2.0 guide merged on 2024-02-28, while only the `2.0.0a1` alpha was out. Its note at the top said so. - The JavaScript v11 guide merged on 2026-09-08 with `11.0.0-beta.1` out, and its interactive version followed on 2026-09-11. - The Flutter v10 guide merged on 2026-10-05 with `10.0.0-rc.2` out, four days before 10.0.0. ### The release candidate note The guide opens with one `<Alert>`. It says there is no stable 7.0 yet, names `7.0.0-rc.2`, and says the rest of the .NET docs describe 6.x until 7.0.0 ships. It also covers what only the release candidate has: - `Logging.AddSentry()` after `ClearProviders()` doesn't add Sentry's logger providers back yet. That came with getsentry/sentry-dotnet#5776, after rc.2. - `DecompressionMethods` still includes Brotli, which getsentry/sentry-dotnet#5816 takes out of the default after rc.2. The note says how to leave it out until then. - An ASP.NET Core app that sends `ILogger` entries through NLog crashes with `Debug` on, tracked in getsentry/sentry-dotnet#5822. The guide's verify step turns `Debug` on, so the note says to leave it off in those apps. - Its `net11.0` builds depend on the .NET 11 release candidate versions of three `Microsoft.Extensions` packages. The rest of the guide describes 7.0.0 as released. At GA, I'll delete that one block from `includes/dotnet-v7-migration-overview.mdx`, and nothing else needs to change. ### What this PR leaves to other PRs This PR only adds the guide and what it needs. The reference pages are in other PRs, and this one doesn't need any of them to merge first: - Logs and the logging integrations: #19925 - `Microsoft.Extensions.Logging` and ASP.NET Core: #19961 - OpenTelemetry propagation: #19924 - Release and environment: #19960 - Hangfire monitor schedules: #19781 Three links in the guide point to the "Apps That Call UseSentry" sections that #19925 adds to the Serilog, NLog and log4net guides. Until #19925 merges, they open those guides at the top, and the migration guide sums up the same setups itself. There is no page for the new `Sentry.Extensions.Hosting` package yet. I'll link it from the guide once that page exists. Refs https://linear.app/getsentry/issue/NET-860 Refs getsentry/sentry-dotnet#5710 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [x] Urgent deadline (GA date, etc.): 2026-11-30 - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST _Make sure you've checked the following before merging your changes:_ - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: James Crosswell <jamescrosswell@users.noreply.github.com> Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
…arent Drop the internal DisableSentryTracing name, promise only sentry-trace from SentryHttpMessageHandler and SentryPropagator, and note that an undecided caller sends traceparent with the not-sampled flag. Co-authored-by: ric-oliv <5938598+ric-oliv@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
> [!NOTE] > This targets `dotnet-v7`, which collects the .NET docs for sentry-dotnet 7.0.0. #20641 merges that branch into `master` when 7.0.0 ships, so this PR can merge into `dotnet-v7` as soon as it's approved. ## DESCRIBE YOUR PR Updates the .NET logging docs for sentry-dotnet 7.0.0. In 7.0.0, `SentryOptions.EnableLogs` and `SentryOptions.EnableMetrics` are removed, Serilog, NLog and log4net send logs as soon as they're added, and the Serilog, NLog, log4net and Microsoft.Extensions.Logging integrations no longer initialize the SDK. The pages are written for 7.x. The docs aren't versioned, so this goes live with the rest of the 7.0.0 docs. - **Logs setup, options and usage** (`platform-includes/logs/*/dotnet.mdx`): `EnableLogs` is only documented on the host options (ASP.NET Core, AWS Lambda, Azure Functions, Blazor Server, Blazor WebAssembly, MAUI). The Serilog, NLog, log4net and Microsoft.Extensions.Logging snippets call `SentrySdk.Init` and add the integration without a switch. The host and Serilog/NLog/log4net sections explain when `EnableLogs` sends each log twice. - **Serilog, NLog and log4net guides**: initialize Sentry first, then add the sink/target/appender. Removed initializing through the integration, `InitializeSdk`, and the DSN, environment, release and `<options>` settings on the NLog target and log4net appender. Documented Serilog's `UseSerilog()` and the one-time standard-error warning. - **NLog includes**: removed `dsn` from the set-tag and set-user variants, including the `options.Dsn` that #19990 added to the set-tag snippet. Deleted the set-environment, set-release and config-intro variants, so the NLog guide uses the generic .NET pages, which set these on the options passed to `SentrySdk.Init`. - **Blazor WebAssembly**: removed `builder.Logging.AddSentry(o => o.InitializeSdk = false)`, which no longer compiles and was already redundant with `UseSentry`. - **Azure Functions**: installs `Sentry.Extensions.Hosting` instead of `Sentry.Extensions.Logging`, and starts Sentry with `.UseSentry(options => ...)` on the `HostBuilder` chain instead of `logging.AddSentry(options => ...)`. `EnableLogs = true` stays in the snippet, now on `SentryGenericHostOptions`. Apps with the ASP.NET Core integration (`ConfigureFunctionsWebApplication()`) call the same `UseSentry`. The "Changed in Version 7.0.0" alert covers 6.x, which has no hosting package. - **ASP.NET**: removed `EnableLogs` from the `SentrySdk.Init` snippet and from the list of features the snippet turns on. Send Logs now says the Serilog, NLog and log4net integrations send logs as soon as they're added, and points to `SetBeforeSendLog` for dropping them. - **Metrics options**: `EnableMetrics` was removed in 7.0.0. Kept the advice to return `null` from `SetBeforeSendMetric`. Closes getsentry/sentry-dotnet#5698 Part of getsentry/sentry-dotnet#5706 ### Notes for review - The Serilog, NLog and log4net guides each have a new "Capturing Startup Crashes" subsection for apps that want crashes from before `UseSentry` starts Sentry (getsentry/sentry-dotnet#5844). Each calls `SentrySdk.Init` before the builder; the Serilog one does it alongside Serilog's two-stage initialization. The companion samples, getsentry/sentry-dotnet#5847 and getsentry/sentry-dotnet#5866, link to them. - Merged `master` after #19990, which moved the .NET guides to the new quick start template. The Azure Functions and Blazor WebAssembly changes now sit on that template, which already uses `UseOtlp()` for Azure Functions. - The Microsoft.Extensions.Logging snippet on the logs setup page uses `SentrySdk.Init` plus `builder.Logging.AddSentry()`, and says in one sentence that generic-host apps use `UseSentry` from `Sentry.Extensions.Hosting` instead. The Microsoft.Extensions.Logging guide page is updated in #19961, so this PR only partly covers #5706. - Azure Functions follows getsentry/sentry-dotnet#5739. It adds `Sentry.Extensions.Hosting` with `UseSentry`, and says Azure Functions (isolated) apps use it, also with the ASP.NET Core integration. Checked against `version7`: `SentryGenericHostOptions.EnableLogs` defaults to `false`, and `UseSentry` registers Sentry's `ILogger` providers. `ConfigureFunctionsWorkerDefaults()` and `ConfigureFunctionsWebApplication()` return `IHostBuilder`, so the snippet binds to `UseSentry(IHostBuilder, Action<SentryGenericHostOptions>)`. The SDK starts in `Build()` and closes when the host stops. The `version7` sample makes the same call. getsentry/sentry-dotnet#5740 stops `Logging.AddSentry()` from registering `IHub`, so `UseSentry` is now also what puts it in DI. - The logs setup and options includes list `dotnet.extensions-hosting` in the `UseSentry` + `EnableLogs` sections, the `appsettings.json` tab and the Serilog/NLog/log4net expandables. That's the platform key of the generic-host guide coming in a separate PR, so that PR doesn't need to edit these files. Nothing links to it yet, since the page doesn't exist on this branch. Azure Functions isn't in the Serilog/NLog/log4net expandables: their snippets use `builder.Services` and `builder.Logging`, which a `HostBuilder` chain doesn't have. - "Before 7.0.0" notes appear only where a 6.x reader following the page would silently get no logs, or replace their SDK setup: the Serilog/NLog/log4net and Microsoft.Extensions.Logging sections of the logs setup page, the `EnableLogs` option, and the Azure Functions guide. - #5698 says an ASP.NET Core app that also uses the Serilog sink sends each log twice with `EnableLogs` on. That only happens when `ILogger` entries reach both Sentry's provider and Serilog. I checked against `version7`: one `LogInformation` call was sent once with `builder.Host.UseSerilog()`, which replaces the logger factory, and twice with `builder.Logging.AddSerilog()`. The same applies to NLog and log4net when they're registered as `ILogger` providers. So the docs name that case, registering the framework as an `ILogger` provider (for example `builder.Logging.AddSerilog()`), and say to leave `EnableLogs` off then. - #5706 describes `UseSerilog()` as the replacement for `ApplySerilogScopeToEvents()`. On `version7` it's optional: if the app doesn't call it, the sink registers the scope processor itself once it's running, so only events captured before then miss the `LogContext` properties. The guide says so. - Changes beyond the two issues: - `dotnet.blazor-server` added to the `EnableLogs` sections. It uses `Sentry.AspNetCore`'s `UseSentry`, but it fell into the plain `SentrySdk.Init` section, which now says logging integrations need no switch. - log4net logs usage no longer mentions `SentryAppender.Environment`, which 7.0.0 removes (getsentry/sentry-dotnet#5592). - The NLog set-user snippet used `new User`. That type doesn't exist, so it's now `SentryUser`. - The Azure Functions snippet drops `TracesSampleRate` and `DisableSentryHttpMessageHandler`, which the `version7` sample still sets. Under `UseOtlp()` Sentry creates no transactions of its own, so `TracesSampleRate` has no effect. `SentryHttpMessageHandler` already skips span creation, so disabling it would only stop it propagating `sentry-trace`. #19924 documents both. - The C# and F# snippets I added or changed compile against the `version7` sources. The Azure Functions and `UseSentry` ones compile against the 7.0.0-rc.2 packages, whose public API matches `version7`. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [x] Urgent deadline (GA date, etc.): 2026-11-30 - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: Not urgent, can wait up to 1 week+ 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## DESCRIBE YOUR PR This updates the .NET docs for sentry-dotnet 7.0.0, which has been on NuGet since 2026-11-12. Each change was reviewed in its own PR against the `dotnet-v7` branch, so the 7.x docs go live together: - #20311 docs(dotnet): Add a Generic Host guide for SDK 7.0.0 - #20642 docs(dotnet): Add supported versions to the MAUI guide for SDK 7.0.0 - #19960 docs(dotnet): Document release and environment resolution for SDK 7.0.0 - #19961 docs(dotnet): Update Microsoft.Extensions.Logging guide for SDK 7.0.0 - #19924 docs(dotnet): Update OTLP propagation docs for SDK 7.0.0 - #19925 docs(dotnet): Update logging docs for SDK 7.0.0 - #20715 docs(dotnet): Document ClearProviders() in the ASP.NET Core guide for SDK 7.0.0 - #20752 docs(dotnet): Tell .NET Framework apps to install Microsoft.Extensions.Logging for SDK 7.0.0 - #20743 docs(dotnet): Document NLog's MinimumLogLevel for SDK 7.0.0 - #20742 docs(dotnet): Link the Generic Host guide from the other .NET pages for SDK 7.0.0 - #20689 docs(dotnet): Update the 7.x migration guide for 7.0.0 - #20780 docs(dotnet): Fix Serilog flushing, Serilog usings and the Azure Functions package for SDK 7.0.0 - #20781 docs(dotnet): Fix the .NET logs and metrics examples and other pages for SDK 7.0.0 ### Issues this closes Closes getsentry/sentry-dotnet#5710 The other docs issues for 7.0.0 were closed when their PRs merged into `dotnet-v7`. ### Before merging - [x] sentry-dotnet 7.0.0 is on NuGet. - [x] The release candidate alert is gone from `includes/dotnet-v7-migration-overview.mdx`. - [x] The links that #20311, #19961 and #19925 left for after the other PRs merge are in. - [x] `master` is merged into `dotnet-v7`, and the Vercel preview looks right. - [x] This description has a `Closes` line for every issue that's still open. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [x] Urgent deadline (GA date, etc.): 2026-11-13 - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: Not urgent, can wait up to 1 week+ --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: James Crosswell <jamescrosswell@users.noreply.github.com> Co-authored-by: ric-oliv <ric-oliv@users.noreply.github.com> Co-authored-by: ric-oliv <5938598+ric-oliv@users.noreply.github.com> Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
Note
This targets
dotnet-v7, which collects the .NET docs for sentry-dotnet 7.0.0. #20641 merges that branch intomasterwhen 7.0.0 ships, so this PR can merge intodotnet-v7as soon as it's approved.DESCRIBE YOUR PR
Updates the .NET OTLP page for sentry-dotnet 7.0.0. From 7.0.0,
AddSentryOtlpExporterno longer installsSentryPropagator, and thedefaultTextMapPropagatorparameter is gone from it and fromUseOtlp(getsentry/sentry-dotnet#5319).SentryPropagatorbullet and the "Planned Removal" alert with a Trace Propagation section. It covers what gets propagated by default, how to addSentryPropagatorfor services that rely onsentry-trace, and whenPropagateTraceparenthelps. A short note covers the pre-7.0.0 behavior.defaultTextMapPropagatoroption.TracesSampleRatewith a Sampling section. WithUseOtlp()the SDK creates no transactions, soTracesSampleRateandTracesSamplerare never read, and the OTLP exporter installs no OpenTelemetry sampler. Sampling is configured on theTracerProvider. This is true for 6.x as well.Closes getsentry/sentry-dotnet#5546
Notes for review
Where the page differs from the issue, it follows the source on sentry-dotnet's
version7branch:PropagateTraceparentdoesn't help the OTLP service itself. OpenTelemetry's default propagator (W3C trace context plus baggage, which the OTel SDK installs) and the .NET runtime already sendtraceparent. OTel's HttpClient instrumentation also overwrites anytraceparentthatSentryHttpMessageHandleradds first. A local run against aversion7build sent identical headers with and without the option. The page recommends it for the Sentry-traced services that call the OTLP service, as/concepts/otlp/sentry-with-otel/already does.sentry-tracedoesn't disappear completely.UseOtlp()stopsSentryHttpMessageHandlerfrom creating spans, but its header propagation still runs (SentryMessageHandler.PropagateTraceHeaders). Sentry adds the handler toIHttpClientFactoryclients when it's set up through DI. Other requests only carrysentry-traceif the app configuresSentryPropagator.SentryPropagatoris still public inSentry.OpenTelemetry.Exporteronversion7, so the snippet doesn't need the deprecatedSentry.OpenTelemetrypackage. It derives fromBaggagePropagator, which is why the composite doesn't list that one separately. The snippet compiles against theversion7build with OpenTelemetry 1.12.0.IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace
YYYY-MM-DDwith the due date. You can update this information later by editing the PR description.SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
🤖 Generated with Claude Code