Skip to content

chore: Add migration docs for Hub #10126

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

Merged
merged 4 commits into from
Jan 10, 2024
Merged

chore: Add migration docs for Hub #10126

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6581d78
chore: Add migration docs for `Hub`
Jan 10, 2024
41ff70b
Update MIGRATION.md
Jan 10, 2024
c796d95
Remove section
Jan 10, 2024
0c9dbc4
Apply review feedback
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
44 changes: 44 additions & 0 deletions MIGRATION.md
View file
Open in desktop
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 SDKs "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() | Best replaced with `withScope()` |
Copy link
Member

@mydea mydea Jan 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| hub.pushScope() | Best replaced with `withScope()` |
| hub.pushScope() | `Sentry.withScope()` |

| hub.popScope() | When used in combination with `hub.pushScope()` best replaced with `withScope()` |
Copy link
Member

@mydea mydea Jan 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| hub.popScope() | When used in combination with `hub.pushScope()` best replaced with `withScope()` |
| hub.popScope() | `Sentry.withScope()` |

| hub.withScope() | `withScope()` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| hub.withScope() | `withScope()` |
| hub.withScope() | `Sentry.withScope()` |

| getClient() | `scope.getClient` |
Copy link
Member

@mydea mydea Jan 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| getClient() | `scope.getClient` |
| getClient() | `Sentry.getClient()` |

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

users should never use scope.getClient() in the future, as we want to cascade the clients in v8 (so it is only set on the isolation scope).

| getScope() | REMOVED - Scopes are used directly now. |
Copy link
Member

@mydea mydea Jan 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| getScope() | REMOVED - Scopes are used directly now. |
| 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() | `scope.captureException()` |
| captureMessage() | `scope.captureMessage()` |
| captureEvent() | `scope.captureEvent()` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| captureException() | `scope.captureException()` |
| captureMessage() | `scope.captureMessage()` |
| captureEvent() | `scope.captureEvent()` |
| captureException() | `Sentry.captureException()` |
| captureMessage() | `Sentry.captureMessage()` |
| captureEvent() | `Sentry.captureEvent()` |

IMHO users should avoid using these on the scope directly, just use the global methods.

| lastEventId() | REMOVED - Use event processors or beforeSend instead. |
| addBreadcrumb() | `scope.addBreadcrumb()` |
| setUser() | `scope.setUser()` |
| setTags() | `scope.setTags()` |
| setExtras() | `scope.setExtras()` |
| setTag() | `scope.setTag()` |
| setExtra() | `scope.setExtra()` |
| setContext() | `scope.setContext()` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| addBreadcrumb() | `scope.addBreadcrumb()` |
| setUser() | `scope.setUser()` |
| setTags() | `scope.setTags()` |
| setExtras() | `scope.setExtras()` |
| setTag() | `scope.setTag()` |
| setExtra() | `scope.setExtra()` |
| setContext() | `scope.setContext()` |
| 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() | `withScope()` or `withIsolationScope()` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| run() | `withScope()` or `withIsolationScope()` |
| run() | `Sentry.withScope()` or `Sentry.withIsolationScope()` |

| getIntegration() | `client.getIntegration()` |
| startTransaction() | `startSpan()`, `startInactiveSpan()` or `startSpanManual()` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| startTransaction() | `startSpan()`, `startInactiveSpan()` or `startSpanManual()` |
| startTransaction() | `Sentry.startSpan()`, `Sentry.startInactiveSpan()` or `Sentry.startSpanManual()` |

| traceHeaders() | REMOVED - The closest equivalent is now `spanToTraceHeader(getActiveSpan())` |
| captureSession() | Use top level `Sentry.captureSession()` |
| startSession() | Top level `Sentry.startSession()` |
| endSession() | Top level `Sentry.endSession()` |
| shouldSendDefaultPii() | REMOVED - The closest equivalent is `scope.getClient().getOptions().sendDefaultPii` |

## Deprecate `scope.getSpan()` and `scope.setSpan()`

Instead, you can get the currently active span via `Sentry.getActiveSpan()`.
Expand Down