From 29f4570e663034517b51c1a92ed37dec7664897d Mon Sep 17 00:00:00 2001 From: Lukas Bloder Date: Fri, 10 Jun 2022 12:01:06 +0200 Subject: [PATCH 1/3] add local scope doc to Android Platform, adapt LocalScope doc for Java to include the new callback. align old code example and leave as alternative --- .../scopes/with-scope/java.mdx | 87 +++++++++++++++++-- .../common/enriching-events/scopes.mdx | 2 +- 2 files changed, 80 insertions(+), 9 deletions(-) diff --git a/src/includes/enriching-events/scopes/with-scope/java.mdx b/src/includes/enriching-events/scopes/with-scope/java.mdx index ec4ee2755e634d..e3190e41193576 100644 --- a/src/includes/enriching-events/scopes/with-scope/java.mdx +++ b/src/includes/enriching-events/scopes/with-scope/java.mdx @@ -1,25 +1,96 @@ + + +```java {tabTitle: Java} +import io.sentry.Sentry; +import io.sentry.SentryLevel; + +// will be tagged with my-tag="my value" +Sentry.captureException(new Exception("my error"), scope -> { + scope.setTag("my-tag", "my value"); + scope.setLevel(SentryLevel.WARNING); +}); + +// will not be tagged with my-tag +Sentry.captureException(new Exception("my error")); +``` + +```kotlin {tabTitle: Kotlin} +import io.sentry.Sentry +import io.sentry.SentryLevel + +// will be tagged with my-tag="my value" +Sentry.captureException(Exception("my error")) { scope -> + scope.setTag("my-tag", "my value") + scope.level = SentryLevel.WARNING +} + +// will not be tagged with my-tag +Sentry.captureException(Exception("my error")) +``` + + + + + +The JavaSDK provides two alternative ways of configuring a local scope. + ```java {tabTitle: Java} import io.sentry.Sentry; import io.sentry.SentryLevel; +// will be tagged with my-tag="my value" +Sentry.captureException(new Exception("my error"), scope -> { + scope.setTag("my-tag", "my value"); + scope.setLevel(SentryLevel.WARNING); +}); + +// will not be tagged with my-tag +Sentry.captureException(new Exception("my error")); +``` + +```java {tabTitle: Java-Alternative} +import io.sentry.Sentry; +import io.sentry.SentryLevel; + Sentry.withScope(scope -> { - scope.setLevel(SentryLevel.FATAL); - scope.setTransaction("main"); + scope.setTag("my-tag", "my value"); + scope.setLevel(SentryLevel.WARNING); - // This message includes the dataset to the scope in this block: - Sentry.captureMessage("Fatal message!"); + // will be tagged with my-tag="my value" + Sentry.captureException(new Exception("my error")); }); + +// will not be tagged with my-tag +Sentry.captureException(new Exception("my error")); ``` ```kotlin {tabTitle: Kotlin} import io.sentry.Sentry import io.sentry.SentryLevel +// will be tagged with my-tag="my value" +Sentry.captureException(Exception("my error")) { scope -> + scope.setTag("my-tag", "my value") + scope.level = SentryLevel.WARNING +} + +// will not be tagged with my-tag +Sentry.captureException(Exception("my error")) +``` + +```kotlin {tabTitle: Kotlin-Alternative} +import io.sentry.Sentry +import io.sentry.SentryLevel + Sentry.withScope { scope -> - scope.level = SentryLevel.FATAL - scope.setTransaction("main") + scope.setTag("my-tag", "my value") + scope.level = SentryLevel.WARNING - // This message includes the dataset to the scope in this block: - Sentry.captureMessage("Fatal message!") + // will be tagged with my-tag="my value" + Sentry.captureException(Exception("my error")) } + +// will not be tagged with my-tag +Sentry.captureException(Exception("my error")) ``` + diff --git a/src/platforms/common/enriching-events/scopes.mdx b/src/platforms/common/enriching-events/scopes.mdx index 2cb93bcaddbcc7..f2914769035353 100644 --- a/src/platforms/common/enriching-events/scopes.mdx +++ b/src/platforms/common/enriching-events/scopes.mdx @@ -93,7 +93,7 @@ You can also apply this configuration when unsetting a user at logout: To learn what useful information can be associated with scopes see [the context documentation](../context/). - + ## Local Scopes From 5f8f0d2dc342944c987b4b962058014269aa74b8 Mon Sep 17 00:00:00 2001 From: Lukas Bloder Date: Thu, 16 Jun 2022 11:33:06 +0200 Subject: [PATCH 2/3] Update local scope documentation. Differentiate between withScope/pushScope and scope callback parameter of capture methods --- .../apple.mdx | 0 .../dart.mdx | 0 .../dotnet.mdx | 0 .../scopes/scope-callback-param/java.mdx | 27 ++++++++ .../unreal.mdx | 0 .../scopes/with-scope/java.mdx | 69 ++----------------- .../common/enriching-events/scopes.mdx | 34 +++++++-- 7 files changed, 64 insertions(+), 66 deletions(-) rename src/includes/enriching-events/scopes/{with-scope => scope-callback-param}/apple.mdx (100%) rename src/includes/enriching-events/scopes/{with-scope => scope-callback-param}/dart.mdx (100%) rename src/includes/enriching-events/scopes/{with-scope => scope-callback-param}/dotnet.mdx (100%) create mode 100644 src/includes/enriching-events/scopes/scope-callback-param/java.mdx rename src/includes/enriching-events/scopes/{with-scope => scope-callback-param}/unreal.mdx (100%) diff --git a/src/includes/enriching-events/scopes/with-scope/apple.mdx b/src/includes/enriching-events/scopes/scope-callback-param/apple.mdx similarity index 100% rename from src/includes/enriching-events/scopes/with-scope/apple.mdx rename to src/includes/enriching-events/scopes/scope-callback-param/apple.mdx diff --git a/src/includes/enriching-events/scopes/with-scope/dart.mdx b/src/includes/enriching-events/scopes/scope-callback-param/dart.mdx similarity index 100% rename from src/includes/enriching-events/scopes/with-scope/dart.mdx rename to src/includes/enriching-events/scopes/scope-callback-param/dart.mdx diff --git a/src/includes/enriching-events/scopes/with-scope/dotnet.mdx b/src/includes/enriching-events/scopes/scope-callback-param/dotnet.mdx similarity index 100% rename from src/includes/enriching-events/scopes/with-scope/dotnet.mdx rename to src/includes/enriching-events/scopes/scope-callback-param/dotnet.mdx diff --git a/src/includes/enriching-events/scopes/scope-callback-param/java.mdx b/src/includes/enriching-events/scopes/scope-callback-param/java.mdx new file mode 100644 index 00000000000000..e7dbe6e8eafd4b --- /dev/null +++ b/src/includes/enriching-events/scopes/scope-callback-param/java.mdx @@ -0,0 +1,27 @@ +```java {tabTitle: Java} +import io.sentry.Sentry; +import io.sentry.SentryLevel; + +// will be tagged with my-tag="my value" +Sentry.captureException(new Exception("my error"), scope -> { + scope.setTag("my-tag", "my value"); + scope.setLevel(SentryLevel.WARNING); +}); + +// will not be tagged with my-tag +Sentry.captureException(new Exception("my error")); +``` + +```kotlin {tabTitle: Kotlin} +import io.sentry.Sentry +import io.sentry.SentryLevel + +// will be tagged with my-tag="my value" +Sentry.captureException(Exception("my error")) { scope -> + scope.setTag("my-tag", "my value") + scope.level = SentryLevel.WARNING +} + +// will not be tagged with my-tag +Sentry.captureException(Exception("my error")) +``` diff --git a/src/includes/enriching-events/scopes/with-scope/unreal.mdx b/src/includes/enriching-events/scopes/scope-callback-param/unreal.mdx similarity index 100% rename from src/includes/enriching-events/scopes/with-scope/unreal.mdx rename to src/includes/enriching-events/scopes/scope-callback-param/unreal.mdx diff --git a/src/includes/enriching-events/scopes/with-scope/java.mdx b/src/includes/enriching-events/scopes/with-scope/java.mdx index e3190e41193576..6ee220a969f2e8 100644 --- a/src/includes/enriching-events/scopes/with-scope/java.mdx +++ b/src/includes/enriching-events/scopes/with-scope/java.mdx @@ -1,57 +1,9 @@ - - -```java {tabTitle: Java} -import io.sentry.Sentry; -import io.sentry.SentryLevel; - -// will be tagged with my-tag="my value" -Sentry.captureException(new Exception("my error"), scope -> { - scope.setTag("my-tag", "my value"); - scope.setLevel(SentryLevel.WARNING); -}); - -// will not be tagged with my-tag -Sentry.captureException(new Exception("my error")); -``` - -```kotlin {tabTitle: Kotlin} -import io.sentry.Sentry -import io.sentry.SentryLevel - -// will be tagged with my-tag="my value" -Sentry.captureException(Exception("my error")) { scope -> - scope.setTag("my-tag", "my value") - scope.level = SentryLevel.WARNING -} - -// will not be tagged with my-tag -Sentry.captureException(Exception("my error")) -``` - - - -The JavaSDK provides two alternative ways of configuring a local scope. - ```java {tabTitle: Java} import io.sentry.Sentry; import io.sentry.SentryLevel; -// will be tagged with my-tag="my value" -Sentry.captureException(new Exception("my error"), scope -> { - scope.setTag("my-tag", "my value"); - scope.setLevel(SentryLevel.WARNING); -}); - -// will not be tagged with my-tag -Sentry.captureException(new Exception("my error")); -``` - -```java {tabTitle: Java-Alternative} -import io.sentry.Sentry; -import io.sentry.SentryLevel; - Sentry.withScope(scope -> { scope.setTag("my-tag", "my value"); scope.setLevel(SentryLevel.WARNING); @@ -68,20 +20,6 @@ Sentry.captureException(new Exception("my error")); import io.sentry.Sentry import io.sentry.SentryLevel -// will be tagged with my-tag="my value" -Sentry.captureException(Exception("my error")) { scope -> - scope.setTag("my-tag", "my value") - scope.level = SentryLevel.WARNING -} - -// will not be tagged with my-tag -Sentry.captureException(Exception("my error")) -``` - -```kotlin {tabTitle: Kotlin-Alternative} -import io.sentry.Sentry -import io.sentry.SentryLevel - Sentry.withScope { scope -> scope.setTag("my-tag", "my value") scope.level = SentryLevel.WARNING @@ -93,4 +31,11 @@ Sentry.withScope { scope -> // will not be tagged with my-tag Sentry.captureException(Exception("my error")) ``` + + + +In the Java SDK `with-scope` 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. + + + diff --git a/src/platforms/common/enriching-events/scopes.mdx b/src/platforms/common/enriching-events/scopes.mdx index f2914769035353..206766e0c0a649 100644 --- a/src/platforms/common/enriching-events/scopes.mdx +++ b/src/platforms/common/enriching-events/scopes.mdx @@ -93,13 +93,17 @@ You can also apply this configuration when unsetting a user at logout: To learn what useful information can be associated with scopes see [the context documentation](../context/). - - ## Local Scopes We also support pushing and configuring a scope within a single call. This is typically -called `with-scope` or `push-scope` depending on the SDK, and is very helpful if -you only want to send data for one specific event. In the following example we use +called `with-scope`, `push-scope` or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if +you only want to send data for one specific event. + + + +### Using `with-scope` + +In the following example we use `with-scope` to attach a `level` and a `tag` to only one specific error: @@ -123,6 +127,28 @@ caught, and all errors that occur will be silently ignored and **not** reported. + + +### Using Scope Callback Parameter + +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: + + + +Before the callback is invoked the SDK creates a clone of the current scope, and the changes +made will stay isolated within the callback function. This allows you to +more easily isolate pieces of context information to specific locations in your code or +even call `clear` to briefly remove all context information. + + + +Any exceptions that occur within the callback function for configuring a local scope will not be +caught, and all errors that occur will be silently ignored and **not** reported. + + + + + ## Kotlin Coroutines From 12e870ace8de745af107f527a6c709cd3b89b421 Mon Sep 17 00:00:00 2001 From: Lukas Bloder Date: Fri, 24 Jun 2022 13:44:20 +0200 Subject: [PATCH 3/3] CR remove local scope section from native, as it is not supported. Remove with-scope section from android --- src/includes/enriching-events/scopes/with-scope/native.mdx | 1 - src/platforms/common/enriching-events/scopes.mdx | 6 +++++- 2 files changed, 5 insertions(+), 2 deletions(-) delete mode 100644 src/includes/enriching-events/scopes/with-scope/native.mdx diff --git a/src/includes/enriching-events/scopes/with-scope/native.mdx b/src/includes/enriching-events/scopes/with-scope/native.mdx deleted file mode 100644 index b02ffbf1e714d5..00000000000000 --- a/src/includes/enriching-events/scopes/with-scope/native.mdx +++ /dev/null @@ -1 +0,0 @@ -_This is not supported by the Native SDK._ diff --git a/src/platforms/common/enriching-events/scopes.mdx b/src/platforms/common/enriching-events/scopes.mdx index 206766e0c0a649..a9ca7356327c3f 100644 --- a/src/platforms/common/enriching-events/scopes.mdx +++ b/src/platforms/common/enriching-events/scopes.mdx @@ -93,13 +93,15 @@ You can also apply this configuration when unsetting a user at logout: To learn what useful information can be associated with scopes see [the context documentation](../context/). + + ## Local Scopes We also support pushing and configuring a scope within a single call. This is typically called `with-scope`, `push-scope` or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if you only want to send data for one specific event. - + ### Using `with-scope` @@ -149,6 +151,8 @@ caught, and all errors that occur will be silently ignored and **not** reported. + + ## Kotlin Coroutines