feat(browser): Start standalone (segment) spans via start*Span APIs

separate standalone and segment

tmp add test helper (no need after rebase)

add tests

Author: Lms24

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/init.js

@@ -0,0 +1,8 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  tracesSampleRate: 1.0,
+});

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/segment-false/subject.js

@@ -0,0 +1 @@
+Sentry.startSpan({ name: 'standalone_segment_span', experimental: { standalone: true, segment: false } }, () => {});

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/segment-false/test.ts

@@ -0,0 +1,47 @@
+import { expect } from '@playwright/test';
+import type { SpanEnvelope } from '@sentry/types';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import {
+  getFirstSentryEnvelopeRequest,
+  properFullEnvelopeRequestParser,
+  shouldSkipTracingTest,
+} from '../../../../../utils/helpers';
+
+sentryTest('sends a span envelope with is_segment: false', async ({ getLocalTestPath, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestPath({ testDir: __dirname });
+  const spanEnvelope = await getFirstSentryEnvelopeRequest<SpanEnvelope>(page, url, properFullEnvelopeRequestParser);
+
+  const headers = spanEnvelope[0];
+  const item = spanEnvelope[1][0];
+
+  const itemHeader = item[0];
+  const spanJson = item[1];
+
+  expect(headers).toMatchObject({
+    sent_at: expect.any(String),
+  });
+
+  expect(itemHeader).toEqual({
+    type: 'span',
+  });
+
+  expect(spanJson).toEqual({
+    data: {
+      'sentry.origin': 'manual',
+      'sentry.sample_rate': 1,
+      'sentry.source': 'custom',
+    },
+    description: 'standalone_segment_span',
+    origin: 'manual',
+    span_id: expect.stringMatching(/^[0-9a-f]{16}$/),
+    start_timestamp: expect.any(Number),
+    timestamp: expect.any(Number),
+    trace_id: expect.stringMatching(/^[0-9a-f]{32}$/),
+    is_segment: false,
+  });
+});

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/segment-true/subject.js

@@ -0,0 +1 @@
+Sentry.startSpan({ name: 'standalone_segment_span', experimental: { standalone: true, segment: true } }, () => {});

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/segment-true/test.ts

@@ -0,0 +1,48 @@
+import { expect } from '@playwright/test';
+import type { SpanEnvelope } from '@sentry/types';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import {
+  getFirstSentryEnvelopeRequest,
+  properFullEnvelopeRequestParser,
+  shouldSkipTracingTest,
+} from '../../../../../utils/helpers';
+
+sentryTest('sends a segment span envelope', async ({ getLocalTestPath, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestPath({ testDir: __dirname });
+  const spanEnvelope = await getFirstSentryEnvelopeRequest<SpanEnvelope>(page, url, properFullEnvelopeRequestParser);
+
+  const headers = spanEnvelope[0];
+  const item = spanEnvelope[1][0];
+
+  const itemHeader = item[0];
+  const spanJson = item[1];
+
+  expect(headers).toMatchObject({
+    sent_at: expect.any(String),
+  });
+
+  expect(itemHeader).toEqual({
+    type: 'span',
+  });
+
+  expect(spanJson).toEqual({
+    data: {
+      'sentry.origin': 'manual',
+      'sentry.sample_rate': 1,
+      'sentry.source': 'custom',
+    },
+    description: 'standalone_segment_span',
+    origin: 'manual',
+    span_id: expect.stringMatching(/^[0-9a-f]{16}$/),
+    start_timestamp: expect.any(Number),
+    timestamp: expect.any(Number),
+    trace_id: expect.stringMatching(/^[0-9a-f]{32}$/),
+    is_segment: true,
+    segment_id: spanJson.span_id,
+  });
+});

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/segment-undefined/subject.js

@@ -0,0 +1 @@
+Sentry.startSpan({ name: 'standalone_segment_span', experimental: { standalone: true } }, () => {});

dev-packages/browser-integration-tests/suites/public-api/startSpan/standalone/segment-undefined/test.ts

@@ -0,0 +1,46 @@
+import { expect } from '@playwright/test';
+import type { SpanEnvelope } from '@sentry/types';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import {
+  getFirstSentryEnvelopeRequest,
+  properFullEnvelopeRequestParser,
+  shouldSkipTracingTest,
+} from '../../../../../utils/helpers';
+
+sentryTest('sends a segment-less span envelope', async ({ getLocalTestPath, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestPath({ testDir: __dirname });
+  const spanEnvelope = await getFirstSentryEnvelopeRequest<SpanEnvelope>(page, url, properFullEnvelopeRequestParser);
+
+  const headers = spanEnvelope[0];
+  const item = spanEnvelope[1][0];
+
+  const itemHeader = item[0];
+  const spanJson = item[1];
+
+  expect(headers).toMatchObject({
+    sent_at: expect.any(String),
+  });
+
+  expect(itemHeader).toEqual({
+    type: 'span',
+  });
+
+  expect(spanJson).toEqual({
+    data: {
+      'sentry.origin': 'manual',
+      'sentry.sample_rate': 1,
+      'sentry.source': 'custom',
+    },
+    description: 'standalone_segment_span',
+    origin: 'manual',
+    span_id: expect.stringMatching(/^[0-9a-f]{16}$/),
+    start_timestamp: expect.any(Number),
+    timestamp: expect.any(Number),
+    trace_id: expect.stringMatching(/^[0-9a-f]{32}$/),
+  });
+});

dev-packages/browser-integration-tests/utils/helpers.ts

@@ -1,5 +1,5 @@
 import type { Page, Request } from '@playwright/test';
-import type { EnvelopeItem, EnvelopeItemType, Event, EventEnvelopeHeaders } from '@sentry/types';
+import type { Envelope, EnvelopeItem, EnvelopeItemType, Event, EventEnvelopeHeaders } from '@sentry/types';
 import { parseEnvelope } from '@sentry/utils';
 
 export const envelopeUrlRegex = /\.sentry\.io\/api\/\d+\/envelope\//;
@@ -43,6 +43,13 @@ export const properEnvelopeRequestParser = <T = Event>(request: Request | null,
   return properEnvelopeParser(request)[0][envelopeIndex] as T;
 };
 
+export const properFullEnvelopeRequestParser = <T extends Envelope>(request: Request | null): T => {
+  // https://develop.sentry.dev/sdk/envelopes/
+  const envelope = request?.postData() || '';
+
+  return parseEnvelope(envelope) as T;
+};
+
 export const envelopeHeaderRequestParser = (request: Request | null): EventEnvelopeHeaders => {
   // https://develop.sentry.dev/sdk/envelopes/
   const envelope = request?.postData() || '';

packages/core/src/tracing/sentrySpan.ts

@@ -4,6 +4,7 @@ import type {
   SpanAttributeValue,
   SpanAttributes,
   SpanContextData,
+  SpanEnvelope,
   SpanJSON,
   SpanOrigin,
   SpanStatus,
@@ -16,6 +17,7 @@ import { dropUndefinedKeys, logger, timestampInSeconds, uuid4 } from '@sentry/ut
 import { getClient, getCurrentScope } from '../currentScopes';
 import { DEBUG_BUILD } from '../debug-build';
 
+import { createSpanEnvelope } from '../envelope';
 import { getMetricSummaryJsonForSpan } from '../metrics/metric-summary';
 import {
   SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME,
@@ -58,6 +60,12 @@ export class SentrySpan implements Span {
   /** The timed events added to this span. */
   protected _events: TimedEvent[];
 
+  /** if true, treat span as a standalone span (not part of a transaction) */
+  private _isStandaloneSpan?: boolean;
+
+  /** send standalone span as segment span */
+  private _isSegmentSpan?: boolean;
+
   /**
    * You should never call the constructor manually, always use `Sentry.startSpan()`
    * or other span methods.
@@ -96,6 +104,9 @@ export class SentrySpan implements Span {
     if (this._endTime) {
       this._onSpanEnded();
     }
+
+    this._isStandaloneSpan = spanContext.isStandalone;
+    this._isSegmentSpan = spanContext.isStandalone && spanContext.isSegment;
   }
 
   /** @inheritdoc */
@@ -188,6 +199,8 @@ export class SentrySpan implements Span {
       profile_id: this._attributes[SEMANTIC_ATTRIBUTE_PROFILE_ID] as string | undefined,
       exclusive_time: this._attributes[SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME] as number | undefined,
       measurements: timedEventsToMeasurements(this._events),
+      is_segment: !this._isStandaloneSpan ? undefined : this._isSegmentSpan,
+      segment_id: this._isStandaloneSpan && this._isSegmentSpan ? this._spanId : undefined,
     });
   }
 
@@ -227,13 +240,20 @@ export class SentrySpan implements Span {
       client.emit('spanEnd', this);
     }
 
-    // If this is a root span, send it when it is endedf
-    if (this === getRootSpan(this)) {
-      const transactionEvent = this._convertSpanToTransaction();
-      if (transactionEvent) {
-        const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
-        scope.captureEvent(transactionEvent);
-      }
+    // If this is not a root span, we're done, otherwise, we send it when it is ended
+    if (this !== getRootSpan(this)) {
+      return;
+    }
+
+    if (this._isStandaloneSpan) {
+      sendSpanEnvelope(createSpanEnvelope([this]));
+      return;
+    }
+
+    const transactionEvent = this._convertSpanToTransaction();
+    if (transactionEvent) {
+      const scope = getCapturedScopesOnSpan(this).scope || getCurrentScope();
+      scope.captureEvent(transactionEvent);
     }
   }
 
@@ -318,3 +338,17 @@ function isSpanTimeInput(value: undefined | SpanAttributes | SpanTimeInput): val
 function isFullFinishedSpan(input: Partial<SpanJSON>): input is SpanJSON {
   return !!input.start_timestamp && !!input.timestamp && !!input.span_id && !!input.trace_id;
 }
+
+function sendSpanEnvelope(envelope: SpanEnvelope): void {
+  const client = getClient();
+  if (!client) {
+    return;
+  }
+
+  const transport = client.getTransport();
+  if (transport) {
+    transport.send(envelope).then(null, reason => {
+      DEBUG_BUILD && logger.error('Error while sending span:', reason);
+    });
+  }
+}

packages/core/src/tracing/trace.ts

@@ -45,7 +45,7 @@ export function startSpan<T>(context: StartSpanOptions, callback: (span: Span) =
     const shouldSkipSpan = context.onlyIfParent && !parentSpan;
     const activeSpan = shouldSkipSpan
       ? new SentryNonRecordingSpan()
-      : createChildSpanOrTransaction({
+      : createChildOrRootSpan({
           parentSpan,
           spanContext,
           forceTransaction: context.forceTransaction,
@@ -92,7 +92,7 @@ export function startSpanManual<T>(context: StartSpanOptions, callback: (span: S
     const shouldSkipSpan = context.onlyIfParent && !parentSpan;
     const activeSpan = shouldSkipSpan
       ? new SentryNonRecordingSpan()
-      : createChildSpanOrTransaction({
+      : createChildOrRootSpan({
           parentSpan,
           spanContext,
           forceTransaction: context.forceTransaction,
@@ -144,7 +144,7 @@ export function startInactiveSpan(context: StartSpanOptions): Span {
     return new SentryNonRecordingSpan();
   }
 
-  return createChildSpanOrTransaction({
+  return createChildOrRootSpan({
     parentSpan,
     spanContext,
     forceTransaction: context.forceTransaction,
@@ -212,7 +212,7 @@ export function suppressTracing<T>(callback: () => T): T {
   });
 }
 
-function createChildSpanOrTransaction({
+function createChildOrRootSpan({
   parentSpan,
   spanContext,
   forceTransaction,
@@ -291,14 +291,21 @@ function createChildSpanOrTransaction({
  * Eventually the StartSpanOptions will be more aligned with OpenTelemetry.
  */
 function normalizeContext(context: StartSpanOptions): SentrySpanArguments {
+  const exp = context.experimental || {};
+  const initialCtx: SentrySpanArguments = {
+    isStandalone: exp.standalone,
+    isSegment: exp.standalone && exp.segment,
+    ...context,
+  };
+
   if (context.startTime) {
-    const ctx: SentrySpanArguments & { startTime?: SpanTimeInput } = { ...context };
+    const ctx: SentrySpanArguments & { startTime?: SpanTimeInput } = { ...initialCtx };
     ctx.startTimestamp = spanTimeInputToSeconds(context.startTime);
     delete ctx.startTime;
     return ctx;
   }
 
-  return context;
+  return initialCtx;
 }
 
 function getAcs(): AsyncContextStrategy {