withIsolationScope docs are confusing or contradicting

[gotenxds]

Hello, I'm migrating from v7 to v10 and the new withIsolationScope is confusing to me, the migration guide says to use it instead of runWithAsyncContext.

At the same time, the current docs state to use it if you want to "isolate some code"

But the code docs state not to use that function, stating it is not ment for "normal" applications and that it is not recommended to use it.

A bit of cleaification of this would be great, thank you.

[faizansaiyed123]

The migration guide is referring to the replacement for runWithAsyncContext when you need to run code in a separate Sentry isolation context.

withIsolationScope forks the current isolation scope for the callback, so context added inside that callback stays isolated from surrounding work. This is different from withScope, which is generally useful for adding temporary context to events captured within a specific operation.

For most applications using supported framework integrations, Sentry manages the relevant scopes automatically, so you usually don't need to wrap every function manually. withIsolationScope is useful when you have a custom async execution boundary or deliberately need to isolate Sentry context.

So, for code that previously used runWithAsyncContext, the v8+ migration is:

Sentry.withIsolationScope(() => {
  // Your isolated work
});

The distinction is that withIsolationScope is the migration replacement, but it isn't something every ordinary application function needs to call.