Skip to content

docs(samples): capture startup crashes in the ASP.NET Core NLog sample - #5866

Merged
ric-oliv merged 1 commit into
version7from
ai/nlog-startup-crash-sample
Nov 4, 2026
Merged

ric-oliv merged 1 commit into
version7from
ai/nlog-startup-crash-sample

Conversation

@jamescrosswell

Copy link
Copy Markdown
Collaborator

In v7 the logging integrations no longer initialize the SDK, so an ASP.NET Core app that only calls UseSentry loses crashes that happen before UseSentry starts Sentry, when the app starts running. This updates the ASP.NET Core NLog sample the same way #5847 updated the Serilog one:

  • SentrySdk.Init runs at the top, before the NLog configuration, and UseSentry takes over once the app is running.
  • The builder, Build() and Run() are wrapped in try/catch/finally. The catch logs the crash at Fatal through NLog and returns 1. The finally calls LogManager.Shutdown().

Checked against a local mock Sentry server: a throw before Build() and one between Build() and Run() each send exactly one fatal event through the early init. A Run() failure (port already in use) sends one event through UseSentry, and duplicate detection drops the fatal log from the catch.

The comment links to https://docs.sentry.io/platforms/dotnet/guides/nlog/#capturing-startup-crashes. getsentry/sentry-docs#19925 adds that section, so the link 404s until that PR is merged.

Refs #5844

#skip-changelog

🤖 Generated with Claude Code

UseSentry only starts Sentry once the app is running, so crashes during
startup were lost. Initialize Sentry early as well and log startup
failures at Fatal through NLog before exiting.

Refs #5844

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.77%. Comparing base (d28aa8b) to head (b78504f).
⚠️ Report is 4 commits behind head on version7.

Additional details and impacted files
@@            Coverage Diff            @@
##           version7    #5866   +/-   ##
=========================================
  Coverage     76.76%   76.77%           
=========================================
  Files           539      539           
  Lines         19694    19697    +3     
  Branches       3851     3852    +1     
=========================================
+ Hits          15119    15122    +3     
  Misses         3703     3703           
  Partials        872      872           

☔ 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.

@jamescrosswell
jamescrosswell marked this pull request as ready for review November 3, 2026 23:17
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 3, 2026

@ric-oliv ric-oliv left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, LGTM!

@ric-oliv
ric-oliv merged commit 2605151 into version7 Nov 4, 2026
35 checks passed
@ric-oliv
ric-oliv deleted the ai/nlog-startup-crash-sample branch November 4, 2026 14:28
jamescrosswell added a commit that referenced this pull request Nov 4, 2026
…Serilog sample (#5871)

Main now initializes Sentry too, so "Sentry is initialised below" no
longer reads right. Matches the NLog sample's wording from #5866.

Refs #5844

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
jamescrosswell added a commit to getsentry/sentry-docs that referenced this pull request Nov 11, 2026
> [!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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants