Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Add migration docs for Hub #10126

Merged
merged 4 commits into from
Jan 10, 2024
Merged

chore: Add migration docs for Hub #10126

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6581d78
chore: Add migration docs for `Hub`
lforst Jan 10, 2024
41ff70b
Update MIGRATION.md
lforst Jan 10, 2024
c796d95
Remove section
lforst Jan 10, 2024
0c9dbc4
Apply review feedback
lforst Jan 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 44 additions & 11 deletions MIGRATION.md
View file
Open in desktop
lforst marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -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()`.
Expand Down Expand Up @@ -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:
Expand Down