Docs updates for Java SDK v8

docs/platforms/android/configuration/options.mdx

@@ -192,6 +192,14 @@ _(New in version 6.0.0)_
 
 </ConfigKey>
 
+<ConfigKey name="force-init">
+
+Set this boolean to `true` to force a call to `SentryAndroid.init` to re-initialize the SDK, even if the SDK has already been initialized with high priority.
+
+_(New in version 8.0.0)_
+
+</ConfigKey>
+
 ## Integration Configuration
 
 For many platform SDKs integrations can be configured alongside it. On some platforms that happen as part of the `init()` call, in some others, different patterns apply.
@@ -258,20 +266,14 @@ Default: set to `android.content.Context.getCacheDir()/sentry`.
 
 </ConfigKey>
 
-<ConfigKey name="shutdown-timeout">
+<ConfigKey name="shutdown-timeout-millis">
 
-Controls how many seconds to wait before shutting down. Sentry SDKs send events from a background queue. This queue is given a certain amount to drain pending events. The default is SDK specific but typically around two seconds. Setting this value too low may cause problems for sending events from command line applications. Setting the value too high will cause the application to block for a long time for users experiencing network connectivity problems.
+Controls how many seconds to wait before shutting down. Sentry SDKs send events from a background queue. This queue is given a certain amount to drain pending events. The default is SDK specific but typically around two seconds. Setting this value too low may cause problems for sending events from the application. Setting the value too high will cause the application to block for a long time for users experiencing network connectivity problems.
 
 </ConfigKey>
 
 ## Tracing Options
 
-<ConfigKey name="enable-tracing">
-
-A boolean value, if true, transactions and trace data will be generated and captured. This will set the <PlatformIdentifier name="traces-sample-rate" /> to the recommended default of 1.0 if <PlatformIdentifier name="traces-sample-rate" /> is not defined. Note that <PlatformIdentifier name="traces-sample-rate" /> and <PlatformIdentifier name="traces-sampler" /> take precedence over this option.
-
-</ConfigKey>
-
 <ConfigKey name="traces-sample-rate">
 
 A number between 0 and 1, controlling the percentage chance a given transaction will be sent to Sentry. (0 represents 0% while 1 represents 100%.) Applies equally to all transactions created in the app. Either this or <PlatformIdentifier name="traces-sampler" /> must be defined to enable tracing.

docs/platforms/android/configuration/shared-environments.mdx

@@ -16,11 +16,12 @@ When setting up Sentry inside a library, the consuming app could use the Sentry
 
 </Note>
 
-In order to not conflict with other Sentry instances, you should use the `Hub` API to create a new instance of Sentry.
-The Hub API works the same way as the global Sentry instance, but it is not global and can be used within your component. If you want to capture uncaught exceptions, you can use the `UncaughtExceptionHandlerIntegration` to capture them. As this will capture all uncaught exceptions within an app, you should use the `BeforeSendCallback` to only accept events that are relevant for your SDK.
+In order to not conflict with other Sentry instances, you should use the `Scopes` API to create a new instance of Sentry.
+The Scopes API works the same way as the global Sentry instance, but it is not global and can be used within your component. If you want to capture uncaught exceptions, you can use the `UncaughtExceptionHandlerIntegration` to capture them. As this will capture all uncaught exceptions within an app, you should use the `BeforeSendCallback` to only accept events that are relevant for your SDK.
 
 ```kotlin
-import io.sentry.Hub
+import io.sentry.Scope
+import io.sentry.Scopes
 import io.sentry.SentryOptions
 import io.sentry.SentryOptions.BeforeSendCallback
 import io.sentry.UncaughtExceptionHandlerIntegration
@@ -40,21 +41,27 @@ val options = SentryOptions().apply {
 
 }
 
-val hub = Hub(options)
+val globalScope = Scope(options);
+val isolationScope = Scope(options);
+val scope = Scope(options);
+
+globalScope.bindClient(new SentryClient(options));
+
+Scopes scopes = Scopes(scope, isolationScope, globalScope, "MySentry.init");
 
 val integration = UncaughtExceptionHandlerIntegration()
 options.addIntegration(integration)
-integration.register(hub, options)
+integration.register(scopes, options)
 ```
 
