feat(serilog)!: the Sentry sink no longer initializes the SDK

[jamescrosswell]

The Serilog portion of #5245, following the design in this comment. The Sentry sink for Serilog now only configures the sink; Sentry has to be initialized separately via SentrySdk.Init, UseSentry, etc.

Part of #5245

Breaking changes

• SentrySerilogOptions no longer derives from SentryOptions. It carries only sink settings: MinimumEventLevel, MinimumBreadcrumbLevel, FormatProvider, TextFormatter, RestrictedToMinimumLevel, LevelSwitch. Anything else (Dsn, Release, SampleRate, …) belongs on the options used to initialize Sentry.
• SentrySerilogOptions.InitializeSdk is removed.
• The WriteTo.Sentry(string dsn, …) overload is removed. Note that Serilog.Settings.Configuration does not fail when a configuration still supplies dsn: it filters candidate methods on the method's own parameters, so unmatched arguments are dropped silently — not even to SelfLog. The sink is attached, Sentry is never initialized, and the app reports nothing. feat(serilog): configuring a DSN on the sink now fails with a migration error #5611 stacks a tombstone overload on this branch to turn that into a loud failure.
• ApplySerilogScopeToEvents() is renamed UseSerilog(), to match UseOpenTelemetry(). It returns void like its siblings and is now idempotent.
• A WriteTo.Sentry(o => …) configuration that only sets sink settings still compiles, and nothing in the API can catch it. On 6.x that overload initialized the SDK itself (InitializeSdk defaulted to true), taking the DSN from SENTRY_DSN or a [Dsn] assembly attribute; now the sink is attached, Init is never called, and every event is dropped. The sink therefore warns at runtime: on the first log event at or above MinimumEventLevel, if Sentry is not initialized but a DSN can still be found, it writes one line to Serilog's SelfLog and to standard error, at most once per sink. Thanks to @ric-oliv for spotting this.
• Events and structured logs no longer report sentry.dotnet.serilog as the SDK name. Sdk.Name identifies the integration that initialized Sentry, and the sink identifies itself through the log origin (auto.log.serilog). See Metrics and SentrySdk.Logger logs emitted during a request carry no sentry.sdk.name/sentry.sdk.version on ASP.NET Core #5497.

Before:

Log.Logger = new LoggerConfiguration()
    .WriteTo.Sentry(o =>
    {
        o.Dsn = "...";
        o.MinimumEventLevel = LogEventLevel.Error;
    })
    .CreateLogger();

After:

using var _ = SentrySdk.Init(o =>
{
    o.Dsn = "...";
    o.UseSerilog();
});

Log.Logger = new LoggerConfiguration()
    .WriteTo.Sentry(o => o.MinimumEventLevel = LogEventLevel.Error)
    .CreateLogger();

Notes for review

• UseSerilog() registers the processor that copies Serilog LogContext properties onto events. It has to live on the SentryOptions used for init, because it enriches every event, not only ones the sink creates. To keep that discoverable, the sink logs a one-time diagnostic warning when it's missing (only visible with Debug = true).
• The old WriteTo.Sentry(o => …) overload initialized the SDK but never registered that processor — only the dsn parameter overload did. That's why IntegrationTests.Simple snapshots gain inventory/MyTaskId tags: the test now calls UseSerilog(), and the processor is actually running.
• The runtime warning writes to standard error as well as SelfLog because there is no DiagnosticLogger to write to when the SDK was never initialized, and SelfLog only reaches people who already suspect a problem. It is gated on a DSN being discoverable, so an app that deliberately runs without Sentry stays quiet. The shared policy lives in Sentry.Internal.UninitializedSdkWarning; each integration supplies its own channel and message.
• The sink no longer implements IDisposable. It never owned the hub, so Log.CloseAndFlush() no longer disposes the SDK; disposing the handle from SentrySdk.Init does that.
• SerilogAspNetSentrySdkTestFixture was initializing the SDK twice (once via WriteTo.Sentry(ValidDsn), then again via UseSentry); it now only initializes via UseSentry.
• ApiApprovalTests.Run.Net4_8.verified.txt can't regenerate on macOS; it was byte-identical to the DotNet10_0 snapshot before this change, so it's a copy of the regenerated one.

