feat(core): Allow to pass start/end timestamp for spans flexibly (#10060)

We allow the same formats as OpenTelemetry:

* `number` (we handle both seconds and milliseconds)
* `Date`
* `[seconds, nanoseconds]`

Author: mydea

packages/core/src/tracing/idletransaction.ts

@@ -1,13 +1,13 @@
 /* eslint-disable max-lines */
-import type { TransactionContext } from '@sentry/types';
+import type { SpanTimeInput, TransactionContext } from '@sentry/types';
 import { logger, timestampInSeconds } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
 import type { Hub } from '../hub';
+import { spanTimeInputToSeconds } from '../utils/spanUtils';
 import type { Span } from './span';
 import { SpanRecorder } from './span';
 import { Transaction } from './transaction';
-import { ensureTimestampInSeconds } from './utils';
 
 export const TRACING_DEFAULTS = {
   idleTimeout: 1000,
@@ -138,8 +138,8 @@ export class IdleTransaction extends Transaction {
   }
 
   /** {@inheritDoc} */
-  public end(endTimestamp: number = timestampInSeconds()): string | undefined {
-    const endTimestampInS = ensureTimestampInSeconds(endTimestamp);
+  public end(endTimestamp?: SpanTimeInput): string | undefined {
+    const endTimestampInS = spanTimeInputToSeconds(endTimestamp);
 
     this._finished = true;
     this.activities = {};
@@ -153,7 +153,7 @@ export class IdleTransaction extends Transaction {
         logger.log('[Tracing] finishing IdleTransaction', new Date(endTimestampInS * 1000).toISOString(), this.op);
 
       for (const callback of this._beforeFinishCallbacks) {
-        callback(this, endTimestamp);
+        callback(this, endTimestampInS);
       }
 
       this.spanRecorder.spans = this.spanRecorder.spans.filter((span: Span) => {

packages/core/src/tracing/span.ts

@@ -7,14 +7,14 @@ import type {
   SpanAttributes,
   SpanContext,
   SpanOrigin,
+  SpanTimeInput,
   TraceContext,
   Transaction,
 } from '@sentry/types';
 import { dropUndefinedKeys, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
-import { spanToTraceContext, spanToTraceHeader } from '../utils/spanUtils';
-import { ensureTimestampInSeconds } from './utils';
+import { spanTimeInputToSeconds, spanToTraceContext, spanToTraceHeader } from '../utils/spanUtils';
 
 /**
  * Keeps track of finished spans for a given transaction
@@ -300,7 +300,7 @@ export class Span implements SpanInterface {
   }
 
   /** @inheritdoc */
-  public end(endTimestamp?: number): void {
+  public end(endTimestamp?: SpanTimeInput): void {
     if (
       DEBUG_BUILD &&
       // Don't call this for transactions
@@ -313,8 +313,7 @@ export class Span implements SpanInterface {
       }
     }
 
-    this.endTimestamp =
-      typeof endTimestamp === 'number' ? ensureTimestampInSeconds(endTimestamp) : timestampInSeconds();
+    this.endTimestamp = spanTimeInputToSeconds(endTimestamp);
   }
 
   /**

packages/core/src/tracing/trace.ts

@@ -1,4 +1,4 @@
-import type { Span, TransactionContext } from '@sentry/types';
+import type { Span, SpanTimeInput, TransactionContext } from '@sentry/types';
 import { dropUndefinedKeys, logger, tracingContextFromHeaders } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
@@ -7,6 +7,12 @@ import type { Hub } from '../hub';
 import { getCurrentHub } from '../hub';
 import { handleCallbackErrors } from '../utils/handleCallbackErrors';
 import { hasTracingEnabled } from '../utils/hasTracingEnabled';
+import { spanTimeInputToSeconds } from '../utils/spanUtils';
+
+interface StartSpanOptions extends TransactionContext {
+  /** A manually specified start time for the created `Span` object. */
+  startTime?: SpanTimeInput;
+}
 
 /**
  * Wraps a function with a transaction/span and finishes the span after the function is done.
@@ -65,7 +71,7 @@ export function trace<T>(
  * or you didn't set `tracesSampleRate`, this function will not generate spans
  * and the `span` returned from the callback will be undefined.
  */
-export function startSpan<T>(context: TransactionContext, callback: (span: Span | undefined) => T): T {
+export function startSpan<T>(context: StartSpanOptions, callback: (span: Span | undefined) => T): T {
   const ctx = normalizeContext(context);
 
   return withScope(scope => {
@@ -105,7 +111,7 @@ export const startActiveSpan = startSpan;
  * and the `span` returned from the callback will be undefined.
  */
 export function startSpanManual<T>(
-  context: TransactionContext,
+  context: StartSpanOptions,
   callback: (span: Span | undefined, finish: () => void) => T,
 ): T {
   const ctx = normalizeContext(context);
@@ -143,17 +149,12 @@ export function startSpanManual<T>(
  * or you didn't set `tracesSampleRate` or `tracesSampler`, this function will not generate spans
  * and the `span` returned from the callback will be undefined.
  */
-export function startInactiveSpan(context: TransactionContext): Span | undefined {
+export function startInactiveSpan(context: StartSpanOptions): Span | undefined {
   if (!hasTracingEnabled()) {
     return undefined;
   }
 
-  const ctx = { ...context };
-  // If a name is set and a description is not, set the description to the name.
-  if (ctx.name !== undefined && ctx.description === undefined) {
-    ctx.description = ctx.name;
-  }
-
+  const ctx = normalizeContext(context);
   const hub = getCurrentHub();
   const parentSpan = getActiveSpan();
   return parentSpan ? parentSpan.startChild(ctx) : hub.startTransaction(ctx);
@@ -238,12 +239,24 @@ function createChildSpanOrTransaction(
   return parentSpan ? parentSpan.startChild(ctx) : hub.startTransaction(ctx);
 }
 
-function normalizeContext(context: TransactionContext): TransactionContext {
+/**
+ * This converts StartSpanOptions to TransactionContext.
+ * For the most part (for now) we accept the same options,
+ * but some of them need to be transformed.
+ *
+ * Eventually the StartSpanOptions will be more aligned with OpenTelemetry.
+ */
+function normalizeContext(context: StartSpanOptions): TransactionContext {
   const ctx = { ...context };
   // If a name is set and a description is not, set the description to the name.
   if (ctx.name !== undefined && ctx.description === undefined) {
     ctx.description = ctx.name;
   }
 
+  if (context.startTime) {
+    ctx.startTimestamp = spanTimeInputToSeconds(context.startTime);
+    delete ctx.startTime;
+  }
+
   return ctx;
 }

packages/core/src/tracing/transaction.ts

@@ -4,20 +4,20 @@ import type {
   DynamicSamplingContext,
   MeasurementUnit,
   Measurements,
+  SpanTimeInput,
   Transaction as TransactionInterface,
   TransactionContext,
   TransactionEvent,
   TransactionMetadata,
 } from '@sentry/types';
-import { dropUndefinedKeys, logger, timestampInSeconds } from '@sentry/utils';
+import { dropUndefinedKeys, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
 import type { Hub } from '../hub';
 import { getCurrentHub } from '../hub';
-import { spanToTraceContext } from '../utils/spanUtils';
+import { spanTimeInputToSeconds, spanToTraceContext } from '../utils/spanUtils';
 import { getDynamicSamplingContextFromClient } from './dynamicSamplingContext';
 import { Span as SpanClass, SpanRecorder } from './span';
-import { ensureTimestampInSeconds } from './utils';
 
 /** JSDoc */
 export class Transaction extends SpanClass implements TransactionInterface {
@@ -147,9 +147,8 @@ export class Transaction extends SpanClass implements TransactionInterface {
   /**
    * @inheritDoc
    */
-  public end(endTimestamp?: number): string | undefined {
-    const timestampInS =
-      typeof endTimestamp === 'number' ? ensureTimestampInSeconds(endTimestamp) : timestampInSeconds();
+  public end(endTimestamp?: SpanTimeInput): string | undefined {
+    const timestampInS = spanTimeInputToSeconds(endTimestamp);
     const transaction = this._finishTransaction(timestampInS);
     if (!transaction) {
       return undefined;

packages/core/src/tracing/utils.ts

@@ -27,11 +27,3 @@ export { stripUrlQueryAndFragment } from '@sentry/utils';
  * @deprecated Import this function from `@sentry/utils` instead
  */
 export const extractTraceparentData = _extractTraceparentData;
-
-/**
- * Converts a timestamp to second, if it was in milliseconds, or keeps it as second.
- */
-export function ensureTimestampInSeconds(timestamp: number): number {
-  const isMs = timestamp > 9999999999;
-  return isMs ? timestamp / 1000 : timestamp;
-}

packages/core/src/utils/spanUtils.ts

@@ -1,5 +1,5 @@
-import type { Span, TraceContext } from '@sentry/types';
-import { dropUndefinedKeys, generateSentryTraceHeader } from '@sentry/utils';
+import type { Span, SpanTimeInput, TraceContext } from '@sentry/types';
+import { dropUndefinedKeys, generateSentryTraceHeader, timestampInSeconds } from '@sentry/utils';
 
 /**
  * Convert a span to a trace context, which can be sent as the `trace` context in an event.
@@ -26,3 +26,31 @@ export function spanToTraceContext(span: Span): TraceContext {
 export function spanToTraceHeader(span: Span): string {
   return generateSentryTraceHeader(span.traceId, span.spanId, span.sampled);
 }
+
+/**
+ * Convert a span time input intp a timestamp in seconds.
+ */
+export function spanTimeInputToSeconds(input: SpanTimeInput | undefined): number {
+  if (typeof input === 'number') {
+    return ensureTimestampInSeconds(input);
+  }
+
+  if (Array.isArray(input)) {
+    // See {@link HrTime} for the array-based time format
+    return input[0] + input[1] / 1e9;
+  }
+
+  if (input instanceof Date) {
+    return ensureTimestampInSeconds(input.getTime());
+  }
+
+  return timestampInSeconds();
+}
+
+/**
+ * Converts a timestamp to second, if it was in milliseconds, or keeps it as second.
+ */
+function ensureTimestampInSeconds(timestamp: number): number {
+  const isMs = timestamp > 9999999999;
+  return isMs ? timestamp / 1000 : timestamp;
+}

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

@@ -1,3 +1,4 @@
+import { timestampInSeconds } from '@sentry/utils';
 import { Span } from '../../../src';
 
 describe('span', () => {
@@ -174,6 +175,40 @@ describe('span', () => {
     });
   });
 
+  describe('end', () => {
+    it('works without endTimestamp', () => {
+      const span = new Span();
+      const now = timestampInSeconds();
+      span.end();
+
+      expect(span.endTimestamp).toBeGreaterThanOrEqual(now);
+    });
+
+    it('works with endTimestamp in seconds', () => {
+      const span = new Span();
+      const timestamp = timestampInSeconds() - 1;
+      span.end(timestamp);
+
+      expect(span.endTimestamp).toEqual(timestamp);
+    });
+
+    it('works with endTimestamp in milliseconds', () => {
+      const span = new Span();
+      const timestamp = Date.now() - 1000;
+      span.end(timestamp);
+
+      expect(span.endTimestamp).toEqual(timestamp / 1000);
+    });
+
+    it('works with endTimestamp in array form', () => {
+      const span = new Span();
+      const seconds = Math.floor(timestampInSeconds() - 1);
+      span.end([seconds, 0]);
+
+      expect(span.endTimestamp).toEqual(seconds);
+    });
+  });
+
   // Ensure that attributes & data are merged together
   describe('_getData', () => {
     it('works without data & attributes', () => {

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

@@ -160,6 +160,14 @@ describe('startSpan', () => {
       expect(ref.spanRecorder.spans[1].status).toEqual(isError ? 'internal_error' : undefined);
     });
 
+    it('allows to pass a `startTime`', () => {
+      const start = startSpan({ name: 'outer', startTime: [1234, 0] }, span => {
+        return span?.startTimestamp;
+      });
+
+      expect(start).toEqual(1234);
+    });
+
     it('allows for span to be mutated', async () => {
       let ref: any = undefined;
       client.on('finishTransaction', transaction => {
@@ -222,6 +230,15 @@ describe('startSpanManual', () => {
     expect(getCurrentScope()).toBe(initialScope);
     expect(initialScope.getSpan()).toBe(undefined);
   });
+
+  it('allows to pass a `startTime`', () => {
+    const start = startSpanManual({ name: 'outer', startTime: [1234, 0] }, span => {
+      span?.end();
+      return span?.startTimestamp;
+    });
+
+    expect(start).toEqual(1234);
+  });
 });
 
 describe('startInactiveSpan', () => {
@@ -248,6 +265,11 @@ describe('startInactiveSpan', () => {
 
     expect(initialScope.getSpan()).toBeUndefined();
   });
+
+  it('allows to pass a `startTime`', () => {
+    const span = startInactiveSpan({ name: 'outer', startTime: [1234, 0] });
+    expect(span?.startTimestamp).toEqual(1234);
+  });
 });
 
 describe('continueTrace', () => {

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

@@ -1,5 +1,6 @@
-import { TRACEPARENT_REGEXP } from '@sentry/utils';
+import { TRACEPARENT_REGEXP, timestampInSeconds } from '@sentry/utils';
 import { Span, spanToTraceHeader } from '../../../src';
+import { spanTimeInputToSeconds } from '../../../src/utils/spanUtils';
 
 describe('spanToTraceHeader', () => {
   test('simple', () => {
@@ -11,3 +12,37 @@ describe('spanToTraceHeader', () => {
     expect(spanToTraceHeader(span)).toMatch(TRACEPARENT_REGEXP);
   });
 });
+
+describe('spanTimeInputToSeconds', () => {
+  it('works with undefined', () => {
+    const now = timestampInSeconds();
+    expect(spanTimeInputToSeconds(undefined)).toBeGreaterThanOrEqual(now);
+  });
+
+  it('works with a timestamp in seconds', () => {
+    const timestamp = timestampInSeconds();
+    expect(spanTimeInputToSeconds(timestamp)).toEqual(timestamp);
+  });
+
+  it('works with a timestamp in milliseconds', () => {
+    const timestamp = Date.now();
+    expect(spanTimeInputToSeconds(timestamp)).toEqual(timestamp / 1000);
+  });
+
+  it('works with a Date object', () => {
+    const timestamp = new Date();
+    expect(spanTimeInputToSeconds(timestamp)).toEqual(timestamp.getTime() / 1000);
+  });
+
+  it('works with a simple array', () => {
+    const seconds = Math.floor(timestampInSeconds());
+    const timestamp: [number, number] = [seconds, 0];
+    expect(spanTimeInputToSeconds(timestamp)).toEqual(seconds);
+  });
+
+  it('works with a array with nanoseconds', () => {
+    const seconds = Math.floor(timestampInSeconds());
+    const timestamp: [number, number] = [seconds, 9000];
+    expect(spanTimeInputToSeconds(timestamp)).toEqual(seconds + 0.000009);
+  });
+});

packages/types/src/index.ts

@@ -89,7 +89,7 @@ export type {
 
 // eslint-disable-next-line deprecation/deprecation
 export type { Severity, SeverityLevel } from './severity';
-export type { Span, SpanContext, SpanOrigin, SpanAttributeValue, SpanAttributes } from './span';
+export type { Span, SpanContext, SpanOrigin, SpanAttributeValue, SpanAttributes, SpanTimeInput } from './span';
 export type { StackFrame } from './stackframe';
 export type { Stacktrace, StackParser, StackLineParser, StackLineParserFn } from './stacktrace';
 export type { TextEncoderInternal } from './textencoder';