Issues/questions migrating from Raven with ASP.NET MVC

[winzig]

For the most basic scenario ("I just want to log .NET exceptions to Sentry"), the documentation is adequate, and the .UseSentry() method is easy to use. But I'm trying to migrate from my original use of the Raven .NET SDK, and I keep running into things I can't find documented.

So in the context of ASP.NET Core MVC, I ask these questions:

How do we modify the scope for the current HttpRequest?

Previously in my custom Sentry logging, I would create a SentryEvent, including modifying the fingerprint, setting the tags, etc. It seems like this is done on Scopes now, but I cannot figure out how to access the per-request Scope. All the sample code I'm seeing just calls into SentrySdk directly.

This doc talks about the exact issue I'm facing — what's the best way to access the current Scope for the current request in ASP.NET MVC — except it doesn't actually explain how to do it. It just links to some sample code, but I am not seeing this in the code.

What's the preferred way of modifying User data before the event is sent to Sentry?

This page only talks about Scopes, but I have yet to find documentation which explains how to access the per-request scope that I presume Sentry has available somewhere.

I see IUserFactory, which seems similar to what we use in the old SDK, SentryUserFactory. But it's unclear where to register that factory in the new SDK, assuming that's even the preferred way to modify User properties before logging an event.

What are ISentryEventExceptionProcessor and ISentryEventProcessor?

In the MVC sample code, I see references to adding implementations of these as singletons and transients, but can't find where these classes are documented:

// Register as many ISentryEventExceptionProcessor as you need. They ALL get called.
services.AddSingleton<ISentryEventExceptionProcessor, SpecialExceptionProcessor>();

// You can also register as many ISentryEventProcessor as you need.
services.AddTransient<ISentryEventProcessor, ExampleEventProcessor>();

How do I do handle exceptions that may be encountered while logging to Sentry?

Previously there was an ErrorOnCapture on RavenClient, but not seeing anything like that in SentryClient.

Is SentryClient thread-safe?

With RavenClient we would keep a static singleton around in scenarios where we wanted to log an exception outside of a typical HttpContext/request. Is this the best way to handle these scenarios with the new SDK?

[bruno-garcia]

Thanks for raising. Apologies if this is confusing but I hope I'll be able to clarify all your points:

How do we modify the scope for the current HttpRequest?

On each new request a new scope is pushed in by the SDK. Just like ASP.NET Core pushes one within the container. When you register something PerScope, it'll be used for that request only. Same with the logger, a _logger.BeginScope is invoked by ASP.NET Core for each request so that the trail of logs (which Sentry SDK captures as breadcrumbs) are scoped per request and when an event is sent to Sentry you see only log entries relevant to that request.

You can modify the current scope (say in a Controller, the current request) with SentrySdk.ConfigureScope. This static class access the current scope. It works the same way that in ASP.NET classic HttpContext.Current static property would give your that scoped request. Internally it uses CallContext/AsyncLocal.

If you don't want to couple your code with static classes, in ASP.NET Core we register a IHub in the container so you can just get a IHub via constructor and call _hub.ConfigureScope. This way you can unit test things more easily. IHub extends ISentryClient and adds the Scope management related stuff:

sentry-dotnet/src/Sentry/IHub.cs

Lines 15 to 17 in 967c0e0

	public interface IHub :
	ISentryClient,
	ISentryScopeManager

Also, you don't have to set things to the Scope. You can do it, so that you set it once and all events sent within that scope include that value. It's for convenience. The values from the Scope are copied over to the event on each event sent out but all of those properties still exist in the event. You can always set directly to it. You can always do:

SentrySdk.CaptureEvent(new SentryEvent
{
    // Everything sent to sentry is here
});

Or with a new client, without any scope involved:

var client = new SentryClient(new SentryOptions
{
    // Configure Client
});
client.CaptureEvent(new SentryEvent
{
    // Access everything that gets sent to Sentry
});
client.Dispose(); // Blocks the thread until event is flushed out, closes the HttpClient

Scope is a concept that lives in the Hub. In the example above there's no Hub at all so you can't keep data around to be copied over to events. There's no ConfigureScope in SentryClient. The client simply takes an event, runs EventProcessors and BeforeSend, serializes the event and sends to Sentry.

What's the preferred way of modifying User data before the event is sent to Sentry?

