feat(core): Deprecate span.toTraceparent() in favor of spanToTraceHeader() util (#10031)

Instead, there is a new util `spanToTraceHeader(span)` which can be
used. This is done to align the Span schema with OpenTelemetry.

Open question: Do we need to re-export this from all our packages, so
users can also use this directly?

Author: mydea

MIGRATION.md

@@ -15,6 +15,7 @@ In v8, the Span class is heavily reworked. The following properties & methods ar
 * `span.toContext()`: Access the fields directly instead.
 * `span.updateWithContext(newSpanContext)`: Update the fields directly instead.
 * `span.setName(newName)`: Use `span.updateName(newName)` instead.
+* `span.toTraceparent()`: use `spanToTraceHeader(span)` util instead.
 
 ## Deprecate `pushScope` & `popScope` in favor of `withScope`
 

packages/astro/src/server/meta.ts

@@ -1,4 +1,4 @@
-import { getDynamicSamplingContextFromClient } from '@sentry/core';
+import { getDynamicSamplingContextFromClient, spanToTraceHeader } from '@sentry/core';
 import type { Client, Scope, Span } from '@sentry/types';
 import {
   TRACEPARENT_REGEXP,
@@ -30,7 +30,7 @@ export function getTracingMetaTags(
   const { dsc, sampled, traceId } = scope.getPropagationContext();
   const transaction = span?.transaction;
 
-  const sentryTrace = span ? span.toTraceparent() : generateSentryTraceHeader(traceId, undefined, sampled);
+  const sentryTrace = span ? spanToTraceHeader(span) : generateSentryTraceHeader(traceId, undefined, sampled);
 
   const dynamicSamplingContext = transaction
     ? transaction.getDynamicSamplingContext()

packages/astro/test/server/meta.test.ts

@@ -4,7 +4,9 @@ import { vi } from 'vitest';
 import { getTracingMetaTags, isValidBaggageString } from '../../src/server/meta';
 
 const mockedSpan = {
-  toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1',
+  sampled: true,
+  traceId: '12345678901234567890123456789012',
+  spanId: '1234567890123456',
   transaction: {
     getDynamicSamplingContext: () => ({
       environment: 'production',
@@ -68,7 +70,9 @@ describe('getTracingMetaTags', () => {
     const tags = getTracingMetaTags(
       // @ts-expect-error - only passing a partial span object
       {
-        toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1',
+        sampled: true,
+        traceId: '12345678901234567890123456789012',
+        spanId: '1234567890123456',
         transaction: undefined,
       },
       mockedScope,
@@ -89,7 +93,9 @@ describe('getTracingMetaTags', () => {
     const tags = getTracingMetaTags(
       // @ts-expect-error - only passing a partial span object
       {
-        toTraceparent: () => '12345678901234567890123456789012-1234567890123456-1',
+        sampled: true,
+        traceId: '12345678901234567890123456789012',
+        spanId: '1234567890123456',
         transaction: undefined,
       },
       mockedScope,

packages/core/src/index.ts

@@ -69,6 +69,7 @@ export { prepareEvent } from './utils/prepareEvent';
 export { createCheckInEnvelope } from './checkin';
 export { hasTracingEnabled } from './utils/hasTracingEnabled';
 export { isSentryRequestUrl } from './utils/isSentryRequestUrl';
+export { spanToTraceHeader } from './utils/spanUtils';
 export { DEFAULT_ENVIRONMENT } from './constants';
 export { ModuleMetadata } from './integrations/metadata';
 export { RequestData } from './integrations/requestdata';

packages/core/src/tracing/hubextensions.ts

@@ -4,6 +4,7 @@ import { logger } from '@sentry/utils';
 import { DEBUG_BUILD } from '../debug-build';
 import type { Hub } from '../hub';
 import { getMainCarrier } from '../hub';
+import { spanToTraceHeader } from '../utils/spanUtils';
 import { registerErrorInstrumentation } from './errors';
 import { IdleTransaction } from './idletransaction';
 import { sampleTransaction } from './sampling';
@@ -16,7 +17,7 @@ function traceHeaders(this: Hub): { [key: string]: string } {
 
   return span
     ? {
-        'sentry-trace': span.toTraceparent(),
+        'sentry-trace': spanToTraceHeader(span),
       }
     : {};
 }

packages/core/src/tracing/span.ts

@@ -10,9 +10,10 @@ import type {
   TraceContext,
   Transaction,
 } from '@sentry/types';
-import { dropUndefinedKeys, generateSentryTraceHeader, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
+import { dropUndefinedKeys, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
+import { spanToTraceHeader } from '../utils/spanUtils';
 import { ensureTimestampInSeconds } from './utils';
 
 /**
@@ -320,7 +321,7 @@ export class Span implements SpanInterface {
    * @inheritDoc
    */
   public toTraceparent(): string {
-    return generateSentryTraceHeader(this.traceId, this.spanId, this.sampled);
+    return spanToTraceHeader(this);
   }
 
   /**

packages/core/src/utils/spanUtils.ts

@@ -0,0 +1,9 @@
+import type { Span } from '@sentry/types';
+import { generateSentryTraceHeader } from '@sentry/utils';
+
+/**
+ * Convert a Span to a Sentry trace header.
+ */
+export function spanToTraceHeader(span: Span): string {
+  return generateSentryTraceHeader(span.traceId, span.spanId, span.sampled);
+}

packages/core/test/lib/utils/spanUtils.test.ts

@@ -0,0 +1,13 @@
+import { TRACEPARENT_REGEXP } from '@sentry/utils';
+import { Span, spanToTraceHeader } from '../../../src';
+
+describe('spanToTraceHeader', () => {
+  test('simple', () => {
+    const span = new Span();
+    expect(spanToTraceHeader(span)).toMatch(TRACEPARENT_REGEXP);
+  });
+  test('with sample', () => {
+    const span = new Span({ sampled: true });
+    expect(spanToTraceHeader(span)).toMatch(TRACEPARENT_REGEXP);
+  });
+});

packages/nextjs/src/common/wrapAppGetInitialPropsWithSentry.ts

@@ -1,4 +1,4 @@
-import { addTracingExtensions, getClient, getCurrentScope } from '@sentry/core';
+import { addTracingExtensions, getClient, getCurrentScope, spanToTraceHeader } from '@sentry/core';
 import { dynamicSamplingContextToSentryBaggageHeader } from '@sentry/utils';
 import type App from 'next/app';
 
@@ -63,7 +63,7 @@ export function wrapAppGetInitialPropsWithSentry(origAppGetInitialProps: AppGetI
         }
 
         if (requestTransaction) {
-          appGetInitialProps.pageProps._sentryTraceData = requestTransaction.toTraceparent();
+          appGetInitialProps.pageProps._sentryTraceData = spanToTraceHeader(requestTransaction);
 
           const dynamicSamplingContext = requestTransaction.getDynamicSamplingContext();
           appGetInitialProps.pageProps._sentryBaggage =

packages/nextjs/src/common/wrapErrorGetInitialPropsWithSentry.ts

@@ -1,4 +1,4 @@
-import { addTracingExtensions, getClient, getCurrentScope } from '@sentry/core';
+import { addTracingExtensions, getClient, getCurrentScope, spanToTraceHeader } from '@sentry/core';
 import { dynamicSamplingContextToSentryBaggageHeader } from '@sentry/utils';
 import type { NextPageContext } from 'next';
 import type { ErrorProps } from 'next/error';
@@ -55,7 +55,7 @@ export function wrapErrorGetInitialPropsWithSentry(
 
         const requestTransaction = getTransactionFromRequest(req) ?? getCurrentScope().getTransaction();
         if (requestTransaction) {
-          errorGetInitialProps._sentryTraceData = requestTransaction.toTraceparent();
+          errorGetInitialProps._sentryTraceData = spanToTraceHeader(requestTransaction);
 
           const dynamicSamplingContext = requestTransaction.getDynamicSamplingContext();
           errorGetInitialProps._sentryBaggage = dynamicSamplingContextToSentryBaggageHeader(dynamicSamplingContext);