-Once the Hub is configured, you can use it to capture events:
+Once the `Scopes` are configured, you can use them to capture events:
 
 ```kotlin
-hub.captureException(IllegalStateException("Example Exception"))
+scopes.captureException(IllegalStateException("Example Exception"))
 ```
 
-If your SDK can be opened and closed multiple times, you should also close the Hub when you are done with it:
+If your SDK can be opened and closed multiple times, you should also close the `Scopes` when you are done:
 
 ```kotlin
-hub.close()
+scopes.close()
 ```

docs/platforms/android/enriching-events/scopes/index.mdx

@@ -1,46 +1,79 @@
 ---
-title: Scopes and Hubs
+title: Scopes
 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."
 ---
 
 When an event is captured and sent to Sentry, SDKs will merge that event data with extra
 information from the current scope. SDKs will typically automatically manage the scopes
 for you in the framework integrations and you don't need to think about them. However,
-you should know what a scope is and how you can use it for your advantage.
+you should know what a scope is and how you can use it to your advantage.
 
-## What's a Scope, What's a Hub
+## What's a Scope?
 
-You can think of the hub as the central point that our SDKs use to route an
-event to Sentry. When you call `init()` a hub is created and a client and a
-blank scope are created on it. That hub is then associated with the current
-thread and will internally hold a stack of scopes.
-
-The scope will hold useful information that should be sent along with the
-event. For instance [contexts](../context/) or
+Scopes hold useful information that gets sent along with the
+event. For instance, [contexts](../context/) and
 [breadcrumbs](../breadcrumbs/) are stored on