Sentry integration for ASP.NET Core uses the framework's dependency injection (DI). You don't need to register anything. When the docs mention all you need to do is UseSentry it means we take care of registering the default implementations such as DefaultUserFactory. Internally we register IUserFactory pointing to DefaultUserFactory:

sentry-dotnet/src/Sentry.AspNetCore/Extensions/DependencyInjection/ServiceCollectionExtensions.cs

Line 24 in 582d088

services.TryAddSingleton<IUserFactory, DefaultUserFactory>();

If your register your factory, the SDK will not register the default one, that's how TryAdd works.
In case you want to use your own, all you need to do is register with the lifetime you need, for example a transient one:

services.AddTransient<IUserFactory, MyUserFactory>();

If you register your factory, before sending an event the SDK will call your Create to get the user. You don't need to worry about Scopes in this case. It's just DI.

What are ISentryEventExceptionProcessor and ISentryEventProcessor?

These are hooks to the event processing pipeline. You can create a class that implement one of those interfaces and register with the DI container and the SDK will resole them from the container and invoke the Process for each event it sends out.

In the MVC sample code, I see references to adding implementations of these as singletons and transients, but can't find where these classes are documented:

Those classes are in the Sample project. They are there just to show you can create your own and register with the container. The lifetime is up to you. In case you have an event processor that is not thread-safe, you should register it as Transient. The SDK will always ask the container for each event it processes so there'll be no race-condition. I suggest putting a breakpoint in one of these sample processors and stepping through the code. It's the same idea of BeforeSend but instead of being a Func<SentryEvent, SentryEvent> like BeforeSend, it's based on an abstraction which is easier to unit test and play with DI. You can create as many IEventProcessors as you want and register them all into DI. We'll run all of them before sending the event out to Sentry.

services.AddTransient<ISentryEventProcessor, MarkVipCustomerEventProcessor>();
services.AddTransient<ISentryEventProcessor, DropTestUserEventProcessor>();

Where those classes would be something that takes their own dependencies via constructor injection and could do whatever your application requirements dictate.

Basically it's a way to run your code against events before sending them. As the docs mention you can also drop events if you choose to return null instead of an event:

sentry-dotnet/src/Sentry/Extensibility/ISentryEventProcessor.cs

Lines 13 to 17 in 967c0e0

	/// <remarks>
	/// The event returned can be the same instance received or a new one.
	/// Returning null will stop the processing pipeline.
	/// Meaning the event should no longer be processed nor send.
	/// </remarks>

How do I do handle exceptions that may be encountered while logging to Sentry?

The new Unified API doesn't expose such hook. We've chosen to do that as there's no guarantee that events are sent to Sentry. If you choose to enable debugging sentryOptions.Debug = true you'd get logged that errors have occurred but we don't expose a callback at this time.

Is SentryClient thread-safe?

Yes. You can call SentrySdk.CaptureEvent or share an instance of SentryClient across multiple threads of execution.

I hope this clarifies things a bit. Let us know what continues blurry.

[bruno-garcia]

I think it's worth noting that when moving from ASP.NET classic to ASP.NET Core I suggest no longer relying to a Singleton instance of SentryClient around or static classes.

If you need to send an event (without messing with the scope) simply take ISentryClient in the constructor of your class (like a Controller). If you need scope, take IHub.

[winzig]

Thanks @bruno-garcia. I'm working through your response now to try and apply it to my code. Eventually we are going to move to a DI-centric approach for logging, but currently our logging class is a static class that we call into when exceptions are caught both during an HttpRequest, and also outside the scope of the request.

We obtain a sentry client from the HttpContext passed into our logging class, when it's available, otherwise we fall back to our singleton:

var client = (context != null) 
    ? context.RequestServices.GetService<Sentry.ISentryClient>()
    : Constants.SentryClientFallback;

In this scenario, how do you set the Fingerprint and Tags of an event? With the old SDK, we were able to set the Fingerprint property directly on the Event. In the new SDK it's read-only.

I see above where you indicated:

You can modify the current scope (say in a Controller, the current request) with SentrySdk.ConfigureScope. This static class access the current scope.

It's still not clear to me what happens when I call into that method from a static class. Is there some way to obtain/modify the Scope using the HttpContext object? Or if we obtain the client via the context.RequestServices.GetService<Sentry.ISentryClient>() object, are we able to obtain that request's scope, and modify it before it sends an event?

Assuming Tags/Fingerprints should now be defined on the scope instead of the event (this is still confusing to me).

[bruno-garcia]

