feat(core): Add withActiveSpan (#10195)

Author: Luca Forstner

packages/core/src/exports.ts

@@ -17,6 +17,7 @@ import type {
   SessionContext,
   Severity,
   SeverityLevel,
+  Span,
   TransactionContext,
   User,
 } from '@sentry/types';
@@ -229,6 +230,21 @@ export function withIsolationScope<T>(callback: (isolationScope: Scope) => T): T
   });
 }
 
+/**
+ * Forks the current scope and sets the provided span as active span in the context of the provided callback.
+ *
+ * @param span Spans started in the context of the provided callback will be children of this span.
+ * @param callback Execution context in which the provided span will be active. Is passed the newly forked scope.
+ * @returns the value returned from the provided callback function.
+ */
+export function withActiveSpan<T>(span: Span, callback: (scope: Scope) => T): T {
+  return withScope(scope => {
+    // eslint-disable-next-line deprecation/deprecation
+    scope.setSpan(span);
+    return callback(scope);
+  });
+}
+
 /**
  * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *

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

@@ -1,6 +1,20 @@
 import type { Attachment, Breadcrumb, Client, Event } from '@sentry/types';
-import { applyScopeDataToEvent, getCurrentScope, getIsolationScope, withIsolationScope } from '../../src';
+import {
+  Hub,
+  addTracingExtensions,
+  applyScopeDataToEvent,
+  getActiveSpan,
+  getCurrentScope,
+  getIsolationScope,
+  makeMain,
+  startInactiveSpan,
+  startSpan,
+  withIsolationScope,
+} from '../../src';
+
+import { withActiveSpan } from '../../src/exports';
 import { Scope, getGlobalScope, setGlobalScope } from '../../src/scope';
+import { TestClient, getDefaultTestClientOptions } from '../mocks/client';
 
 describe('Scope', () => {
   beforeEach(() => {
@@ -503,3 +517,40 @@ describe('isolation scope', () => {
     });
   });
 });
+
+describe('withActiveSpan()', () => {
+  beforeAll(() => {
+    addTracingExtensions();
+  });
+
+  beforeEach(() => {
+    const options = getDefaultTestClientOptions({ enableTracing: true });
+    const client = new TestClient(options);
+    const scope = new Scope();
+    const hub = new Hub(client, scope);
+    makeMain(hub);
+  });
+
+  it('should set the active span within the callback', () => {
+    expect.assertions(2);
+    const inactiveSpan = startInactiveSpan({ name: 'inactive-span' });
+
+    expect(getActiveSpan()).not.toBe(inactiveSpan);
+
+    withActiveSpan(inactiveSpan!, () => {
+      expect(getActiveSpan()).toBe(inactiveSpan);
+    });
+  });
+
+  it('should create child spans when calling startSpan within the callback', done => {
+    expect.assertions(1);
+    const inactiveSpan = startInactiveSpan({ name: 'inactive-span' });
+
+    withActiveSpan(inactiveSpan!, () => {
+      startSpan({ name: 'child-span' }, childSpan => {
+        expect(childSpan?.parentSpanId).toBe(inactiveSpan?.spanContext().spanId);
+        done();
+      });
+    });
+  });
+});