From ff3ea99831488e2e9f43034365007dcd231be8e5 Mon Sep 17 00:00:00 2001 From: Ivana Kellyerova Date: Mon, 15 Apr 2024 15:07:38 +0200 Subject: [PATCH 1/2] docs: Better examples in migration guide --- MIGRATION_GUIDE.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 7215817d48..34f6e8849f 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -5,7 +5,7 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh ## New Features - Additional integrations will now be activated automatically if the SDK detects the respective package is installed: Ariadne, ARQ, asyncpg, Chalice, clickhouse-driver, GQL, Graphene, huey, Loguru, PyMongo, Quart, Starlite, Strawberry. -- Added new API for custom instrumentation: `new_scope`, `isolation_scope`. See the [Deprecated](#deprecated) section to see how they map to the existing APIs. +- As part of refactoring the [inner workings](https://docs.sentry.io/platforms/python/enriching-events/scopes/) of the SDK we added new top-level APIs for custom instrumentation called `new_scope` and `isolation_scope`. See the [Deprecated](#deprecated) section to see how they map to the existing APIs. ## Changed @@ -118,7 +118,7 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh # do something with the forked scope ``` -- `configure_scope` is deprecated. Use the new isolation scope directly via `Scope.get_isolation_scope()` instead. +- `configure_scope` is deprecated. Modify the current or isolation scope directly instead. Before: @@ -132,11 +132,22 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh ```python from sentry_sdk.scope import Scope + scope = Scope.get_current_scope() + # do something with `scope` + ``` + + Or: + + ```python + from sentry_sdk.scope import Scope + scope = Scope.get_isolation_scope() # do something with `scope` ``` -- `push_scope` is deprecated. Use the new `new_scope` context manager to fork the necessary scopes. + When to use `get_current_scope()` and `get_isolation_scope()` depends on how long the change to the scope should apply. If you want it to affect the whole request-response cycle or the whole execution of task, use the isolation scope. If it's more localized, use the current scope. + +- `push_scope` is deprecated. Fork the current or the isolation scope instead. Before: @@ -154,6 +165,17 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh # do something with `scope` ``` + Or: + + ```python + import sentry_sdk + + with sentry_sdk.isolation_scope() as scope: + # do something with `scope` + ``` + + `new_scope()` will fork the current scope, while `isolation_scope()` will fork the isolation scope. Isolation scopes roughly translate to transactions, so if you're looking to create a new separated scope for a whole request-response cycle or task execution, go for `isolation_scope()`. If you want to wrap a smaller unit code, fork the current scope instead with `new_scope()`. + - Accessing the client via the hub has been deprecated. Use the top-level `sentry_sdk.get_client()` to get the current client. - `profiler_mode` and `profiles_sample_rate` have been deprecated as `_experiments` options. Use them as top level options instead: ```python From 29d7a199e777696216ce6013250294833449da10 Mon Sep 17 00:00:00 2001 From: Ivana Kellyerova Date: Mon, 15 Apr 2024 15:12:21 +0200 Subject: [PATCH 2/2] wording --- MIGRATION_GUIDE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 34f6e8849f..ede427193c 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -1,11 +1,11 @@ # Sentry SDK 2.0 Migration Guide -Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of what's changed. +Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of what's changed. Looking for a more digestable summary? See the [guide in the docs](https://docs.sentry.io/platforms/python/migration/1.x-to-2.x) with the most common migration patterns. ## New Features - Additional integrations will now be activated automatically if the SDK detects the respective package is installed: Ariadne, ARQ, asyncpg, Chalice, clickhouse-driver, GQL, Graphene, huey, Loguru, PyMongo, Quart, Starlite, Strawberry. -- As part of refactoring the [inner workings](https://docs.sentry.io/platforms/python/enriching-events/scopes/) of the SDK we added new top-level APIs for custom instrumentation called `new_scope` and `isolation_scope`. See the [Deprecated](#deprecated) section to see how they map to the existing APIs. +- While refactoring the [inner workings](https://docs.sentry.io/platforms/python/enriching-events/scopes/) of the SDK we added new top-level APIs for custom instrumentation called `new_scope` and `isolation_scope`. See the [Deprecated](#deprecated) section to see how they map to the existing APIs. ## Changed @@ -145,7 +145,7 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh # do something with `scope` ``` - When to use `get_current_scope()` and `get_isolation_scope()` depends on how long the change to the scope should apply. If you want it to affect the whole request-response cycle or the whole execution of task, use the isolation scope. If it's more localized, use the current scope. + When to use `get_current_scope()` and `get_isolation_scope()` depends on how long the change to the scope should be in effect. If you want the changed scope to affect the whole request-response cycle or the whole execution of task, use the isolation scope. If it's more localized, use the current scope. - `push_scope` is deprecated. Fork the current or the isolation scope instead. @@ -174,7 +174,7 @@ Looking to upgrade from Sentry SDK 1.x to 2.x? Here's a comprehensive list of wh # do something with `scope` ``` - `new_scope()` will fork the current scope, while `isolation_scope()` will fork the isolation scope. Isolation scopes roughly translate to transactions, so if you're looking to create a new separated scope for a whole request-response cycle or task execution, go for `isolation_scope()`. If you want to wrap a smaller unit code, fork the current scope instead with `new_scope()`. + `new_scope()` will fork the current scope, while `isolation_scope()` will fork the isolation scope. The lifecycle of a single isolation scope roughly translates to the lifecycle of a transaction in most cases, so if you're looking to create a new separated scope for a whole request-response cycle or task execution, go for `isolation_scope()`. If you want to wrap a smaller unit code, fork the current scope instead with `new_scope()`. - Accessing the client via the hub has been deprecated. Use the top-level `sentry_sdk.get_client()` to get the current client. - `profiler_mode` and `profiles_sample_rate` have been deprecated as `_experiments` options. Use them as top level options instead: