feat(core): Add withIsolationScope

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/astro/src/index.server.ts

@@ -46,6 +46,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  autoDiscoverNodePerformanceMonitoringIntegrations,
  makeNodeTransport,
  defaultIntegrations,

packages/browser/src/exports.ts

@@ -60,6 +60,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  FunctionToString,
  InboundFilters,
  metrics,

packages/bun/src/index.ts

@@ -66,6 +66,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/core/src/exports.ts

@@ -25,6 +25,7 @@ import { GLOBAL_OBJ, isThenable, logger, timestampInSeconds, uuid4 } from '@sent
 import { DEFAULT_ENVIRONMENT } from './constants';
 import { DEBUG_BUILD } from './debug-build';
 import type { Hub } from './hub';
+import { runWithAsyncContext } from './hub';
 import { getCurrentHub, getIsolationScope } from './hub';
 import type { Scope } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
@@ -35,7 +36,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
  * Captures an exception event and sends it to Sentry.
  *
  * @param exception The exception to capture.
- * @param hint Optinal additional data to attach to the Sentry event.
+ * @param hint Optional additional data to attach to the Sentry event.
  * @returns the id of the captured Sentry event.
  */
 export function captureException(
@@ -208,6 +209,26 @@ export function withScope<T>(
  return getCurrentHub().withScope(rest[0]);
 }
 
+/**
+ * Attempts to fork the current isolation scope and the current scope based on the current async context strategy. If no
+ * async context strategy is set, the isolation scope and the current scope will not be forked (this is currently the
+ * case, for example, in the browser).
+ *
+ * Usage of this function in environments without async context strategy is discouraged and may lead to unexpected behaviour.
+ *
+ * This function is intended for Sentry SDK and SDK integration development. It is not recommended to be used in "normal"
+ * applications directly because it comes with pitfalls. Use at your own risk!
+ *
+ * @param callback The callback in which the passed isolation scope is active. (Note: In environments without async
+ * context strategy, the currently active isolation scope may change within execution of the callback.)
+ * @returns The same value that `callback` returns.
+ */
+export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T {
+ return runWithAsyncContext(() => {
+ return callback(getIsolationScope());
+ });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

packages/core/src/index.ts

@@ -29,6 +29,7 @@ export {
  setTags,
  setUser,
  withScope,
+ withIsolationScope,
  getClient,
  getCurrentScope,
  startSession,

packages/core/test/lib/async-context.test.ts

@@ -0,0 +1,13 @@
+import { getCurrentHub, runWithAsyncContext } from '../../src';
+
+describe('runWithAsyncContext()', () => {
+ it('without strategy hubs should be equal', () => {
+ runWithAsyncContext(() => {
+ const hub1 = getCurrentHub();
+ runWithAsyncContext(() => {
+ const hub2 = getCurrentHub();
+ expect(hub1).toBe(hub2);
+ });
+ });
+ });
+});

packages/core/test/lib/scope.test.ts

@@ -1,5 +1,5 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent } from '../../src';
+import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
 
 describe('Scope', () => {
@@ -465,3 +465,41 @@ describe('Scope', () => {
  });
  });
 });
+
+describe('isolation scope', () => {
+ describe('withIsolationScope()', () => {
+ it('will pass an isolation scope without Sentry.init()', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(scope).toBeDefined();
+ done();
+ });
+ });
+
+ it('will make the passed isolation scope the active isolation scope within the callback', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getIsolationScope()).toBe(scope);
+ done();
+ });
+ });
+
+ it('will pass an isolation scope that is different from the current active scope', done => {
+ expect.assertions(1);
+ withIsolationScope(scope => {
+ expect(getCurrentScope()).not.toBe(scope);
+ done();
+ });
+ });
+
+ it('will always make the inner most passed scope the current scope when nesting calls', done => {
+ expect.assertions(1);
+ withIsolationScope(_scope1 => {
+ withIsolationScope(scope2 => {
+ expect(getIsolationScope()).toBe(scope2);
+ done();
+ });
+ });
+ });
+ });
+});

packages/deno/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,

packages/node/src/index.ts

@@ -65,6 +65,7 @@ export {
  // eslint-disable-next-line deprecation/deprecation
  trace,
  withScope,
+ withIsolationScope,
  captureCheckIn,
  withMonitor,
  setMeasurement,