feat(core): Add continueTrace method (#9164)

This adds a new `continueTrace` method which can be used to continue a
trace from headers.

This method has the following signature:

```ts
function continueTrace<V>(
  {
    sentryTrace,
    baggage,
  }: {
    sentryTrace: Parameters<typeof tracingContextFromHeaders>[0];
    baggage: Parameters<typeof tracingContextFromHeaders>[1];
  },
  callback: (transactionContext: Partial<TransactionContext>) => V,
): V
```

Author: mydea

packages/browser/src/exports.ts

@@ -41,6 +41,7 @@ export {
   startSpan,
   startInactiveSpan,
   startSpanManual,
+  continueTrace,
   SDK_VERSION,
   setContext,
   setExtra,

packages/bun/src/index.ts

@@ -59,6 +59,7 @@ export {
   startSpan,
   startInactiveSpan,
   startSpanManual,
+  continueTrace,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';
 export { autoDiscoverNodePerformanceMonitoringIntegrations } from '@sentry/node';

packages/core/src/tracing/index.ts

@@ -7,8 +7,16 @@ export { extractTraceparentData, getActiveTransaction } from './utils';
 // eslint-disable-next-line deprecation/deprecation
 export { SpanStatus } from './spanstatus';
 export type { SpanStatusType } from './span';
-// eslint-disable-next-line deprecation/deprecation
-export { trace, getActiveSpan, startSpan, startInactiveSpan, startActiveSpan, startSpanManual } from './trace';
+export {
+  trace,
+  getActiveSpan,
+  startSpan,
+  startInactiveSpan,
+  // eslint-disable-next-line deprecation/deprecation
+  startActiveSpan,
+  startSpanManual,
+  continueTrace,
+} from './trace';
 export { getDynamicSamplingContextFromClient } from './dynamicSamplingContext';
 export { setMeasurement } from './measurement';
 export { sampleTransaction } from './sampling';

packages/core/src/tracing/trace.ts

@@ -1,5 +1,5 @@
 import type { TransactionContext } from '@sentry/types';
-import { isThenable } from '@sentry/utils';
+import { dropUndefinedKeys, isThenable, logger, tracingContextFromHeaders } from '@sentry/utils';
 
 import type { Hub } from '../hub';
 import { getCurrentHub } from '../hub';
@@ -203,6 +203,48 @@ export function getActiveSpan(): Span | undefined {
   return getCurrentHub().getScope().getSpan();
 }
 
+/**
+ * Continue a trace from `sentry-trace` and `baggage` values.
+ * These values can be obtained from incoming request headers,
+ * or in the browser from `<meta name="sentry-trace">` and `<meta name="baggage">` HTML tags.
+ *
+ * It also takes an optional `request` option, which if provided will also be added to the scope & transaction metadata.
+ * The callback receives a transactionContext that may be used for `startTransaction` or `startSpan`.
+ */
+export function continueTrace<V>(
+  {
+    sentryTrace,
+    baggage,
+  }: {
+    sentryTrace: Parameters<typeof tracingContextFromHeaders>[0];
+    baggage: Parameters<typeof tracingContextFromHeaders>[1];
+  },
+  callback: (transactionContext: Partial<TransactionContext>) => V,
+): V {
+  const hub = getCurrentHub();
+  const currentScope = hub.getScope();
+
+  const { traceparentData, dynamicSamplingContext, propagationContext } = tracingContextFromHeaders(
+    sentryTrace,
+    baggage,
+  );
+
+  currentScope.setPropagationContext(propagationContext);
+
+  if (__DEBUG_BUILD__ && traceparentData) {
+    logger.log(`[Tracing] Continuing trace ${traceparentData.traceId}.`);
+  }
+
+  const transactionContext: Partial<TransactionContext> = {
+    ...traceparentData,
+    metadata: dropUndefinedKeys({
+      dynamicSamplingContext: traceparentData && !dynamicSamplingContext ? {} : dynamicSamplingContext,
+    }),
+  };
+
+  return callback(transactionContext);
+}
+
 function createChildSpanOrTransaction(
   hub: Hub,
   parentSpan: Span | undefined,

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

@@ -1,5 +1,5 @@
 import { addTracingExtensions, Hub, makeMain } from '../../../src';
-import { startSpan } from '../../../src/tracing';
+import { continueTrace, startSpan } from '../../../src/tracing';
 import { getDefaultTestClientOptions, TestClient } from '../../mocks/client';
 
 beforeAll(() => {
@@ -170,3 +170,154 @@ describe('startSpan', () => {
     });
   });
 });
+
+describe('continueTrace', () => {
+  beforeEach(() => {
+    const options = getDefaultTestClientOptions({ tracesSampleRate: 0.0 });
+    client = new TestClient(options);
+    hub = new Hub(client);
+    makeMain(hub);
+  });
+
+  it('works without trace & baggage data', () => {
+    const expectedContext = {
+      metadata: {},
+    };
+
+    const result = continueTrace({ sentryTrace: undefined, baggage: undefined }, ctx => {
+      expect(ctx).toEqual(expectedContext);
+      return ctx;
+    });
+
+    expect(result).toEqual(expectedContext);
+
+    const scope = hub.getScope();
+
+    expect(scope.getPropagationContext()).toEqual({
+      sampled: undefined,
+      spanId: expect.any(String),
+      traceId: expect.any(String),
+    });
+
+    expect(scope['_sdkProcessingMetadata']).toEqual({});
+  });
+
+  it('works with trace data', () => {
+    const expectedContext = {
+      metadata: {
+        dynamicSamplingContext: {},
+      },
+      parentSampled: false,
+      parentSpanId: '1121201211212012',
+      traceId: '12312012123120121231201212312012',
+    };
+
+    const result = continueTrace(
+      {
+        sentryTrace: '12312012123120121231201212312012-1121201211212012-0',
+        baggage: undefined,
+      },
+      ctx => {
+        expect(ctx).toEqual(expectedContext);
+        return ctx;
+      },
+    );
+
+    expect(result).toEqual(expectedContext);
+
+    const scope = hub.getScope();
+
+    expect(scope.getPropagationContext()).toEqual({
+      sampled: false,
+      parentSpanId: '1121201211212012',
+      spanId: expect.any(String),
+      traceId: '12312012123120121231201212312012',
+    });
+
+    expect(scope['_sdkProcessingMetadata']).toEqual({});
+  });
+
+  it('works with trace & baggage data', () => {
+    const expectedContext = {
+      metadata: {
+        dynamicSamplingContext: {
+          environment: 'production',
+          version: '1.0',
+        },
+      },
+      parentSampled: true,
+      parentSpanId: '1121201211212012',
+      traceId: '12312012123120121231201212312012',
+    };
+
+    const result = continueTrace(
+      {
+        sentryTrace: '12312012123120121231201212312012-1121201211212012-1',
+        baggage: 'sentry-version=1.0,sentry-environment=production',
+      },
+      ctx => {
+        expect(ctx).toEqual(expectedContext);
+        return ctx;
+      },
+    );
+
+    expect(result).toEqual(expectedContext);
+
+    const scope = hub.getScope();
+
+    expect(scope.getPropagationContext()).toEqual({
+      dsc: {
+        environment: 'production',
+        version: '1.0',
+      },
+      sampled: true,
+      parentSpanId: '1121201211212012',
+      spanId: expect.any(String),
+      traceId: '12312012123120121231201212312012',
+    });
+
+    expect(scope['_sdkProcessingMetadata']).toEqual({});
+  });
+
+  it('works with trace & 3rd party baggage data', () => {
+    const expectedContext = {
+      metadata: {
+        dynamicSamplingContext: {
+          environment: 'production',
+          version: '1.0',
+        },
+      },
+      parentSampled: true,
+      parentSpanId: '1121201211212012',
+      traceId: '12312012123120121231201212312012',
+    };
+
+    const result = continueTrace(
+      {
+        sentryTrace: '12312012123120121231201212312012-1121201211212012-1',
+        baggage: 'sentry-version=1.0,sentry-environment=production,dogs=great,cats=boring',
+      },
+      ctx => {
+        expect(ctx).toEqual(expectedContext);
+        return ctx;
+      },
+    );
+
+    expect(result).toEqual(expectedContext);
+
+    const scope = hub.getScope();
+
+    expect(scope.getPropagationContext()).toEqual({
+      dsc: {
+        environment: 'production',
+        version: '1.0',
+      },
+      sampled: true,
+      parentSpanId: '1121201211212012',
+      spanId: expect.any(String),
+      traceId: '12312012123120121231201212312012',
+    });
+
+    expect(scope['_sdkProcessingMetadata']).toEqual({});
+  });
+});

packages/node/src/index.ts

@@ -61,6 +61,7 @@ export {
   startActiveSpan,
   startInactiveSpan,
   startSpanManual,
+  continueTrace,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';
 export { autoDiscoverNodePerformanceMonitoringIntegrations } from './tracing';

packages/serverless/src/index.ts

@@ -56,4 +56,5 @@ export {
   startActiveSpan,
   startInactiveSpan,
   startSpanManual,
+  continueTrace,
 } from '@sentry/node';

packages/sveltekit/src/server/index.ts

@@ -51,6 +51,7 @@ export {
   startActiveSpan,
   startInactiveSpan,
   startSpanManual,
+  continueTrace,
 } from '@sentry/node';
 
 // We can still leave this for the carrier init and type exports

packages/vercel-edge/src/index.ts

@@ -58,6 +58,7 @@ export {
   startSpan,
   startInactiveSpan,
   startSpanManual,
+  continueTrace,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';