NLog, log4net and Microsoft.Extensions.Logging follow separately. The generic host replacement for builder.Logging.AddSentry(dsn) is tracked in #5572.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 91.78082% with 6 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (version7@aa02031). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/Sentry/Internal/ConcurrentBagLite.cs	37.50%	5 Missing ⚠️
src/Sentry.Serilog/SentrySink.cs	96.42%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             version7    #5573   +/-   ##
===========================================
  Coverage            ?   74.73%           
===========================================
  Files               ?      516           
  Lines               ?    18866           
  Branches            ?     3676           
===========================================
  Hits                ?    14100           
  Misses              ?     3892           
  Partials            ?      874           

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

[ric-oliv]

Nice @jamescrosswell! Assuming we agree with this direction (Logging extension only configures the sink and does not inits the SDK), I think it's looking pretty good!

• We should probably remove the Dsn (not used anymore) and the the EnableTracing (never used) properties from the appsettings.json example.
• While testing the Serilog sample project (as a user upgrading and not initializing the Sentry SDK manually), I don't get any crash or warning... the SDK configures the sink, but no-ops on the execution. It might be worth checking if we should crash the SDK (or log via another channel) in this scenario.
• Having the SDK initialized but not calling "UseSerilog()" is only going to show up in the logs as a warning, and only if we have debug = true. This feels a bit prone to issues with integrators forgetting to call "UseSerilog()" and not seeing any information at all about the issue. It would be great is we could somehow make the SDK itself register the SerilogScopeEventProcessor and avoid the call completely. Not sure if we can do this though.

Other than that, I believe we're good to merge this PR!

[jamescrosswell]

• We should probably remove the Dsn (not used anymore) and the the EnableTracing (never used) properties from the appsettings.json example.

Good call. Done in 0aada87

[jamescrosswell]

• While testing the Serilog sample project (as a user upgrading and not initializing the Sentry SDK manually), I don't get any crash or warning... the SDK configures the sink, but no-ops on the execution. It might be worth checking if we should crash the SDK (or log via another channel) in this scenario.

I'm guessing we're talking about the scenario where someone initialises both Serilog and the Sdk via configuration bindings (e.g. appsettings.json)... and yeah, that's an issue since they wouldn't get any compiler warnings letting them know the DSN is no longer used.

We could try to bind to the DSN value in the logging config... not because we actually want to use it but just to check if someone has erroneously configured it there and so that we can show them a warning?

EDIT: did a bit of research on this...

Serilog.Settings.Configuration automatically populates an IConfiguration parameter on a sink method, so we could add an IConfiguration parameter and use this to walk the config and check for a DSN configuration. However we'd need to add a new public dependency on Microsoft.Extensions.Configuration.Abstractions to Sentry.Serilog to do that, purely to produce this warning for the upgrade to v7.x.

Normally I'd be against adding a dependency for a single warning... however this is a fairly major change and most apps would have that particular dependency already anyway, so we could do it.

Also Serilog.Settings.AppSettings (the XML app.config provider, still relevant for net462) binds args by name too and IConfiguration injection won't reach it.

@ric-oliv thoughts?

[jamescrosswell]

• Having the SDK initialized but not calling "UseSerilog()" is only going to show up in the logs as a warning, and only if we have debug = true. This feels a bit prone to issues with integrators forgetting to call "UseSerilog()" and not seeing any information at all about the issue. It would be great is we could somehow make the SDK itself register the SerilogScopeEventProcessor and avoid the call completely. Not sure if we can do this though.

