Skip to content

Commit f5946d2

Browse files
adinauerlblodermaxhovcoolguyzonegetsantry[bot]
authored
Restore Java Hub docs as versioned docs for v7 and prior (#12401)
* Update Java SDK v8 deprecation removals (#11820) * Update Java SDK v8 deprecation removals * Update docs/platforms/android/configuration/options.mdx Co-authored-by: Lukas Bloder <[email protected]> --------- Co-authored-by: Lukas Bloder <[email protected]> * Add documentation on how to check-in to an environment with CheckInUtils (#11826) * Remove `enableTracing` option from Java SDK as it has been removed in v8 (#11575) * Update OpenTelemetry docs for Java v8 (#12209) * Update OTel docs for Java v8 * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> --------- Co-authored-by: Alex Krawiec <[email protected]> * Document `forceInit` for Java SDK (#12260) * document forceInit option * Apply suggestions from code review Co-authored-by: Lukas Bloder <[email protected]> --------- Co-authored-by: Lukas Bloder <[email protected]> * Improve `bindToScope` docs for Java (#12263) * Improve bindToScope docs * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> --------- Co-authored-by: Alex Krawiec <[email protected]> * Docs for `sentry-graphql-22` (#12259) * Duplicate docs for graphql-java v22 * link between graphql docs versions * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> --------- Co-authored-by: Alex Krawiec <[email protected]> * Update platform docs for v8 and use OpenTelemetry (#12232) * Update OTel docs for Java v8 * Change platform docs for v8 and use OTel * move includes to index file * CR changes * [getsentry/action-github-commit] Auto commit * close ConfigKey tag * replace link * fix link * Update Android SDK "Using Sentry within an SDK" section for Java SDK v8 (#12325) * Update Using Sentry within an SDK for v8 * Update docs/platforms/android/configuration/shared-environments.mdx Co-authored-by: Lukas Bloder <[email protected]> --------- Co-authored-by: Lukas Bloder <[email protected]> * Add documentation on setting SpanKind and capture HttpHeaders with OTEL (#12328) * wip add docs for capturing http headers as well as manual instrumentation using opentelemetry * Update docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx Co-authored-by: Alexander Dinauer <[email protected]> --------- Co-authored-by: Alexander Dinauer <[email protected]> * Replace `Hub` docs with `Scopes` (#12377) * Replace hub docs with scopes docs * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Lukas Bloder <[email protected]> * Apply suggestions from code review Co-authored-by: Lukas Bloder <[email protected]> * Update docs/platforms/android/enriching-events/scopes/index.mdx * duplicate java into android * Update docs/platforms/android/enriching-events/scopes/index.mdx --------- Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Lukas Bloder <[email protected]> * Restore Hub docs as versioned docs for v7 and prior --------- Co-authored-by: Lukas Bloder <[email protected]> Co-authored-by: Max Hovens <[email protected]> Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
1 parent 0915205 commit f5946d2

File tree

7 files changed

+343
-0
lines changed

7 files changed

+343
-0
lines changed

‎docs/platforms/android/enriching-events/scopes/index__v7.x.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Scopes and Hubs
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+
---
5+
6+
When an event is captured and sent to Sentry, SDKs will merge that event data with extra
7+
information from the current scope. SDKs will typically automatically manage the scopes
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.
10+
11+
## What's a Scope, What's a Hub
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
20+
[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.
23+
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.
27+
28+
## How the Scope and Hub Work
29+
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 <PlatformIdentifier name="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/).
36+
37+
When you call a global function such as <PlatformIdentifier name="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.
40+
41+
## Configuring the Scope
42+
43+
The most useful operation when working with scopes is the <PlatformIdentifier name="configure-scope" /> function. It can be used to reconfigure the current scope.
44+
45+
You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
46+
47+
<PlatformContent includePath="enriching-events/scopes/configure-scope" />
48+
49+
You can also apply this configuration when unsetting a user at logout:
50+
51+
<PlatformContent includePath="enriching-events/unset-user" />
52+
53+
<PlatformContent includePath="enriching-events/scopes/scope-synchronization" />
54+
55+
To learn what useful information can be associated with scopes see
56+
[the context documentation](../context/).
57+
58+
## Local Scopes
59+
60+
We also support pushing and configuring a scope within a single call. This is typically
61+
called <PlatformIdentifier name="with-scope" />, <PlatformIdentifier name="push-scope" /> or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if
62+
you only want to send data for one specific event.
63+
64+
### Using Scope Callback Parameter
65+
66+
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:
67+
68+
<PlatformContent includePath="enriching-events/scopes/scope-callback-param" />
69+
70+
Before the callback is invoked the SDK creates a clone of the current scope, and the changes
71+
made will stay isolated within the callback function. This allows you to
72+
more easily isolate pieces of context information to specific locations in your code or
73+
even call `clear` to briefly remove all context information.
74+
75+
<Alert level="info" title="Important">
76+
77+
Any exceptions that occur within the callback function for configuring a local scope will not be
78+
caught, and all errors that occur will be silently ignored and **not** reported.
79+
80+
</Alert>

‎docs/platforms/java/common/enriching-events/scopes/index__v7.x.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: Scopes and Hubs
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+
---
5+
6+
When an event is captured and sent to Sentry, SDKs will merge that event data with extra
7+
information from the current scope. SDKs will typically automatically manage the scopes
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.
10+
11+
## What's a Scope, What's a Hub
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
20+
[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.
23+
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.
27+
28+
## How the Scope and Hub Work
29+
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 <PlatformIdentifier name="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/).
36+
37+
When you call a global function such as <PlatformIdentifier name="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.
40+
41+
## Configuring the Scope
42+
43+
The most useful operation when working with scopes is the <PlatformIdentifier name="configure-scope" /> function. It can be used to reconfigure the current scope.
44+
45+
You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
46+
47+
<PlatformContent includePath="enriching-events/scopes/configure-scope" />
48+
49+
You can also apply this configuration when unsetting a user at logout:
50+
51+
<PlatformContent includePath="enriching-events/unset-user" />
52+
53+
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 <PlatformIdentifier name="with-scope" />, <PlatformIdentifier name="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.
61+
62+
### Using <PlatformIdentifier name="with-scope" />
63+
64+
In the following example we use <PlatformIdentifier name="with-scope" /> to attach a `level` and a `tag` to only one specific error:
65+
66+
<PlatformContent includePath="enriching-events/scopes/with-scope" />
67+
68+
While this example looks similar to <PlatformIdentifier name="configure-scope" />, it is actually very different.
69+
Calls to <PlatformIdentifier name="configure-scope" /> change the current active scope; all successive calls to <PlatformIdentifier name="configure-scope" /> will maintain previously set changes unless they are explicitly unset.
70+
71+
On the other hand, <PlatformIdentifier name="with-scope" /> creates a clone of the current scope, and the changes
72+
made will stay isolated within the <PlatformIdentifier name="with-scope" /> callback function. This allows you to
73+
more easily isolate pieces of context information to specific locations in your code or
74+
even call <PlatformIdentifier name="clear" /> to briefly remove all context information.
75+
76+
### Using Scope Callback Parameter
77+
78+
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:
79+
80+
<PlatformContent includePath="enriching-events/scopes/scope-callback-param" />
81+
82+
Before the callback is invoked the SDK creates a clone of the current scope, and the changes
83+
made will stay isolated within the callback function. This allows you to
84+
more easily isolate pieces of context information to specific locations in your code or
85+
even call `clear` to briefly remove all context information.
86+
87+
<Alert level="info" title="Important">
88+
89+
Any exceptions that occur within the callback function for configuring a local scope will not be
90+
caught, and all errors that occur will be silently ignored and **not** reported.
91+
92+
</Alert>
93+
94+
## Kotlin Coroutines
95+
96+
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.
97+
98+
### Installation
99+
100+
```xml {tabTitle:Maven}
101+
<dependency>
102+
<groupId>io.sentry</groupId>
103+
<artifactId>sentry-kotlin-extensions</artifactId>
104+
<version>{{@inject packages.version('sentry.java.kotlin-extensions', '5.0.0') }}</version>
105+
</dependency>
106+
```
107+
108+
```groovy {tabTitle:Gradle}
109+
implementation 'io.sentry:sentry-kotlin-extensions:{{@inject packages.version('sentry.java.kotlin-extensions', '5.0.0') }}'
110+
```
111+
112+
```scala {tabTitle: SBT}
113+
libraryDependencies += "io.sentry" % "sentry-kotlin-extensions" % "{{@inject packages.version('sentry.java.kotlin-extensions', '5.0.0') }}"
114+
```
115+
116+
### Usage
117+
118+
```kotlin
119+
import io.sentry.kotlin.SentryContext
120+
import io.sentry.Sentry
121+
122+
launch(SentryContext()) {
123+
// tag set in parent coroutine is visible to child coroutine
124+
Sentry.setTag("parent-tag", "value")
125+
launch() {
126+
// tag set in child coroutine is not visible in parent coroutine
127+
Sentry.setTag("child-tag", "value")
128+
}
129+
}
130+
```

‎platform-includes/enriching-events/scopes/configure-scope/android__v7.x.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
```java {tabTitle: Java}
2+
import io.sentry.Sentry;
3+
import io.sentry.protocol.User;
4+
5+
Sentry.configureScope(scope -> {
6+
scope.setTag("my-tag", "my value");
7+
User user = new User();
8+
user.setId("42");
9+
user.setEmail("[email protected]");
10+
scope.setUser(user);
11+
});
12+
```
13+
14+
```kotlin {tabTitle: Kotlin}
15+
import io.sentry.Sentry
16+
import io.sentry.protocol.User
17+
18+
Sentry.configureScope { scope ->
19+
scope.setTag("my-tag", "my value")
20+
scope.user = User().apply {
21+
id = "42"
22+
email = "[email protected]"
23+
}
24+
}
25+
```

‎platform-includes/enriching-events/scopes/configure-scope/java__v7.x.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
```java {tabTitle: Java}
2+
import io.sentry.Sentry;
3+
import io.sentry.protocol.User;
4+
5+
Sentry.configureScope(scope -> {
6+
scope.setTag("my-tag", "my value");
7+
User user = new User();
8+
user.setId("42");
9+
user.setEmail("[email protected]");
10+
scope.setUser(user);
11+
});
12+
```
13+
14+
```kotlin {tabTitle: Kotlin}
15+
import io.sentry.Sentry
16+
import io.sentry.protocol.User
17+
18+
Sentry.configureScope { scope ->
19+
scope.setTag("my-tag", "my value")
20+
scope.user = User().apply {
21+
id = "42"
22+
email = "[email protected]"
23+
}
24+
}
25+
```

‎platform-includes/enriching-events/scopes/scope-callback-param/java__v7.x.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
```java {tabTitle: Java}
2+
import io.sentry.Sentry;
3+
import io.sentry.SentryLevel;
4+
5+
// will be tagged with my-tag="my value"
6+
Sentry.captureException(new Exception("my error"), scope -> {
7+
scope.setTag("my-tag", "my value");
8+
scope.setLevel(SentryLevel.WARNING);
9+
});
10+
11+
// will not be tagged with my-tag
12+
Sentry.captureException(new Exception("my error"));
13+
```
14+
15+
```kotlin {tabTitle: Kotlin}
16+
import io.sentry.Sentry
17+
import io.sentry.SentryLevel
18+
19+
// will be tagged with my-tag="my value"
20+
Sentry.captureException(Exception("my error")) { scope ->
21+
scope.setTag("my-tag", "my value")
22+
scope.level = SentryLevel.WARNING
23+
}
24+
25+
// will not be tagged with my-tag
26+
Sentry.captureException(Exception("my error"))
27+
```

‎platform-includes/enriching-events/scopes/with-scope/java__v7.x.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<PlatformSection notSupported={["android"]}>
2+
3+
```java {tabTitle: Java}
4+
import io.sentry.Sentry;
5+
import io.sentry.SentryLevel;
6+
7+
Sentry.withScope(scope -> {
8+
scope.setTag("my-tag", "my value");
9+
scope.setLevel(SentryLevel.WARNING);
10+
11+
// will be tagged with my-tag="my value"
12+
Sentry.captureException(new Exception("my error"));
13+
});
14+
15+
// will not be tagged with my-tag
16+
Sentry.captureException(new Exception("my error"));
17+
```
18+
19+
```kotlin {tabTitle: Kotlin}
20+
import io.sentry.Sentry
21+
import io.sentry.SentryLevel
22+
23+
Sentry.withScope { scope ->
24+
scope.setTag("my-tag", "my value")
25+
scope.level = SentryLevel.WARNING
26+
27+
// will be tagged with my-tag="my value"
28+
Sentry.captureException(Exception("my error"))
29+
}
30+
31+
// will not be tagged with my-tag
32+
Sentry.captureException(Exception("my error"))
33+
```
34+
35+
<Alert level="info" title="Important">
36+
37+
In the Java SDK `withScope` does **not** work reliably in `globalHubMode` as the `scope` gets pushed on the stack global to the hub. In `globalHubMode` use the callback parameter of the capture methods detailed below.
38+
39+
</Alert>
40+
41+
</PlatformSection>

‎platform-includes/enriching-events/unset-user/java__v7.x.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
```java {tabTitle: Java}
2+
import io.sentry.Sentry;
3+
4+
Sentry.configureScope(scope -> {
5+
scope.setUser(null);
6+
});
7+
```
8+
9+
```kotlin {tabTitle: Kotlin}
10+
import io.sentry.Sentry
11+
12+
Sentry.configureScope { scope ->
13+
scope.user = null
14+
}
15+
```

0 commit comments

Comments
 (0)