From 21a277fdc7a56a1552a9566bd14e0697ed3f64b4 Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Mon, 25 Nov 2024 16:57:05 +0100 Subject: [PATCH 1/2] docs(sdks): New Scope APIs --- develop-docs/sdk/telemetry/scopes.mdx | 60 +++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 develop-docs/sdk/telemetry/scopes.mdx diff --git a/develop-docs/sdk/telemetry/scopes.mdx b/develop-docs/sdk/telemetry/scopes.mdx new file mode 100644 index 00000000000000..f28194e3a1dbdd --- /dev/null +++ b/develop-docs/sdk/telemetry/scopes.mdx @@ -0,0 +1,60 @@ +--- +title: Scopes +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +The implementation in each SDK consists of three types of scopes: + +- The global scope +- The isolation scope +- The current scope + +Regardles of the scope type, data like tags, breadcrumbs, context, etc. can be added to each scope type by the user. + +### Global Scope + +The global scope acts as a global variable that stays the same for the entire execution of the application. Data applied to this scope will be applied to **all** events emitted by the SDK. +This scope is used for application-wide data like the `release`, the `environment`, etc. + +### Isolation Scope + +The isolation scope holds data which is only applicable to the current request (on a server), tab (in a browser), or user (on mobile). Top-level SDK APIs like `sentry.setTag()`, `sentry.setContext()`, etc. write to the isolation scope. + +The isolation scope is stored in a context variable, thread local, async local, or similar depending on the platform. + +The isolation scope is forked by the SDK's integrations. Users should not need to think about isolation scopes or forking of one. + +### Current Scope + +This scope holds data for the current active span. Whenever a new span is started the current scope of the parent span is forked (read: duplicated), giving the new span all the data from the parent span and making it possible to add or mutate data that is just applied to the new span (see also "Copy-on-write"). + +Changing the original scope after forking does not modify the forked scope. + +The current scope is stored in a context variable, thread local, async local, or similar depending on the platform. + +The current scope can be forked by the end user. Either explicitly, by using `sentry.withScope()` or implicitly, by starting a new span. + +### The Scope APIs + +```js +... +``` + +### Applying the scope data to events + +The data held by all three scope types is merged before it is applied to an event. + +This is performed in the following order: + +1. Data from the global scope is... +2. merged with data from the isolation scope, which is... +3. merged with data from the current scope, which is ... +4. applied to the event + +## Related Documents + +This is a more concise version of the [Hub & Scope Refactoring](/sdk/miscellaneous/hub_and_scope_refactoring/) document. It does focus on the actual implementation and expected features. +The old document remains unchanged, and offers more historical context and migration strategies. From 9aafcab3b7387f2e53abf5b46ec870dc48d4798a Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Tue, 26 Nov 2024 11:44:00 +0100 Subject: [PATCH 2/2] chore(wording): finish scopes document --- develop-docs/sdk/telemetry/scopes.mdx | 42 ++++++++++++--------------- 1 file changed, 18 insertions(+), 24 deletions(-) diff --git a/develop-docs/sdk/telemetry/scopes.mdx b/develop-docs/sdk/telemetry/scopes.mdx index f28194e3a1dbdd..45e0cabc6f5fd4 100644 --- a/develop-docs/sdk/telemetry/scopes.mdx +++ b/develop-docs/sdk/telemetry/scopes.mdx @@ -6,55 +6,49 @@ title: Scopes This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. -The implementation in each SDK consists of three types of scopes: +The implementation in each SDK MUST consist of three types of scopes: - The global scope - The isolation scope - The current scope -Regardles of the scope type, data like tags, breadcrumbs, context, etc. can be added to each scope type by the user. +Users MUST be able to add data such as `tags`, `breadcrumbs`, and `context` to any scope, regardless of its type. + +## Choosing the Right Scope ### Global Scope -The global scope acts as a global variable that stays the same for the entire execution of the application. Data applied to this scope will be applied to **all** events emitted by the SDK. -This scope is used for application-wide data like the `release`, the `environment`, etc. +The global scope functions as a persistent global variable throughout the application's execution. Any data assigned to this scope is automatically applied to **all** events emitted by the SDK. + +It is typically used to store application-wide data, such as the `release`, `environment`, and similar context. ### Isolation Scope -The isolation scope holds data which is only applicable to the current request (on a server), tab (in a browser), or user (on mobile). Top-level SDK APIs like `sentry.setTag()`, `sentry.setContext()`, etc. write to the isolation scope. +The isolation scope MUST contain data specific to the current execution context: a single request (on a server), a single tab (in a browser), or a single user session (on mobile). Top-level SDK APIs, such as `sentry.setTag()` and `sentry.setContext()` MUST write to the isolation scope. -The isolation scope is stored in a context variable, thread local, async local, or similar depending on the platform. +The isolation scope SHOULD be implemented using a context variable, thread-local storage, async-local storage, or an equivalent mechanism appropriate for the platform. -The isolation scope is forked by the SDK's integrations. Users should not need to think about isolation scopes or forking of one. +SDK integrations MUST handle the forking of isolation scopes automatically. Users MUST NOT need to manage or be concerned with the details of scope isolation or its forking process. ### Current Scope -This scope holds data for the current active span. Whenever a new span is started the current scope of the parent span is forked (read: duplicated), giving the new span all the data from the parent span and making it possible to add or mutate data that is just applied to the new span (see also "Copy-on-write"). - -Changing the original scope after forking does not modify the forked scope. - -The current scope is stored in a context variable, thread local, async local, or similar depending on the platform. - -The current scope can be forked by the end user. Either explicitly, by using `sentry.withScope()` or implicitly, by starting a new span. +The current scope MUST maintain data for the active span. When a new span is started, the current scope of the parent span is forked (i.e., duplicated), transferring all data from the parent span to the new span. This allows modifications or additions specific to the new span without affecting the parent span. This behavior aligns with a "copy-on-write" model. -### The Scope APIs +Any changes made to the current scope after forking MUST NOT impact the forked scope. -```js -... -``` +The current scope SHOULD be implemented using a context variable, thread-local storage, async-local storage, or an equivalent mechanism appropriate for the platform. -### Applying the scope data to events +Users MAY fork the current scope explicitly by invoking `sentry.withScope()` or implicitly by starting a new span. -The data held by all three scope types is merged before it is applied to an event. +## Applying Scope Data to Events -This is performed in the following order: +Data from all three scope types MUST be merged in a specific order before being applied to an event. The process is as follows: -1. Data from the global scope is... +1. data from the global scope is... 2. merged with data from the isolation scope, which is... 3. merged with data from the current scope, which is ... 4. applied to the event ## Related Documents -This is a more concise version of the [Hub & Scope Refactoring](/sdk/miscellaneous/hub_and_scope_refactoring/) document. It does focus on the actual implementation and expected features. -The old document remains unchanged, and offers more historical context and migration strategies. +This document provides a concise summary of the [Hub & Scope Refactoring](/sdk/miscellaneous/hub_and_scope_refactoring/), focusing on implementation details and expected features. The original document remains unchanged, offering additional historical context and migration strategies.