Skip to content

Commit 1a7ea9b

Browse files
Luca ForstnerLms24
Luca Forstner
andauthored
chore: Add migration docs for Hub (#10126)
Co-authored-by: Lukas Stracke <[email protected]>
1 parent 6faec42 commit 1a7ea9b

File tree

1 file changed

+44
-11
lines changed

1 file changed

+44
-11
lines changed

MIGRATION.md

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,50 @@ npx @sentry/migr8@latest
88

99
This will let you select which updates to run, and automatically update your code. Make sure to still review all code changes!
1010

11+
## Deprecate `Hub`
12+
13+
The `Hub` has been a very important part of the Sentry SDK API up until now.
14+
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.
15+
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".
16+
17+
`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.
18+
19+
If you are using the `Hub` right now, see the following table on how to migrate to the new API:
20+
21+
| Old `Hub` API | New `Scope` API |
22+
| --- | --- |
23+
| `new Hub()` | `withScope()`, `withIsolationScope()` or `new Scope()` |
24+
| hub.isOlderThan() | REMOVED - Was used to compare `Hub` instances, which are gonna be removed |
25+
| hub.bindClient() | A combination of `scope.setClient()` and `client.setupIntegrations()` |
26+
| hub.pushScope() | `Sentry.withScope()` |
27+
| hub.popScope() | `Sentry.withScope()` |
28+
| hub.withScope() | `Sentry.withScope()` |
29+
| getClient() | `Sentry.getClient()` |
30+
| getScope() | `Sentry.getCurrentScope()` to get the currently active scope |
31+
| getIsolationScope() | `Sentry.getIsolationScope()` |
32+
| getStack() | REMOVED - The stack used to hold scopes. Scopes are used directly now |
33+
| getStackTop() | REMOVED - The stack used to hold scopes. Scopes are used directly now |
34+
| captureException() | `Sentry.captureException()` |
35+
| captureMessage() | `Sentry.captureMessage()` |
36+
| captureEvent() | `Sentry.captureEvent()` |
37+
| lastEventId() | REMOVED - Use event processors or beforeSend instead |
38+
| addBreadcrumb() | `Sentry.addBreadcrumb()` |
39+
| setUser() | `Sentry.setUser()` |
40+
| setTags() | `Sentry.setTags()` |
41+
| setExtras() | `Sentry.setExtras()` |
42+
| setTag() | `Sentry.setTag()` |
43+
| setExtra() | `Sentry.setExtra()` |
44+
| setContext() | `Sentry.setContext()` |
45+
| configureScope() | REMOVED - Scopes are now the unit of concurrency |
46+
| run() | `Sentry.withScope()` or `Sentry.withIsolationScope()` |
47+
| getIntegration() | `client.getIntegration()` |
48+
| startTransaction() | `Sentry.startSpan()`, `Sentry.startInactiveSpan()` or `Sentry.startSpanManual()` |
49+
| traceHeaders() | REMOVED - The closest equivalent is now `spanToTraceHeader(getActiveSpan())` |
50+
| captureSession() | `Sentry.captureSession()` |
51+
| startSession() | `Sentry.startSession()` |
52+
| endSession() | `Sentry.endSession()` |
53+
| shouldSendDefaultPii() | REMOVED - The closest equivalent is `Sentry.getClient().getOptions().sendDefaultPii` |
54+
1155
## Deprecate `scope.getSpan()` and `scope.setSpan()`
1256

1357
Instead, you can get the currently active span via `Sentry.getActiveSpan()`.
@@ -73,17 +117,6 @@ Sentry.init({
73117
});
74118
```
75119

76-
## Deprecated fields on `Hub`
77-
78-
In v8, the Hub class will be removed. The following methods are therefore deprecated:
79-
80-
* `hub.startTransaction()`: See [Deprecation of `startTransaction`](#deprecate-starttransaction)
81-
* `hub.lastEventId()`: See [Deprecation of `lastEventId`](#deprecate-sentrylasteventid-and-hublasteventid)
82-
* `hub.startSession()`: Use top-level `Sentry.startSession()` instead
83-
* `hub.endSession()`: Use top-level `Sentry.endSession()` instead
84-
* `hub.captureSession()`: Use top-level `Sentry.captureSession()` instead
85-
* `hub.shouldSendDefaultPii()`: Access Sentry client option via `Sentry.getClient().getOptions().sendDefaultPii` instead
86-
87120
## Deprecated fields on `Span` and `Transaction`
88121

89122
In v8, the Span class is heavily reworked. The following properties & methods are thus deprecated:

0 commit comments

Comments
 (0)