Make scopes more aligned to Sentry specs to ease support in the downstream SDKs

[limbonaut]

Context

I'm working on implementing current scopes in the Godot SDK, which requires scope lifetime to be fixed to specific functions in GDScript or active span. The scopes are a prerequisite to implementing performance API in Godot.

Take a look at API I'm aiming to implement across all supported platforms (it's GDScript code):

SentrySDK.with_scope(func(scope):
  scope.set_tag(...)
  do_some_work()  # can cause errors that should be associated with this scope
  do_more_work()  # can cause more errors (Godot errors are not terminating)
)

It's modeled after three-scope model (global scope + current scope minus isolation scope because underlying SDKs don't support isolation scopes yet). So it's a simplified "two-scope" model: global + current scopes.

The performance API will need this too:

SentrySDK.with_span("game.some_work", func(span):  
  # with_span() forks current scope for the duration of the active span (i.e. this function)
  SentrySDK.get_current_scope().set_tag(...)
  do_some_work()
)

The recent Scope API spec mandates:

When a new span is started, the current scope of the parent span MUST be forked (duplicated), transferring all data from the parent scope to the new scope.

The current scope stack will be managed internally in the Godot SDK.

Proposal(s)

A) Allow for scope lifetime to be owned by users. Currently, capture_event_with_scope takes ownership of "local" scope, making it a one-time construct for our use-case. This multiplies the work needed to maintain current scopes at runtime in the Godot SDK (Godot errors are non-terminal - application continues running).

This could be implemented as a separate constructor: sentry_scope_new (creates user-owned scope) and sentry_scope_free, and it tags scope as "user-owned".

B) Add sentry_scope_clone() so the parent span's current scope cloning could be streamlined in the downstream SDKs. This should perform a deep copy (unless CoW). This operation exists in other SDKs such as cocoa, android, js, etc.

C) Implement sentry_capture_log_with_scope so integrations can associate logs with specific scope-bound active span (considering that the scope model and stack would be owned by Godot SDK) and apply scope attributes.

D) Add sentry_scope_set_span and sentry_scope_set_transaction - so the events can be associated with the current scope's active span/transaction.

So it's three four closely related proposals 🙂 Looking forward to your feedback, can work on implementations too.

EDIT: clarified C
EDIT 2: added D

[linear-code]

NATIVE-197

[limbonaut]

Ah, I also forgot that we dont have sentry_scope_set_span. That would be D.

[jpnurmi]

Thanks for the proposal!

C) Implement sentry_capture_log_with_scope so integrations can associate logs with specific scopes (considering that the scope model and stack would be owned by Godot SDK).

This is just cosmetics, but the _with_scope suffix was inspired by the withScope APIs in other SDKs. I feel like it was a mistake and we should instead have sentry_scope_capture_foo(scope, foo) for all scope-specific capture functions. 🤔