Different sentry options in UseSentry() and Init() + where are the docs?

[Patrick-Glatt-Vitra]

Hi, I'm a bit confused.
I have different available sentry options.
Also I'm not sure if I'm searching on the wrong place for the option documentation or if there are some missing documentations.

First. I use sentry in a .net WebApi which is .net 7 based and using some ASP.NET Core packages
Via the nuget package manager the package "Sentry.AspNetCore" and package "Sentry" is installed.
Sentry is firstly initialized via UseSentry() method on WebHostBuilder and later, if configuration have to be change at runtime, via the SentrySdk.Init() method.

First question here. Maybe I already messed up here some things. Is there maybe already a duplication of integrating two different Sentry SDK packages via nuget packages which leads to my other following issues?

Second question. Somhow the SentryOptions available in the UseSentry() method are different then the ones I can use in SentrySdk.Init() method. Why?
Example:
builder.UseSentry(options => { // options. MinimumBreadcrumbLevel //available here}
SentrySdk.Init(options => { // options. MinimumBreadcrumbLevel //not available here});

Update: Ah in UseSentry() the SentryAspNetCoreOptions are used which inherit from SentryLoggingOptions which inherit from SentryOptions. Therefore there are more options available in UseSentry(). In Init() I have only the very basic options of SentryOptions available.

Last Question. Seems I can't find all the available options in the documentation.
For Example I can use the options.DeduplicateMode but if I search it on https://docs.sentry.io/platforms/dotnet/configuration/ the DeduplicateMode option is not listed there. Where are the docs to all this options? Some info's I already found in the coding for ex. in the SentryOptions calls, enum classes etc but they are short and not easy to understand for someone new at sentry.

[mattjohnsonpint]

Our packages are layered. Initialization and options follows suit.

• Package: Sentry is the base package.
  • If used alone, initialize via SentrySdk.Init.
  • The options class is SentryOptions.
• Package Sentry.Extensions.Logging depends on Sentry.
  • If used alone, initialize via ILoggingBuilder.AddSentry. It will initialize Sentry internally.
  • The options class is SentryLoggingOptions, which extends SentryOptions.
• Package Sentry.AspNetCore depends on Sentry.Extensions.Logging.
  • Initialized via IWebHostBuilder.UseSentry. It will initialize Sentry.Extensions.Logging and Sentry internally.
  • The options class is SentryAspNetCoreOptions, which extends SentryLoggingOptions.

There's a similar hierarchy for other package types, such as Sentry.Maui.

In most cases - you should only ever initialize once, and from the highest level package that you are using. For ASP.NET Core, call UseSentry, and don't call SentrySdk.Init after the host is built and running.

The only valid reason to use SentrySdk.Init in an ASP.NET Core app is if you want to catch errors from your web initialization startup itself. In that case, you'd call SentrySdk.Init at the very top of Program.cs before anything else has run. When the builder runs, it will re-initialize through UseSentry, and overwrite the original configuration. (It will also flush and dispose the internal hub and background worker associated with the original initialization, and start new one - but you probably don't need to worry about that.). Most people don't do this, because it's fairly evident when an web server fails during the initialization phase.

You said:

... if configuration have to be change at runtime ...

Everything is at runtime, so I presume you mean after the app is initialized and receiving web requests. It's not a good idea to try to change the configuration at this point. If you have some specific reason to do so, please let me know so we can evaluate an alternative.

Last Question. Seems I can't find all the available options in the documentation.

Yeah, we do our best to keep on top of docs, but it's certainly possible we've missed some along the way.

For Example I can use the options.DeduplicateMode

That was added in #363, and it looks like indeed we forgot to add docs at that time. I'll make a note to do so. (FWIW, it's a rarely used option.)

Thanks for the feedback!

[mattjohnsonpint]

I think BeforeSendTransaction is too late to change the sample rate. The decision has already been made by then. You might try using a custom TracesSampler function though.

I do think we should consider making the configuration adjustable at runtime without reinitialization. The IOptions<T> pattern does allow for that, and many configuration providers are dynamically updatable. We just don't currently listen for changes. It might take some work on our part to get there though. Likely a v4 thing.

[mattjohnsonpint]

@Patrick-Glatt-Vitra - To answer some of your questions:

The only way I found mentioned on the internet was that I could use the SentrySdk.Init() over and over again which would be a way to change the sentry options without a restart of the application. This wont work? Could you maybe explain me shortly why its not possible? Is sentry nested deep and would affect running threads etc in a thread heavy application?

The current design of the Sentry .NET SDK is to only ever allow one hub running at any given time. If you re-initialize, you're replacing the current hub with a new one. Any events or transactions captured on the current hub will be flushed and the hub will be disposed, while a new one starts up. This will mostly work, but there are a few bugs with certain options - mainly caching (see #2033).

There are other more subtle issues for example, consider:

using Sentry;

const string DSN = "... your dsn ...";

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseSentry(options =>
{
    options.Dsn = DSN;
});

var app = builder.Build();

app.MapGet("/", () =>
{
    SentrySdk.CaptureMessage("Test 1");

    SentrySdk.Init(options =>
    {
        options.Dsn = DSN;
    });

    SentrySdk.CaptureMessage("Test 2");

    return "ok";
});

app.Run();

Both messages will be captured and sent to Sentry, but only the first one will have HTTP request context information attached (such as headers. Also, if you have tracing enabled in a similar setup, only the first captured message will be part of the trace. There are probably dozens of other little things that can go wrong here. The main reason is that the SentryMiddleware and SentryTracingMiddleware capture things like context and transaction to the current scope - which is part of the hub. If you reinitialize, you're replacing the hub - and thus losing the current scope.

I put the init inline the request in this example, which you probably wouldn't do. But even if you put it on some background thread - it would take effect immediately because everything goes back to the current hub attached to the SentrySdk, accessed via the HubAdapter. So it might as well be inline a request, because you could easily have requests in progress when such reinitialization occurred.

A lot of this is getting into our internals, which we could improve upon in a future version. We could allow multiple simultaneous hubs, for example. We could also allow SentryOptions to be updatable without reinitialization. Or perhaps there are some options that are immutable and some options that are updatable. This would need a lot of re-thinking and design work, and some consideration of priority, how much value it adds vs the time it would take, etc. TBH, At the moment, it's not a high priority.

Did I get it right that you overwrite the CurrentHub with the new hub and dispose the old one? This would mean, using Init() again would do the job of changing the current running sentry options by creating a new hub and dispose the old hub?

Yes, but as mentioned, anything on the current scope is lost. Perhaps an easier example to understand would be breadcrumbs. Add a breadcrumb, then re-init and capture an event. The breadcrumb will be lost.

Looks like if I would call Init() with a dsn=null in the options, I would run into the Dsn.IsDisabled() case which would return the DisabledHub.Instance as the "new" Hub which would be later also be needed for the dispose.

Any time you init, you need to supply a DSN. If you have set it in the SENTRY_DSN environment variable, or have used the DsnAttribute on your assembly, then it will be found again. But if you've only got it in a config file such as appSettings.json, then it would be found by UseSentry (which looks at config files), but not by SentrySdk.Init because it's designed to support apps without configuration providers (ie. console apps). If you've used none of those, then you must supply it in code (like the sample above). If you supply none of those, then the DSN will be null, and the hub will be the DisabledHub.

Is the DisabledHub.Instance a final static value or would it change after every Init() to the CurrentHub instance? If it would always change to the CurrentHub after a successful Init, then disabling sentry temporary would work via the dsn=null too maybe if the dispose works correctly.

DisabledHub is used internally when the SDK is disabled. All operations on it are no-op. So it is effectively the same as null. (It's basically the null-object pattern.).

In other words, if you don't supply a DSN (even on re-init), then the Sentry SDK is disabled and no errors or transactions will be captured from there forward.

[mattjohnsonpint]

I should also mention that each real Hub holds an instance of SentryClient, which holds an instance of BackgroundWorker - which has an active long-running WorkerTask that is used to queue and send events. It's a producer/consumer buffer that we use to handle back-pressure, so we can capture events without slowing your app down while we work on sending them to Sentry.

Every time you reinitialize, you're getting a new BackgroundWorker, and a new task is started to process it. This is probably fine if you reinitialize rarely. But if you are doing it often, I can see it becoming a major problem for performance of your app.

Certainly - please don't initialize the SDK in a request like I showed above. Any significant traffic to such an endpoint would be disastrous for your app.

[mattjohnsonpint]

And again, if your main need is to adjust the TracesSampleRate without restarting the app, then consider implementing a TracesSampler function instead. You can have it pull a sample rate from an updatable configuration value of your own design.

Though, I'll also add that Sentry's current advice is to send 100% of transactions and let the server-side automatic retention policies do their thing. See https://docs.sentry.io/product/performance/performance-at-scale/benefits-performance-at-scale/#automatic-retention-of-high-quality-data.

[Patrick-Glatt-Vitra]

I do think we should consider making the configuration adjustable at runtime without reinitialization. The IOptions<T> pattern does allow for that, and many configuration providers are dynamically updatable. We just don't currently listen for changes. It might take some work on our part to get there though. Likely a v4 thing.

This would be great and help us a lot 👍
Thx a lot for your detailed explanations and help.
I understand that using the Init() to update configurations is not the way to go. Its possible but might bring other issues.