@winzig You an set fingerprint by using the extension method SetFingerprint.
The extension method is part of BaseScope which is a base class to SentryEvent

Here's an example from the samples:

sentry-dotnet/samples/Sentry.Samples.Console.Customized/Program.cs

Line 160 in 2cae234

evt.SetFingerprint(new [] { "NewClientDebug"});

We obtain a sentry client from the HttpContext passed into our logging class, when it's available, otherwise we fall back to our singleton:

I'm unsure if you'll ever need the fallback though. With UseSentry we register the client and it'll always be there for you. Or you mean you are calling into the static class without providing an HttpContext?

It's still not clear to me what happens when I call into that method from a static class. Is there some way to obtain/modify the Scope using the HttpContext object? Or if we obtain the client via the context.RequestServices.GetService<Sentry.ISentryClient>() object, are we able to obtain that request's scope, and modify it before it sends an event?

If you obtain the client via context.RequestServices.GetService<Sentry.ISentryClient>() that means that a request exists and the SDK already pushed a new scope for you. So you can modify it via the IHub. Instead of retreving ISentryClient from the container, get IHub (it's a super set, it's the client with access to the scope as I mentioned on the previous reply):

var hub = context.RequestServices.GetService<Sentry.IHub>() 
hub.ConfigureScope(s => ...); // whatever u set here will be included to ALL events sent during this request. Even after leaving this method.
hub.CaptureException(exception); // Sends one event for this one exception, including the Scope data u set above.

But if you are about to send an event directly, without messing with the scope, you can just set the fingerprint to the Event:

var client = context.RequestServices.GetService<Sentry.ISentryClient>();
var evt = new SentryEvent(exception);
evt.SetFingerprint(new [] { "..." });
client.CaptureEvent(evt);

^ No scope involved. The data you set to the event is sent to Sentry and doesn't stay around in memory in case more events are sent out (which is what scope does).

Assuming Tags/Fingerprints should now be defined on the scope instead of the event (this is still confusing to me).

They can if you want to set it once, and any event sent later on in that same request will include them.

If you set in the beginning of the request a tag hub.ConfigureScope(s => s.SetTag()) and later a _logger.LogError() call happens, that tag is sent with the event created by the logger.

I suggest opening the samples we have in the repo and debugging through, it should make it more clear. Let us know!

[winzig]

Or you mean you are calling into the static class without providing an HttpContext?

Yes, alongside our dotnet core web project, we have built out a class library with a lot of our business logic, and so in certain scenarios, we don't have an HttpContext available.

In addition, we are currently planning to handle the exceptions with a middleware exception handler, rather than UseSentry(), so that our code that records exceptions into our local database can be shared between our class library code that has no HttpContext.

(Updated to remove references to a problem I just resolved.)

[winzig]

Turns out a large part of my confusion related to tags, fingerprints, etc. was due to not having a using Sentry statement in my class, which I had initially left out because I thought it was causing namespace collisions. I've worked through those issues, and now SetFingerprint and SetTags is accessible and working as expected.

Next issue is with the Extra param. I see the SetExtra and SetExtras methods now, but they take key/value pairs, whereas the Raven SDK accepted Extra as an object. I assume I can call evt.SetExtra("extra", myExtraObject); and I will get similar behavior to what the Raven SDK offered?

[winzig]

@bruno-garcia Is there sample code somewhere showing the recommended way to register IHub and IUserFactory, without using UseSentry() setup code? I see the one sample in the context of ILogger and logging, but I'm interested in adding this support as singletons in my ASP.NET Core startup code, as I used to do with IRavenClient.

[bruno-garcia]

@winzig there isn't a recommended way without UseSentry. Could you please describe your use-case where you need it without UseSentry?
Last request we had was due to misunderstanding of what UseSentry does and the ASP.NET Core DI so we haven't put any effort into a story for a Startup.cs based ConfigureServices/Configure since this is what UseSentry does under the hood.

[winzig]

@bruno-garcia Because we send exceptions from a centralized class library that doesn’t always have an HttpContext.

[kanadaj]

@winzig the recommended way for class libraries is to pass an ISentryClient to the constructor of the current class. Alternatively you can pass an ILogger object, since Sentry adds a listener to the default Microsoft.Extensions.Logging provider.

The last method is to use the static SentrySdk class. It uses AsyncLocal to retrieve the scope of the current request (if you called UseSentry during startup) so your library class doesn't need to be aware of the request itself.