Allow SDK users to control `Mechanism.Handled` for captured exceptions

[bitsandfoxes]

Tip

tldr; see #3383 (comment)

The MainExceptionProcessor handles setting the mechanism here:

sentry-dotnet/src/Sentry/Internal/MainExceptionProcessor.cs

Lines 177 to 188 in c30052e

	else if (exception.StackTrace != null)
	{
	// The exception was thrown, but it was caught by the user, not an integration.
	// Thus, we can mark it as handled.
	mechanism.Handled = true;
	}
	else
	{
	// The exception was never thrown. It was just constructed and then captured.
	// Thus, it is neither handled nor unhandled.
	mechanism.Handled = null;
	}

So this code ends up with Handled = true

try
{
    throw new Exception();
}
catch (Exception ex)
{
    // will be marked as handled 
    SentrySdk.CaptureException(ex);
}

And this code ends up with Handled -- in the issue's Highlights

// will not be marked as anything
SentrySdk.CaptureException(new Exception());

Interestingly, captured messages are Handled -- too.

Which, personally, I find confusing. If an exception is not unhandled, should we not consider it handled implicitly? I'm not talking technical correctness here but user expectations.

But I can still filter issues based on error.handled:false so maybe it doesn't matter?

[bitsandfoxes]

We should consider other scenarios where the stacktrace ends up being null. Just to make sure we're not falsely flagging handled exceptions as --.

[ericsampson]

it feels to me like the only entity who knows for sure if an exception sent to CaptureException is actually "handled" or not is the caller. So should this be controlled by an optional input parameter of that method?
(I don't know how that aligns with the cross-language use of this type of Sentry method)

[jamescrosswell]

it feels to me like the only entity who knows for sure if an exception sent to CaptureException is actually "handled" or not is the caller. So should this be controlled by an optional input parameter of that method?

It's possible for the caller to set handled to true/false by setting the "mechanism" for the exception before capturing it... which is how the Sentry middleware sets this in the ASP.NET Core integration:

sentry-dotnet/src/Sentry.AspNetCore/SentryMiddleware.cs

Line 219 in d1e5efc

e.SetSentryMechanism(mechanism, description, handled: false);

It looks like the main exception processor would overwrite any value that was set explicitly via the mechanism though... which probably isn't a good idea. If someone has set this mechanism explicitly, we shouldn't be overwriting it right?

[bitsandfoxes]

If someone has set this mechanism explicitly, we shouldn't be overwriting it right?

Yeah, definitely not!

[ericsampson]

It's possible for the caller to set handled to true/false by setting the "mechanism" for the exception before capturing it via exception.SetSentryMechanism(mechanism, description, handled: false);

Is that even documented in the SDK docs site?

Either way, it just seems like it would be a lot user-friendlier and more discoverable to offer a new overload:
CaptureException(Exception exception, ..., bool handled = false)