feat(core): Deprecate startTransaction() (#10073)

This finally deprecates `startTransaction()`. There are only few
remaining usages in our own code base, which we can refactor as we go.

I chose to leave usages in E2E/integration tests for now, we can then
refactor them when we get rid of these to ensure the behavior remains
the same.

---------

Co-authored-by: Lukas Stracke <[email protected]>

Author: mydea

MIGRATION.md

@@ -8,6 +8,17 @@ 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 `startTransaction()`
+
+In v8, the old performance API `startTransaction()` (as well as `hub.startTransaction()`) will be removed.
+Instead, use the new performance APIs:
+
+* `startSpan()`
+* `startSpanManual()`
+* `startInactiveSpan()`
+
+You can [read more about the new performance APIs here](./docs/v8-new-performance-apis.md).
+
 ## Deprecate `Sentry.lastEventId()` and `hub.lastEventId()`
 
 `Sentry.lastEventId()` sometimes causes race conditons, so we are deprecating it in favour of the `beforeSend` callback.

dev-packages/e2e-tests/test-applications/create-next-app/pages/api/success.ts

@@ -3,6 +3,7 @@ import * as Sentry from '@sentry/nextjs';
 import type { NextApiRequest, NextApiResponse } from 'next';
 
 export default function handler(req: NextApiRequest, res: NextApiResponse) {
+  // eslint-disable-next-line deprecation/deprecation
   const transaction = Sentry.startTransaction({ name: 'test-transaction', op: 'e2e-test' });
   Sentry.getCurrentHub().getScope().setSpan(transaction);
 

dev-packages/e2e-tests/test-applications/node-express-app/src/app.ts

@@ -34,6 +34,7 @@ app.get('/test-param/:param', function (req, res) {
 });
 
 app.get('/test-transaction', async function (req, res) {
+  // eslint-disable-next-line deprecation/deprecation
   const transaction = Sentry.startTransaction({ name: 'test-transaction', op: 'e2e-test' });
   Sentry.getCurrentScope().setSpan(transaction);
 

dev-packages/node-integration-tests/suites/public-api/startTransaction/basic-usage/scenario.ts

@@ -9,6 +9,7 @@ Sentry.init({
   tracesSampleRate: 1.0,
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({ name: 'test_transaction_1' });
 
 transaction.end();

dev-packages/node-integration-tests/suites/public-api/startTransaction/with-nested-spans/scenario.ts

@@ -8,6 +8,7 @@ Sentry.init({
   tracesSampleRate: 1.0,
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({ name: 'test_transaction_1' });
 const span_1 = transaction.startChild({
   op: 'span_1',

dev-packages/node-integration-tests/suites/tracing-new/apollo-graphql/scenario.ts

@@ -27,6 +27,7 @@ const server = new ApolloServer({
   resolvers,
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({ name: 'test_transaction', op: 'transaction' });
 
 Sentry.getCurrentScope().setSpan(transaction);

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/mongodb/scenario.ts

@@ -16,6 +16,7 @@ const client = new MongoClient(process.env.MONGO_URL || '', {
 });
 
 async function run(): Promise<void> {
+  // eslint-disable-next-line deprecation/deprecation
   const transaction = Sentry.startTransaction({
     name: 'Test Transaction',
     op: 'transaction',

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/mysql/withConnect/scenario.ts

@@ -19,6 +19,7 @@ connection.connect(function (err: unknown) {
   }
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({
   op: 'transaction',
   name: 'Test Transaction',

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/mysql/withoutCallback/scenario.ts

@@ -19,6 +19,7 @@ connection.connect(function (err: unknown) {
   }
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({
   op: 'transaction',
   name: 'Test Transaction',

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/mysql/withoutConnect/scenario.ts

@@ -13,6 +13,7 @@ const connection = mysql.createConnection({
   password: 'docker',
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({
   op: 'transaction',
   name: 'Test Transaction',

dev-packages/node-integration-tests/suites/tracing-new/auto-instrument/pg/scenario.ts

@@ -8,6 +8,7 @@ Sentry.init({
   integrations: [...Sentry.autoDiscoverNodePerformanceMonitoringIntegrations()],
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({
   op: 'transaction',
   name: 'Test Transaction',

dev-packages/node-integration-tests/suites/tracing-new/prisma-orm/scenario.ts

@@ -13,6 +13,7 @@ Sentry.init({
 });
 
 async function run(): Promise<void> {
+  // eslint-disable-next-line deprecation/deprecation
   const transaction = Sentry.startTransaction({
     name: 'Test Transaction',
     op: 'transaction',

dev-packages/node-integration-tests/suites/tracing-new/tracePropagationTargets/scenario.ts

@@ -10,6 +10,7 @@ Sentry.init({
   integrations: [new Sentry.Integrations.Http({ tracing: true })],
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({ name: 'test_transaction' });
 
 Sentry.getCurrentScope().setSpan(transaction);

dev-packages/node-integration-tests/suites/tracing/apollo-graphql/scenario.ts

@@ -29,6 +29,7 @@ const server = new ApolloServer({
   resolvers,
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({ name: 'test_transaction', op: 'transaction' });
 
 Sentry.getCurrentScope().setSpan(transaction);

dev-packages/node-integration-tests/suites/tracing/auto-instrument/mongodb/scenario.ts

@@ -17,6 +17,7 @@ const client = new MongoClient(process.env.MONGO_URL || '', {
 });
 
 async function run(): Promise<void> {
+  // eslint-disable-next-line deprecation/deprecation
   const transaction = Sentry.startTransaction({
     name: 'Test Transaction',
     op: 'transaction',

dev-packages/node-integration-tests/suites/tracing/auto-instrument/mysql/scenario.ts

@@ -20,6 +20,7 @@ connection.connect(function (err: unknown) {
   }
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({
   op: 'transaction',
   name: 'Test Transaction',

dev-packages/node-integration-tests/suites/tracing/auto-instrument/pg/scenario.ts

@@ -9,6 +9,7 @@ Sentry.init({
   tracesSampleRate: 1.0,
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({
   op: 'transaction',
   name: 'Test Transaction',

dev-packages/node-integration-tests/suites/tracing/prisma-orm/scenario.ts

@@ -15,6 +15,7 @@ Sentry.init({
 });
 
 async function run(): Promise<void> {
+  // eslint-disable-next-line deprecation/deprecation
   const transaction = Sentry.startTransaction({
     name: 'Test Transaction',
     op: 'transaction',

dev-packages/node-integration-tests/suites/tracing/tracePropagationTargets/scenario.ts

@@ -12,6 +12,7 @@ Sentry.init({
   integrations: [new Sentry.Integrations.Http({ tracing: true })],
 });
 
+// eslint-disable-next-line deprecation/deprecation
 const transaction = Sentry.startTransaction({ name: 'test_transaction' });
 
 Sentry.getCurrentScope().setSpan(transaction);

packages/astro/src/index.server.ts

@@ -32,6 +32,7 @@ export {
   Hub,
   makeMain,
   Scope,
+  // eslint-disable-next-line deprecation/deprecation
   startTransaction,
   SDK_VERSION,
   setContext,

packages/browser/src/exports.ts

@@ -45,6 +45,7 @@ export {
   lastEventId,
   makeMain,
   Scope,
+  // eslint-disable-next-line deprecation/deprecation
   startTransaction,
   getActiveSpan,
   startSpan,

packages/bun/src/index.ts

@@ -52,6 +52,7 @@ export {
   makeMain,
   runWithAsyncContext,
   Scope,
+  // eslint-disable-next-line deprecation/deprecation
   startTransaction,
   SDK_VERSION,
   setContext,

packages/core/src/exports.ts

@@ -190,11 +190,14 @@ export function withScope<T>(callback: (scope: Scope) => T): T {
  * default values). See {@link Options.tracesSampler}.
  *
  * @returns The transaction which was just started
+ *
+ * @deprecated Use `startSpan()`, `startSpanManual()` or `startInactiveSpan()` instead.
  */
 export function startTransaction(
   context: TransactionContext,
   customSamplingContext?: CustomSamplingContext,
 ): ReturnType<Hub['startTransaction']> {
+  // eslint-disable-next-line deprecation/deprecation
   return getCurrentHub().startTransaction({ ...context }, customSamplingContext);
 }
 

packages/core/src/hub.ts

@@ -440,7 +440,23 @@ export class Hub implements HubInterface {
   }
 
   /**
-   * @inheritDoc
+   * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
+   *
+   * A tree structure can be built by adding child spans to the transaction, and child spans to other spans. To start a
+   * new child span within the transaction or any span, call the respective `.startChild()` method.
+   *
+   * Every child span must be finished before the transaction is finished, otherwise the unfinished spans are discarded.
+   *
+   * The transaction must be finished with a call to its `.end()` method, at which point the transaction with all its
+   * finished child spans will be sent to Sentry.
+   *
+   * @param context Properties of the new `Transaction`.
+   * @param customSamplingContext Information given to the transaction sampling function (along with context-dependent
+   * default values). See {@link Options.tracesSampler}.
+   *
+   * @returns The transaction which was just started
+   *
+   * @deprecated Use `startSpan()`, `startSpanManual()` or `startInactiveSpan()` instead.
    */
   public startTransaction(context: TransactionContext, customSamplingContext?: CustomSamplingContext): Transaction {
     const result = this._callExtensionMethod<Transaction>('startTransaction', context, customSamplingContext);

packages/core/src/index.ts

@@ -19,6 +19,7 @@ export {
   flush,
   // eslint-disable-next-line deprecation/deprecation
   lastEventId,
+  // eslint-disable-next-line deprecation/deprecation
   startTransaction,
   setContext,
   setExtra,

packages/core/src/tracing/trace.ts

@@ -157,7 +157,10 @@ export function startInactiveSpan(context: StartSpanOptions): Span | undefined {
   const ctx = normalizeContext(context);
   const hub = getCurrentHub();
   const parentSpan = getActiveSpan();
-  return parentSpan ? parentSpan.startChild(ctx) : hub.startTransaction(ctx);
+  return parentSpan
+    ? parentSpan.startChild(ctx)
+    : // eslint-disable-next-line deprecation/deprecation
+      hub.startTransaction(ctx);
 }
 
 /**
@@ -236,7 +239,10 @@ function createChildSpanOrTransaction(
   if (!hasTracingEnabled()) {
     return undefined;
   }
-  return parentSpan ? parentSpan.startChild(ctx) : hub.startTransaction(ctx);
+  return parentSpan
+    ? parentSpan.startChild(ctx)
+    : // eslint-disable-next-line deprecation/deprecation
+      hub.startTransaction(ctx);
 }
 
 /**

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

@@ -1,5 +1,5 @@
 import { BrowserClient } from '@sentry/browser';
-import { Hub, addTracingExtensions, makeMain } from '@sentry/core';
+import { Hub, addTracingExtensions, makeMain, startInactiveSpan, startSpan } from '@sentry/core';
 import type { HandlerDataError, HandlerDataUnhandledRejection } from '@sentry/types';
 
 import { getDefaultBrowserClientOptions } from '../../../../tracing/test/testutils';
@@ -30,19 +30,14 @@ beforeAll(() => {
 });
 
 describe('registerErrorHandlers()', () => {
-  let hub: Hub;
   beforeEach(() => {
     mockAddGlobalErrorInstrumentationHandler.mockClear();
     mockAddGlobalUnhandledRejectionInstrumentationHandler.mockClear();
-    const options = getDefaultBrowserClientOptions();
-    hub = new Hub(new BrowserClient(options));
+    const options = getDefaultBrowserClientOptions({ enableTracing: true });
+    const hub = new Hub(new BrowserClient(options));
     makeMain(hub);
   });
 
-  afterEach(() => {
-    hub.getScope().setSpan(undefined);
-  });
-
   it('registers error instrumentation', () => {
     registerErrorInstrumentation();
     expect(mockAddGlobalErrorInstrumentationHandler).toHaveBeenCalledTimes(1);
@@ -53,7 +48,8 @@ describe('registerErrorHandlers()', () => {
 
   it('does not set status if transaction is not on scope', () => {
     registerErrorInstrumentation();
-    const transaction = hub.startTransaction({ name: 'test' });
+
+    const transaction = startInactiveSpan({ name: 'test' })!;
     expect(transaction.status).toBe(undefined);
 
     mockErrorCallback({} as HandlerDataError);
@@ -66,22 +62,19 @@ describe('registerErrorHandlers()', () => {
 
   it('sets status for transaction on scope on error', () => {
     registerErrorInstrumentation();
-    const transaction = hub.startTransaction({ name: 'test' });
-    hub.getScope().setSpan(transaction);
-
-    mockErrorCallback({} as HandlerDataError);
-    expect(transaction.status).toBe('internal_error');
 
-    transaction.end();
+    startSpan({ name: 'test' }, span => {
+      mockErrorCallback({} as HandlerDataError);
+      expect(span?.status).toBe('internal_error');
+    });
   });
 
   it('sets status for transaction on scope on unhandledrejection', () => {
     registerErrorInstrumentation();
-    const transaction = hub.startTransaction({ name: 'test' });
-    hub.getScope().setSpan(transaction);
 
-    mockUnhandledRejectionCallback({});
-    expect(transaction.status).toBe('internal_error');
-    transaction.end();
+    startSpan({ name: 'test' }, span => {
+      mockUnhandledRejectionCallback({});
+      expect(span?.status).toBe('internal_error');
+    });
   });
 });

packages/deno/src/index.ts

@@ -51,6 +51,7 @@ export {
   makeMain,
   runWithAsyncContext,
   Scope,
+  // eslint-disable-next-line deprecation/deprecation
   startTransaction,
   SDK_VERSION,
   setContext,

packages/hub/src/index.ts

@@ -118,6 +118,7 @@ export const configureScope = configureScopeCore;
 /**
  * @deprecated This export has moved to @sentry/core. The @sentry/hub package will be removed in v8.
  */
+// eslint-disable-next-line deprecation/deprecation
 export const startTransaction = startTransactionCore;
 
 /**

packages/nextjs/src/common/utils/wrapperUtils.ts

@@ -100,6 +100,8 @@ export function withTracedServerSideDataFetcher<F extends (...args: any[]) => Pr
       if (platformSupportsStreaming()) {
         let spanToContinue: Span;
         if (previousSpan === undefined) {
+          // TODO: Refactor this to use `startSpan()`
+          // eslint-disable-next-line deprecation/deprecation
           const newTransaction = startTransaction(
             {
               op: 'http.server',
@@ -136,6 +138,8 @@ export function withTracedServerSideDataFetcher<F extends (...args: any[]) => Pr
           status: 'ok',
         });
       } else {
+        // TODO: Refactor this to use `startSpan()`
+        // eslint-disable-next-line deprecation/deprecation
         dataFetcherSpan = startTransaction({
           op: 'function.nextjs',
           name: `${options.dataFetchingMethodName} (${options.dataFetcherRouteName})`,

packages/nextjs/test/clientSdk.test.ts

@@ -1,6 +1,6 @@
 import { BaseClient, getCurrentHub } from '@sentry/core';
 import * as SentryReact from '@sentry/react';
-import { BrowserTracing, WINDOW } from '@sentry/react';
+import { BrowserTracing, WINDOW, getCurrentScope } from '@sentry/react';
 import type { Integration } from '@sentry/types';
 import type { UserIntegrationsFunction } from '@sentry/utils';
 import { logger } from '@sentry/utils';
@@ -89,8 +89,12 @@ describe('Client init()', () => {
     const hub = getCurrentHub();
     const transportSend = jest.spyOn(hub.getClient()!.getTransport()!, 'send');
 
-    const transaction = hub.startTransaction({ name: '/404' });
-    transaction.end();
+    // Ensure we have no current span, so our next span is a transaction
+    getCurrentScope().setSpan(undefined);
+
+    SentryReact.startSpan({ name: '/404' }, () => {
+      // noop
+    });
 
     expect(transportSend).not.toHaveBeenCalled();
     expect(captureEvent.mock.results[0].value).toBeUndefined();

packages/nextjs/test/serverSdk.test.ts

@@ -105,8 +105,9 @@ describe('Server init()', () => {
     const hub = getCurrentHub();
     const transportSend = jest.spyOn(hub.getClient()!.getTransport()!, 'send');
 
-    const transaction = hub.startTransaction({ name: '/404' });
-    transaction.end();
+    SentryNode.startSpan({ name: '/404' }, () => {
+      // noop
+    });
 
     // We need to flush because the event processor pipeline is async whereas transaction.end() is sync.
     await SentryNode.flush();