-the scope. When a scope is pushed, it inherits all data from the parent scope
-and when it pops all modifications are reverted.
+the scope. When a scope is forked, it inherits all data from its parent scope.
+
+## How Scopes Work
+
+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.
+
+When you call a global function such as `Sentry.captureException`, Sentry automatically discovers the active scopes and applies them when capturing the event.
+
+## Different Kinds of Scopes
+
+The Sentry SDK has three different kinds of scopes:
+
+- [Global scope](#global-scope)
+- [Isolation scope](#isolation-scope)
+- [Current scope](#current-scope)
+
+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`.
+
+### Global Scope
+
+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.
+
+### Isolation Scope
+
+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.
+
+### Current Scope
+
+The current scope is the local scope that is currently active. You can modify the current scope via `Sentry.configureScope(scope -> { ... })`.
+
+## How Scope Data is Applied to Events
+
+Global scope, isolation scope, and current scope are combined before an event (like an error or transaction) gets sent to Sentry.
+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.
+
+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 default SDK integrations will push and pop scopes intelligently. For
-instance web framework integrations will create and destroy scopes around your
-routes or controllers.
+```java
+Sentry.configureScope(ScopeType.GLOBAL, scope -> {
+  scope.setExtra("shared", "global");
+  scope.setExtra("global", "data");
+});
 
-## How the Scope and Hub Work
+Sentry.configureScope(ScopeType.ISOLATION, scope -> {
+  scope.setExtra("shared", "isolation");
+  scope.setExtra("isolation", "data");
+});
 
-As you start using an SDK, a scope and hub are automatically created for you out
-of the box. It's unlikely that you'll interact with the hub directly unless you're
-writing an integration or you want to create or destroy scopes. Scopes, on the
-other hand are more user facing. You can call <PlatformIdentifier name="configure-scope" /> at any point in
-time to modify data stored on the scope. This is useful for doing things like
-[modifying the context](../context/).
+Sentry.configureScope(ScopeType.CURRENT, scope -> {
+  scope.setExtra("shared", "current");
+  scope.setExtra("current", "data");
+});
 
-When you call a global function such as <PlatformIdentifier name="capture-event" /> internally Sentry
-discovers the current hub and asks it to capture an event. Internally the hub will
-then merge the event with the topmost scope's data.
+Sentry.captureException(new Exception("my error"));
+// --> Will have the following extra:
+// { shared: 'current', global: 'data', isolation: 'data', current: 'data' }
+```
 
 ## Configuring the Scope
 
-The most useful operation when working with scopes is the <PlatformIdentifier name="configure-scope" /> function. It can be used to reconfigure the current scope.
+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).
 
 You can, for instance, add custom tags or inform Sentry about the currently authenticated user.
 
@@ -53,7 +86,7 @@ You can also apply this configuration when unsetting a user at logout:
 <PlatformContent includePath="enriching-events/scopes/scope-synchronization" />
 
 To learn what useful information can be associated with scopes see
-[the context documentation](../context/).
+[context](../context/), [tags](../tags), [users](../identify-user) and [breadcrumbs](../breadcrumbs/).
 
 ## Local Scopes
 

docs/platforms/java/common/configuration/index.mdx

@@ -265,18 +265,18 @@ sentry.traces-sample-rate=0.2
 
 ### Tracing Origins
 
-To set tracing origins, use the `tracing-origins` option:
+To set tracing origins, use the `trace-propagation-targets` option:
 
 ```properties {tabTitle:sentry.properties}
-tracing-origins=localhost,^(http|https)://api\\..*$
+trace-propagation-targets=localhost,^(http|https)://api\\..*$
 ```
 
 ```properties {tabTitle:environment variable}
-SENTRY_TRACING_ORIGINS=localhost,^(http|https)://api\\..*$
+SENTRY_TRACE_PROPAGATION_TARGETS=localhost,^(http|https)://api\\..*$
 ```
 
 ```properties {tabTitle:system property}
-sentry.tracing-origins=localhost,^(http|https)://api\\..*$
+sentry.trace-propagation-targets=localhost,^(http|https)://api\\..*$
 ```
 
 ### Debug

docs/platforms/java/common/configuration/options.mdx

@@ -162,6 +162,14 @@ _(New in version 6.0.0)_
 
 </ConfigKey>
 
+<ConfigKey name="force-init">
+
+Set this boolean to `true` to force a call to `Sentry.init` to re-initialize the SDK, even if the SDK has already been initialized by a high priority integration.
+
+_(New in version 8.0.0)_
+
+</ConfigKey>
+
 <ConfigKey name="enable-backpressure-handling">
 
 Set this boolean to `false` to disable automatic downsampling of transactions while the system is under load. The `tracesSampleRate` is halved for every failing health check up to 10 times, (roughly 0.001% of the original `tracesSampleRate`). Any positive health check will reset `tracesSampleRate` to its original value. Health checks run in the background every 10 seconds, checking for queue drops and rate limiting. Note: Starting with version 7.8.0 backpressure handling has changed from opt-in to opt-out.
@@ -221,20 +229,14 @@ When set, a proxy can be configured that should be used for outbound requests. T
 
 </ConfigKey>
 
-<ConfigKey name="shutdown-timeout">
+<ConfigKey name="shutdown-timeout-millis">
 
 Controls how many seconds to wait before shutting down. Sentry SDKs send events from a background queue. This queue is given a certain amount to drain pending events. The default is SDK specific but typically around two seconds. Setting this value too low may cause problems for sending events from command line applications. Setting the value too high will cause the application to block for a long time for users experiencing network connectivity problems.
 
 </ConfigKey>
 
 ## Tracing Options
 
-<ConfigKey name="enable-tracing">
-
-A boolean value, if true, transactions and trace data will be generated and captured. This will set the `traces-sample-rate` to the recommended default of 1.0 if `traces-sample-rate` is not defined. Note that `traces-sample-rate` and `traces-sampler` take precedence over this option.
-
-</ConfigKey>
-
 <ConfigKey name="traces-sample-rate">
 
 A number between 0 and 1, controlling the percentage chance a given transaction will be sent to Sentry. (0 represents 0% while 1 represents 100%.) Applies equally to all transactions created in the app. Either this or <PlatformIdentifier name="traces-sampler" /> must be defined to enable tracing.
@@ -247,12 +249,6 @@ A function responsible for determining the percentage chance a given transaction
 
 </ConfigKey>
 
-<ConfigKey name="tracing-origins">
-
-An optional property that configures which downstream services receive the `sentry-trace` header attached to HTTP requests. It contains a list of URLs or regex against which URLs are matched. If not set, the `sentry-trace` header is attached to every request executed from an instrumented client.
-
-</ConfigKey>
-
 <ConfigKey name="trace-propagation-targets">
 
 An optional property that controls which downstream services receive tracing data, in the form of a `sentry-trace` and a `baggage` header attached to any outgoing HTTP requests.