From 1a7ea9ba5138ca843a13858d6d74a6e1cf2a7893 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 10 Jan 2024 12:54:55 +0100 Subject: [PATCH] chore: Add migration docs for `Hub` (#10126) Co-authored-by: Lukas Stracke --- MIGRATION.md | 55 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 7d8645fd4e16..95aa940265f3 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -8,6 +8,50 @@ npx @sentry/migr8@latest This will let you select which updates to run, and automatically update your code. Make sure to still review all code changes! +## Deprecate `Hub` + +The `Hub` has been a very important part of the Sentry SDK API up until now. +Hubs were the SDK's "unit of concurrency" to keep track of data across threads and to scope data to certain parts of your code. +Because it is overly complicated and confusing to power users, it is going to be replaced by a set of new APIs: the "new Scope API". + +`Scope`s have existed before in the SDK but we are now expanding on them because we have found them powerful enough to fully cover the `Hub` API. + +If you are using the `Hub` right now, see the following table on how to migrate to the new API: + +| Old `Hub` API | New `Scope` API | +| --- | --- | +| `new Hub()` | `withScope()`, `withIsolationScope()` or `new Scope()` | +| hub.isOlderThan() | REMOVED - Was used to compare `Hub` instances, which are gonna be removed | +| hub.bindClient() | A combination of `scope.setClient()` and `client.setupIntegrations()` | +| hub.pushScope() | `Sentry.withScope()` | +| hub.popScope() | `Sentry.withScope()` | +| hub.withScope() | `Sentry.withScope()` | +| getClient() | `Sentry.getClient()` | +| getScope() | `Sentry.getCurrentScope()` to get the currently active scope | +| getIsolationScope() | `Sentry.getIsolationScope()` | +| getStack() | REMOVED - The stack used to hold scopes. Scopes are used directly now | +| getStackTop() | REMOVED - The stack used to hold scopes. Scopes are used directly now | +| captureException() | `Sentry.captureException()` | +| captureMessage() | `Sentry.captureMessage()` | +| captureEvent() | `Sentry.captureEvent()` | +| lastEventId() | REMOVED - Use event processors or beforeSend instead | +| addBreadcrumb() | `Sentry.addBreadcrumb()` | +| setUser() | `Sentry.setUser()` | +| setTags() | `Sentry.setTags()` | +| setExtras() | `Sentry.setExtras()` | +| setTag() | `Sentry.setTag()` | +| setExtra() | `Sentry.setExtra()` | +| setContext() | `Sentry.setContext()` | +| configureScope() | REMOVED - Scopes are now the unit of concurrency | +| run() | `Sentry.withScope()` or `Sentry.withIsolationScope()` | +| getIntegration() | `client.getIntegration()` | +| startTransaction() | `Sentry.startSpan()`, `Sentry.startInactiveSpan()` or `Sentry.startSpanManual()` | +| traceHeaders() | REMOVED - The closest equivalent is now `spanToTraceHeader(getActiveSpan())` | +| captureSession() | `Sentry.captureSession()` | +| startSession() | `Sentry.startSession()` | +| endSession() | `Sentry.endSession()` | +| shouldSendDefaultPii() | REMOVED - The closest equivalent is `Sentry.getClient().getOptions().sendDefaultPii` | + ## Deprecate `scope.getSpan()` and `scope.setSpan()` Instead, you can get the currently active span via `Sentry.getActiveSpan()`. @@ -73,17 +117,6 @@ Sentry.init({ }); ``` -## Deprecated fields on `Hub` - -In v8, the Hub class will be removed. The following methods are therefore deprecated: - -* `hub.startTransaction()`: See [Deprecation of `startTransaction`](#deprecate-starttransaction) -* `hub.lastEventId()`: See [Deprecation of `lastEventId`](#deprecate-sentrylasteventid-and-hublasteventid) -* `hub.startSession()`: Use top-level `Sentry.startSession()` instead -* `hub.endSession()`: Use top-level `Sentry.endSession()` instead -* `hub.captureSession()`: Use top-level `Sentry.captureSession()` instead -* `hub.shouldSendDefaultPii()`: Access Sentry client option via `Sentry.getClient().getOptions().sendDefaultPii` instead - ## Deprecated fields on `Span` and `Transaction` In v8, the Span class is heavily reworked. The following properties & methods are thus deprecated: