Sentry-dart: Add scope callback to capture methods

[bruno-garcia]

Currently there's no way to modify a scope for a single event without global side effect.

The latest approach on allowing a scope to be mutated is by taking a scope callback as a second argument to the capture methods. Lets add this to the SDK spec and implement in Dart.

~The Unified API includes a couple of ways to do that: pushScope/popPop and withScope.~

~Works like~

Sentry.withScope(scope => {
    scope.setTag(..);
    Sentry.captureException(..)

~Turns out this isn't on develop.sentry.dev so we need to add there, or figure out why it's not there anymore~

[marandaneto]

it was a conscious decision not to do it, what's the use case? it was not done because it'd require push scope and pop scope and it's not really useful for global scope mode.
ideally, we'd likely do as iOS which is an optional withScope block -> https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentrySDK.m#L176-L187
but we wanted this feature to get mature.

[marandaneto]

a workaround could be Sentry.captureEvent(SentryEvent(exception, tags)), and this event has your tags or whatever you like.

[bruno-garcia]

it was a conscious decision not to do it, what's the use case?

The use case is adding a tag to an event I'm capturing without having that tag show up in any other event that comes after that.

it was not done because it'd require push scope and pop scope and it's not really useful for global scope mode.

Agree push and pop doesn't make sense with global scopes, bu we can have single scope and still allow a scope to be mutated through a clone. On withScope, the method will take a clone of the current (global) scope and pass that as an argument to the callback. That would then be isolated from the global scope as it's a clone.

ideally, we'd likely do as iOS which is an optional withScope block -> https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentrySDK.m#L176-L187
but we wanted this feature to get mature.

Yeah I agree that's a better approach than withScope. It came after the original API design was just passing a callback as a second argument, such as:

Sentry.captureException(e, s => { s.setTag("my-tag","on a cloned, isolated scope" });

this arguably reads best because the withScope thing, since the scope object in the callback isn't explicitly passed to capture, looks like magic.

I'll update the issue title

[ueman]

Is this method supposed to be only available on the static Sentry class?

[marandaneto]

iOS already does it, https://docs.sentry.io/platforms/apple/enriching-events/scopes/#scope-callback

it'd be an optional param (ScopeCallback) to the capture methods.

Hub would take an optional Scopeand use it if passed, otherwise it uses the scope from the _peek