That one's trickier... the call to initialise the SDK is made from the Sentry library... whereas the call to UseSerilog is made from the Sentry.Serilog library. SentrySdk.Init doesn't know whether the Sentry.Serilog package has been added to the user's project or not and, even if it did, it wouldn't have access to the SerilogScopeEventProcessor type via any means other than reflection (which we can't really use - it breaks AOT compilation).

The only other mechanisms that I can think of are:

• An analyzer (that warns people if they've included the Sentry.Serilog integration but not called UseSerilog()
• A source generator (that takes the analyser one step further)
• Maybe some solution with module initialisers.

I think any of those is a fairly complex piece of work that would have lots of edge cases and testing (given that people can initialise both Sentry and Serilog either from code and/or from configuration bindings, we don't know the order of initialisation, init logic may be delegated to code from other external modules etc.). If we do want to tackle it, I think it's a separate issue/PR and probably safer to assume we won't get it done before v7.

[ric-oliv]

I'm guessing we're talking about the scenario where someone initialises both Serilog and the Sdk via configuration bindings (e.g. appsettings.json)

Exactly!

@ric-oliv thoughts?

How do you feel about keeping the SentrySinkExtension "Sentry" with the DSN as an obsolete overload that will throw an exception whenever bounded to? (instead of deleting it).
That way, any integrator that does not change the implementation will immediately have an exception instead of only loosing the logs. We could then remove this overload in v8.

I'll create a PR into this branch so you can have a look if it's a good approach.

As a side-note: the PR description says that the config-bound dsn args "will no longer bind to a Sentry sink method", but they do bind, that's why the issue is silent.

[ric-oliv]

That one's trickier... the call to initialise the SDK is made from the Sentry library... whereas the call to UseSerilog is made from the Sentry.Serilog library. SentrySdk.Init doesn't know whether the Sentry.Serilog package has been added to the user's project or not and, even if it did, it wouldn't have access to the SerilogScopeEventProcessor type via any means other than reflection (which we can't really use - it breaks AOT compilation).

Yes, and we might be able to use SentryOptions to automatically register the SerilogScopeEventProcessor in the SentrySink.
We could potentially call it both in the SentrySink constructor and in the Emit method.

The only issue currently is that SentryOptions keeps the processors in Lists, and SentryClient enumerates those lazily for the whole duration of a capture, so adding one from another thread throws. We can solve it by changing those to a ConcurrentBagLite and adding a couple of auxiliary methods.

In this case, the user should still call UseSerilog() to catch any error that occurs before the SentrySink is initialized, but if it isn't called then we still manage to recover and register ourselves.

One thing I ran into while testing (unrelated to this PR) was the Emit method answering a reentrant log event with another diagnostic. This caused Serilog to route that back into the sink, and each message embeds the previous one. The IsSentrySdk filter that would break the cycle sits in InnerEmit, after the reentrancy branch has already returned.
This can be reproduced in the AspNetCore.Serilog sample with DiagnosticLevel: Info and no UseSerilog(), the Moving the filter above the reentrancy check fixes it (we can also fix that in a separate PR).

I've drafted #5612 just so you have an idea... the test suite passes but we might need to discuss it more. Your call if we follow this path or not (totally fine you see a problem with the approach, or if we should break this down in separate PRs, etc.)

[ric-oliv]

Hi @jamescrosswell,
I missed a couple of things here previously.

1. There's still a path where Sentry silently stops working: the WriteTo.Sentry(o => …) callback with only sink settings (e.g. o.MinimumEventLevel = …), where the DSN comes from SENTRY_DSN or [assembly: Dsn(...)] (SettingLocator). On 6.x that overload initialized the SDK itself, because InitializeSdk defaulted to true. With this PR the code still compiles, no dsn reaches the tombstone, nothing calls Init, and the sink drops everything without any output. It's also the first sample under Configure in the Serilog docs (which we will need to update as well once this is merged).

I tested that sample with a Log.Error(...) call:

• version7 with SENTRY_DSN set: SDK enabled, event captured.
• version7 without it: the app crashes at startup (You must supply a DSN), so anyone running this pattern today gets their DSN from the environment or the attribute.
• This PR, either way: SDK disabled, event dropped, exit code 0, nothing printed.

We can't make it fail at startup, because logging before UseSentry initializes is legitimate (bootstrap loggers). But we could signal it once at runtime. On the first event at or above MinimumEventLevel, if Sentry isn't initialized and a DSN can be found, write one line to SelfLog and to Console.Error. SelfLog alone only reaches people who have enabled it, so it wouldn't help anyone who doesn't know something is wrong. Either way, I think this belongs under Breaking changes, with a migration note.

[ric-oliv]

2. LogContext properties now become tags on every event, for everyone using the sink.

Before this PR, SerilogScopeEventProcessor was only registered if the app called ApplySerilogScopeToEvents() (which isn't in our docs or samples) or used the WriteTo.Sentry("dsn") overload, which called it internally. Everyone else, including the common UseSentry + WriteTo.Sentry() setup, only saw LogContext properties as extras on events created from log lines, and only if the logger had Enrich.FromLogContext().

With the automatic registration from my last PR here, the sink registers the processor itself, in its constructor or on its first log event. So for everyone using the sink, LogContext properties are now added as tags on every event: unhandled exceptions and SentrySdk.CaptureException included, not just events created from logs.

This matches Sentry.Extensions.Logging, where BeginScope key/values become tags on the Sentry scope by default. Since ApplySerilogScopeToEvents() was never documented, I think having this on by default is what users expect from the integrationbut Serilog and MEL integrations still differ in a few ways:

• Which values: MEL keeps only string values (UserId = 42 is dropped). Serilog converts every property with ToString().
• When they're read: MEL copies the values into the Sentry scope when BeginScope is called. Serilog reads LogContext each time an event is captured.
• Opt-out: MEL can be customised or switched off through the public SentryOptions.SentryScopeStateProcessor. The Serilog processor is internal, so it can't be removed or replaced.
• Global mode (MAUI, desktop): MEL's PushScope does nothing there. The Serilog processor still runs.
• Coverage from startup: MEL applies from the moment Sentry is initialised. The automatic registration only applies from when the sink is created or first used. Calling UseSerilog() closes that gap.

Suggestions:

• Keep the automatic registration. Under our logging policy, adding the sink is the user signal, and requiring UseSerilog() on top would effectively be a double opt-in.
• List it under Breaking changes, e.g. "Events now include Serilog LogContext properties as tags", and if needed we can also mention in the migration notes how to remove unwanted keys with SetBeforeSend (plus SetBeforeSendFeedback, since feedback also goes through event processors).

What do you think?

[jamescrosswell]

Serilog and MEL integrations still differ in a few ways:

Most of those things were true before this PR... we can create a follow up issue to try to make these more consistent. Some of the differences may be necessary due to functional differences between MEL and SeriLog though.

The only one that's actually changed is the last one. With WriteTo.Sentry(dsn) the sink was the init, and that gap disappears once we merge #5595... which makes the same true for MEL.

I've added a follow up to look into this - I think it can be prioritised separately though (not a stopper for v7):

• Try to make MEL and Serilog integrations behave more consistently #5635

Keep the automatic registration. Under our logging policy, adding the sink is the user signal, and requiring UseSerilog() on top would effectively be a double opt-in.

Agreed.

List it under Breaking changes, e.g. "Events now include Serilog LogContext properties as tags", and if needed we can also mention in the migration notes how to remove unwanted keys with SetBeforeSend (plus SetBeforeSendFeedback, since feedback also goes through event processors).

Yeah sure, we'll have all this in the release notes for version 7.0.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 2925072. Configure here.}

[cursor]

Shutdown logs warn SDK never initialized

Low Severity

A disabled hub after Close or disposing the Init handle is treated the same as never initializing. If SENTRY_DSN (or a Dsn attribute) is still present, a later event-level log can write the one-time stderr warning telling the app to call SentrySdk.Init, even when Sentry was initialized correctly and then shut down.

Additional Locations (1)

• src/Sentry/Internal/UninitializedSdkWarning.cs#L19-L34

 

^{Reviewed by Cursor Bugbot for commit 2925072. Configure here.}

[jamescrosswell]

Highly unlikely... that implies the SDK has been initialised, the app has been running and the SDK closed all before a single log is made (since the warning only ever fires once - it will only be triggered by the first log message if the SDK is not initialised at that time).

[jamescrosswell]

Suggestions:

* Keep the automatic registration. Under our logging policy, adding the sink is the user signal, and requiring `UseSerilog()` on top would effectively be a double opt-in.

* List it under Breaking changes, e.g. _"Events now include Serilog LogContext properties as tags"_, and if needed we can also mention in the migration notes how to remove unwanted keys with `SetBeforeSend` (plus `SetBeforeSendFeedback`, since feedback also goes through event processors).

What do you think?

@ric-oliv implemented across all 4 PRs - adds a bit of complexity but for the transition from version6 to version7, probably worth keeping. We can always remove this in a later version.

[ric-oliv]

Looks good!

I think we just need to update the PR title to state the breaking change (e.g.: feat(serilog)!: ….), since this will probably otherwise land under Features in the release notes, right? Same for the others #5585, #5592 and #5595.