You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/platforms/android/enriching-events/scopes/index.mdx
+60-27Lines changed: 60 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,46 +1,79 @@
1
1
---
2
-
title: Scopes and Hubs
2
+
title: Scopes
3
3
description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage."
4
4
---
5
5
6
6
When an event is captured and sent to Sentry, SDKs will merge that event data with extra
7
7
information from the current scope. SDKs will typically automatically manage the scopes
8
8
for you in the framework integrations and you don't need to think about them. However,
9
-
you should know what a scope is and how you can use it for your advantage.
9
+
you should know what a scope is and how you can use it to your advantage.
10
10
11
-
## What's a Scope, What's a Hub
11
+
## What's a Scope?
12
12
13
-
You can think of the hub as the central point that our SDKs use to route an
14
-
event to Sentry. When you call `init()` a hub is created and a client and a
15
-
blank scope are created on it. That hub is then associated with the current
16
-
thread and will internally hold a stack of scopes.
17
-
18
-
The scope will hold useful information that should be sent along with the
19
-
event. For instance [contexts](../context/) or
13
+
Scopes hold useful information that gets sent along with the
14
+
event. For instance, [contexts](../context/) and
20
15
[breadcrumbs](../breadcrumbs/) are stored on
21
-
the scope. When a scope is pushed, it inherits all data from the parent scope
22
-
and when it pops all modifications are reverted.
16
+
the scope. When a scope is forked, it inherits all data from its parent scope.
17
+
18
+
## How Scopes Work
19
+
20
+
Scopes are basically stacks of data that are attached to events. When an event is captured, the SDK will merge the data from the active scopes into the event. This allows you to attach data to events that is relevant to the context in which the event was captured.
21
+
22
+
When you call a global function such as `Sentry.captureException`, Sentry automatically discovers the active scopes and applies them when capturing the event.
23
+
24
+
## Different Kinds of Scopes
25
+
26
+
The Sentry SDK has three different kinds of scopes:
27
+
28
+
-[Global scope](#global-scope)
29
+
-[Isolation scope](#isolation-scope)
30
+
-[Current scope](#current-scope)
31
+
32
+
The Android SDK does not fork scopes on its own so you may set data on any of the scopes. The Android SDK writes to [current scope](#current-scope) by default when using top level API like `Sentry.setTag`.
33
+
34
+
### Global Scope
35
+
36
+
The global scope is applied to _all_ events, no matter where they originate. You can use it to store data that should apply to all events, such as environmental information.
37
+
38
+
### Isolation Scope
39
+
40
+
The isolation scope is used to isolate events from each other. For example, each request in a web server might get its own isolation scope, so that events from one request don't interfere with events from another request.
41
+
42
+
### Current Scope
43
+
44
+
The current scope is the local scope that is currently active. You can modify the current scope via `Sentry.configureScope(scope -> { ... })`.
45
+
46
+
## How Scope Data is Applied to Events
47
+
48
+
Global scope, isolation scope, and current scope are combined before an event (like an error or transaction) gets sent to Sentry.
49
+
In most cases, setting something on current scope replaces the same thing that may have been set on isolation or global scope. If it hasn't been set on current scope, the value on isolation scope takes precedence over the one from global scope. If there also isn't any value on isolation scope, the one from global scope is used if present.
50
+
51
+
Note, there are exceptions to this, where values from all scopes are merged. This is the case for breadcrumbs, tags, extras, contexts, attachments, and event processors.
23
52
24
-
The default SDK integrations will push and pop scopes intelligently. For
25
-
instance web framework integrations will create and destroy scopes around your
The most useful operation when working with scopes is the <PlatformIdentifiername="configure-scope" /> function. It can be used to reconfigure the current scope.
76
+
There are two main ways to interact with the scope. You can modify the current scope via `Sentry.configureScope(scope -> { ... })` and use setters on the resulting scope, or you can use global methods like `Sentry.setTag()` directly, which will set on the respective scope under the hood (which will be the isolation scope).
44
77
45
78
You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
46
79
@@ -53,7 +86,7 @@ You can also apply this configuration when unsetting a user at logout:
Copy file name to clipboardExpand all lines: docs/platforms/java/common/enriching-events/scopes/index.mdx
+99-33Lines changed: 99 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,46 +1,109 @@
1
1
---
2
-
title: Scopes and Hubs
2
+
title: Scopes
3
3
description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage."
4
4
---
5
5
6
6
When an event is captured and sent to Sentry, SDKs will merge that event data with extra
7
7
information from the current scope. SDKs will typically automatically manage the scopes
8
8
for you in the framework integrations and you don't need to think about them. However,
9
-
you should know what a scope is and how you can use it for your advantage.
9
+
you should know what a scope is and how you can use it to your advantage.
10
10
11
-
## What's a Scope, What's a Hub
11
+
## What's a Scope?
12
12
13
-
You can think of the hub as the central point that our SDKs use to route an
14
-
event to Sentry. When you call `init()` a hub is created and a client and a
15
-
blank scope are created on it. That hub is then associated with the current
16
-
thread and will internally hold a stack of scopes.
17
-
18
-
The scope will hold useful information that should be sent along with the
19
-
event. For instance [contexts](../context/) or
13
+
Scopes hold useful information that gets sent along with the
14
+
event. For instance, [contexts](../context/) and
20
15
[breadcrumbs](../breadcrumbs/) are stored on
21
-
the scope. When a scope is pushed, it inherits all data from the parent scope
22
-
and when it pops all modifications are reverted.
16
+
the scope. When a scope is forked, it inherits all data from its parent scope.
17
+
18
+
The default SDK integrations will fork scopes intelligently. For
19
+
instance, web framework integrations will fork scopes around your
20
+
routes or request handlers.
21
+
22
+
## How Scopes Work
23
+
24
+
Scopes are basically a stacks of data that are attached to events. When an event is captured, the SDK will merge the data from the active scopes into the event. This allows you to attach data to events that is relevant to the context in which the event was captured.
25
+
26
+
A scope is generally valid inside of a callback or an execution context. This means that multiple parts of your application may have different scopes active at the same time. For instance, a web server might handle multiple requests at the same time, and each request may have different scope data to apply to its events.
27
+
28
+
When you call a global function such as `Sentry.captureException`, Sentry automatically discovers the active scopes and applies them when capturing the event.
29
+
30
+
## Different Kinds of Scopes
31
+
32
+
The Sentry SDK has three different kinds of scopes:
33
+
34
+
-[Global scope](#global-scope)
35
+
-[Isolation scope](#isolation-scope)
36
+
-[Current scope](#current-scope)
23
37
24
-
The default SDK integrations will push and pop scopes intelligently. For
25
-
instance web framework integrations will create and destroy scopes around your
26
-
routes or controllers.
38
+
### Global Scope
27
39
28
-
## How the Scope and Hub Work
40
+
The global scope is applied to _all_ events, no matter where they originate. You can use it to store data that should apply to all events, such as environmental information.
29
41
30
-
As you start using an SDK, a scope and hub are automatically created for you out
31
-
of the box. It's unlikely that you'll interact with the hub directly unless you're
32
-
writing an integration or you want to create or destroy scopes. Scopes, on the
33
-
other hand are more user facing. You can call <PlatformIdentifiername="configure-scope" /> at any point in
34
-
time to modify data stored on the scope. This is useful for doing things like
35
-
[modifying the context](../context/).
42
+
You can access the global scope via `Sentry.getGlobalScope()` or `Sentry.configureScope(ScopeType.GLOBAL, globalScope -> { ... })`.
36
43
37
-
When you call a global function such as <PlatformIdentifiername="capture-event" /> internally Sentry
38
-
discovers the current hub and asks it to capture an event. Internally the hub will
39
-
then merge the event with the topmost scope's data.
44
+
### Isolation Scope
45
+
46
+
The isolation scope is used to isolate events from each other. For example, each request in a web server might get its own isolation scope, so that events from one request don't interfere with events from another request. In most cases, you'll want to put data that should be applied to your events on the isolation scope - which is also why all `Sentry.setXXX` methods, like `Sentry.setTag()`, will write data onto the currently active isolation scope. A classic example for data that belongs on the isolation scope is a user - each request may have a different user, so you want to make sure that the user is set on the isolation scope.
47
+
48
+
You can modify the isolation scope via `Sentry.configureScope(ScopeType.ISOLATION, isolationScope -> { ... })`, but usually you'll just use the `Sentry.setXXX` methods to set data on the currently active isolation scope:
The current scope is the local scope that is currently active. Unlike the rarely-forked isolation scope, the current scope may be forked more frequently and under the hood. It can be used to store data that should only be applied to specific events. In most cases, you should not access this scope directly, but use `Sentry.withScope` to create a new scope that is only active for a specific part of your code:
61
+
62
+
```java
63
+
Sentry.withScope(scope -> {
64
+
// scope is the current scope inside of this callback!
65
+
scope.setTag("my-tag", "my value");
66
+
// this tag will only be applied to events captured inside of this callback
Sentry.captureException(newException("my other error"));
72
+
```
73
+
74
+
You can modify the current scope via `Sentry.configureScope(ScopeType.CURRENT, scope -> { ... })`, but usually you should use `Sentry.withScope()` to interact with local scopes instead.
75
+
76
+
## How Scope Data is Applied to Events
77
+
78
+
Global scope, isolation scope, and current scope are combined before an event (like an error or transaction) gets sent to Sentry.
79
+
In most cases, setting something on current scope replaces the same thing that may have been set on isolation or global scope. If it hasn't been set on current scope, the value on isolation scope takes precedence over the one from global scope. If there also isn't any value on isolation scope, the one from global scope is used if present.
80
+
81
+
Note, there are exceptions to this, where values from all scopes are merged. This is the case for breadcrumbs, tags, extras, contexts, attachments and event processors.
The most useful operation when working with scopes is the <PlatformIdentifiername="configure-scope" /> function. It can be used to reconfigure the current scope.
106
+
There are two main ways to interact with the scope. You can modify the current scope via `Sentry.configureScope(ScopeType.CURRENT, scope -> { ... })` and use setters on the resulting scope, or you can use global methods like `Sentry.setTag()` directly, which will set on the respective scope under the hood (which will be the isolation scope).
44
107
45
108
You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
46
109
@@ -51,13 +114,7 @@ You can also apply this configuration when unsetting a user at logout:
To learn what useful information can be associated with scopes see
54
-
[the context documentation](../context/).
55
-
56
-
## Local Scopes
57
-
58
-
We also support pushing and configuring a scope within a single call. This is typically
59
-
called <PlatformIdentifiername="with-scope" />, <PlatformIdentifiername="push-scope" /> or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if
60
-
you only want to send data for one specific event.
117
+
[context](../context/), [tags](../tags), [users](../identify-user) and [breadcrumbs](../breadcrumbs/).
61
118
62
119
### Using <PlatformIdentifiername="with-scope" />
63
120
@@ -73,6 +130,14 @@ made will stay isolated within the <PlatformIdentifier name="with-scope" /> call
73
130
more easily isolate pieces of context information to specific locations in your code or
74
131
even call <PlatformIdentifiername="clear" /> to briefly remove all context information.
75
132
133
+
## Using `withIsolationScope`
134
+
135
+
`withIsolationScope` works fundamentally the same as `withScope`, but it will fork the isolation scope instead of the current scope. Generally, the isolation scope is meant to be forked less frequently than the current scope, and in most cases the SDK will handle this automatically for you.
136
+
137
+
But in cases where you want to isolate a non-request process (for example, a background job), you can use `withIsolationScope` to create a new isolation scope that is only active for the duration of the callback:
In the following example we use the scope callback parameter that is available for all `capture` methods to attach a `level` and a `tag` to only one specific error:
@@ -91,6 +156,7 @@ caught, and all errors that occur will be silently ignored and **not** reported.
91
156
92
157
</Alert>
93
158
159
+
94
160
## Kotlin Coroutines
95
161
96
162
Sentry's SDK for Java stores the scope and the context in a thread-local variable. To make sure that a coroutine has access to the correct Sentry context, an instance of `SentryContext` must be provided when launching a coroutine.
0 commit comments