feat(core): Deprecate the Hub constructor (#10574)

Co-authored-by: Francesco Novy <[email protected]>

Author: Luca Forstner

MIGRATION.md

@@ -289,6 +289,45 @@ If you are using the `Hub` right now, see the following table on how to migrate
 | endSession()           | `Sentry.endSession()`                                                                |
 | shouldSendDefaultPii() | REMOVED - The closest equivalent is `Sentry.getClient().getOptions().sendDefaultPii` |
 
+The `Hub` constructor is also deprecated and will be removed in the next major version. If you are creating Hubs for
+multi-client use like so:
+
+```ts
+// OLD
+const hub = new Hub();
+hub.bindClient(client);
+makeMain(hub);
+```
+
+instead initialize the client as follows:
+
+```ts
+// NEW
+Sentry.withIsolationScope(() => {
+  Sentry.setCurrentClient(client);
+  client.init();
+});
+```
+
+If you are using the Hub to capture events like so:
+
+```ts
+// OLD
+const client = new Client();
+const hub = new Hub(client);
+hub.captureException();
+```
+
+instead capture isolated events as follows:
+
+```ts
+// NEW
+const client = new Client();
+const scope = new Scope();
+scope.setClient(client);
+scope.captureException();
+```
+
 ## Deprecate `client.setupIntegrations()`
 
 Instead, use the new `client.init()` method. You should probably not use this directly and instead use `Sentry.init()`,

packages/bun/test/integrations/bunserver.test.ts

@@ -19,6 +19,7 @@ describe('Bun Serve Integration', () => {
   beforeEach(() => {
     const options = getDefaultBunClientOptions({ tracesSampleRate: 1, debug: true });
     client = new BunClient(options);
+    // eslint-disable-next-line deprecation/deprecation
     hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);

packages/core/src/hub.ts

@@ -110,6 +110,7 @@ function createHub(...options: ConstructorParameters<typeof Hub>): Hub {
     return sentry.createHub(...options);
   }
 
+  // eslint-disable-next-line deprecation/deprecation
   return new Hub(...options);
 }
 
@@ -132,6 +133,46 @@ export class Hub implements HubInterface {
    * @param client bound to the hub.
    * @param scope bound to the hub.
    * @param version number, higher number means higher priority.
+   *
+   * @deprecated Instantiation of Hub objects is deprecated and the constructor will be removed in version 8 of the SDK.
+   *
+   * If you are currently using the Hub for multi-client use like so:
+   *
+   * ```
+   * // OLD
+   * const hub = new Hub();
+   * hub.bindClient(client);
+   * makeMain(hub)
+   * ```
+   *
+   * instead initialize the client as follows:
+   *
+   * ```
+   * // NEW
+   * Sentry.withIsolationScope(() => {
+   *    Sentry.setCurrentClient(client);
+   *    client.init();
+   * });
+   * ```
+   *
+   * If you are using the Hub to capture events like so:
+   *
+   * ```
+   * // OLD
+   * const client = new Client();
+   * const hub = new Hub(client);
+   * hub.captureException()
+   * ```
+   *
+   * instead capture isolated events as follows:
+   *
+   * ```
+   * // NEW
+   * const client = new Client();
+   * const scope = new Scope();
+   * scope.setClient(client);
+   * scope.captureException();
+   * ```
    */
   public constructor(
     client?: Client,

packages/core/test/lib/base.test.ts

@@ -119,6 +119,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({});
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       scope.addBreadcrumb({ message: 'hello' }, 100);
@@ -134,6 +135,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({});
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       scope.addBreadcrumb({ message: 'hello' }, 100);
@@ -149,6 +151,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({ maxBreadcrumbs: 1 });
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       scope.addBreadcrumb({ message: 'hello' }, 100);
@@ -165,6 +168,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({});
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       scope.addBreadcrumb({ message: 'hello' });
@@ -181,6 +185,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({ beforeBreadcrumb });
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       // eslint-disable-next-line deprecation/deprecation
@@ -196,6 +201,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({ beforeBreadcrumb });
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       // eslint-disable-next-line deprecation/deprecation
@@ -211,6 +217,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({ beforeBreadcrumb });
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       // eslint-disable-next-line deprecation/deprecation
@@ -226,6 +233,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({ beforeBreadcrumb });
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
 
       // eslint-disable-next-line deprecation/deprecation
@@ -620,6 +628,7 @@ describe('BaseClient', () => {
       const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN, maxBreadcrumbs: 1 });
       const client = new TestClient(options);
       const scope = new Scope();
+      // eslint-disable-next-line deprecation/deprecation
       const hub = new Hub(client, scope);
       // eslint-disable-next-line deprecation/deprecation
       hub.addBreadcrumb({ message: '1' });

packages/core/test/lib/integration.test.ts

@@ -617,6 +617,7 @@ describe('addIntegration', () => {
     }
 
     const client = getTestClient();
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
@@ -635,6 +636,7 @@ describe('addIntegration', () => {
       setupOnce = jest.fn();
     }
 
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub();
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
@@ -660,6 +662,7 @@ describe('addIntegration', () => {
     }
 
     const client = getTestClient();
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
@@ -683,6 +686,7 @@ describe('addIntegration', () => {
     }
 
     const client = getTestClient();
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);

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

@@ -522,6 +522,7 @@ describe('withActiveSpan()', () => {
     const options = getDefaultTestClientOptions({ enableTracing: true });
     const client = new TestClient(options);
     const scope = new Scope();
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub(client, scope);
     makeMain(hub); // eslint-disable-line deprecation/deprecation
   });

packages/core/test/lib/sdk.test.ts

@@ -87,6 +87,7 @@ describe('SDK', () => {
 
 describe('captureCheckIn', () => {
   afterEach(function () {
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub();
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);

packages/core/test/lib/tracing/dynamicSamplingContext.test.ts

@@ -9,6 +9,7 @@ describe('getDynamicSamplingContextFromSpan', () => {
   beforeEach(() => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 1.0, release: '1.0.1' });
     const client = new TestClient(options);
+    // eslint-disable-next-line deprecation/deprecation
     hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);

packages/core/test/lib/tracing/errors.test.ts

@@ -34,6 +34,7 @@ describe('registerErrorHandlers()', () => {
     mockAddGlobalErrorInstrumentationHandler.mockClear();
     mockAddGlobalUnhandledRejectionInstrumentationHandler.mockClear();
     const options = getDefaultBrowserClientOptions({ enableTracing: true });
+    // eslint-disable-next-line deprecation/deprecation
     const hub = new Hub(new BrowserClient(options));
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);

packages/core/test/lib/tracing/trace.test.ts

@@ -36,6 +36,7 @@ describe('startSpan', () => {
   beforeEach(() => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 0.0 });
     client = new TestClient(options);
+    // eslint-disable-next-line deprecation/deprecation
     hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
@@ -427,6 +428,7 @@ describe('startSpanManual', () => {
   beforeEach(() => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 1 });
     client = new TestClient(options);
+    // eslint-disable-next-line deprecation/deprecation
     hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
@@ -537,6 +539,7 @@ describe('startInactiveSpan', () => {
   beforeEach(() => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 1 });
     client = new TestClient(options);
+    // eslint-disable-next-line deprecation/deprecation
     hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);
@@ -662,6 +665,7 @@ describe('continueTrace', () => {
   beforeEach(() => {
     const options = getDefaultTestClientOptions({ tracesSampleRate: 0.0 });
     client = new TestClient(options);
+    // eslint-disable-next-line deprecation/deprecation
     hub = new Hub(client);
     // eslint-disable-next-line deprecation/deprecation
     makeMain(hub);