fix(effect): Convert Effect span times to the Sentry clock

Effect timestamps come from its own clock, a fixed origin plus a monotonic
clock, which does not correct for clock drift (e.g. after the device slept).
Sentry now does, so Effect spans could end up offset from the Sentry spans
around them. Start Effect spans on the Sentry clock and convert end and event
times by their offset from the span start. This keeps Effect durations and
explicitly passed end times. If tracer timing is disabled, Effect passes 0 and
we use the Sentry clock instead of producing 1970 timestamps.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Lms24

packages/effect/src/tracer.ts

@@ -10,6 +10,7 @@ import {
   getDefaultCurrentScope,
   isObjectLike,
   startNewTrace,
+  timestampInSeconds,
   withActiveSpan,
   withScope,
 } from '@sentry/core';
@@ -61,16 +62,8 @@ function deriveOp(name: string): string | undefined {
   return undefined;
 }
 
-type HrTime = [number, number];
-
 const SENTRY_SPAN_SYMBOL = Symbol.for('@sentry/effect.SentrySpan');
 
-function nanosToHrTime(nanos: bigint): HrTime {
-  const seconds = Number(nanos / BigInt(1_000_000_000));
-  const remainingNanos = Number(nanos % BigInt(1_000_000_000));
-  return [seconds, remainingNanos];
-}
-
 interface SentrySpanLike extends EffectTracer.Span {
   readonly [SENTRY_SPAN_SYMBOL]: true;
   readonly sentrySpan: Span;
@@ -127,6 +120,7 @@ class SentrySpanWrapper implements SentrySpanLike {
   public status: EffectTracer.SpanStatus;
   public readonly sentrySpan: Span;
   public readonly annotations: Context.Context<never>;
+  private readonly _sentryStartTime: number;
 
   public constructor(
     public readonly name: string,
@@ -136,6 +130,7 @@ class SentrySpanWrapper implements SentrySpanLike {
     startTime: bigint,
     public readonly kind: EffectTracer.SpanKind,
     existingSpan: Span,
+    sentryStartTime: number,
   ) {
     this[SENTRY_SPAN_SYMBOL] = true as const;
     this._tag = 'Span' as const;
@@ -144,6 +139,7 @@ class SentrySpanWrapper implements SentrySpanLike {
     this.links = [...links];
     this.sentrySpan = existingSpan;
     this.annotations = context;
+    this._sentryStartTime = sentryStartTime;
 
     const spanContext = this.sentrySpan.spanContext();
     this.spanId = spanContext.spanId;
@@ -187,15 +183,31 @@ class SentrySpanWrapper implements SentrySpanLike {
       this.sentrySpan.setStatus({ code: 1 });
     }
 
-    this.sentrySpan.end(nanosToHrTime(endTime));
+    this.sentrySpan.end(this._toSentryTime(endTime));
   }
 
   public event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
     if (!this.sentrySpan.isRecording()) {
       return;
     }
 
-    this.sentrySpan.addEvent(name, attributes as Parameters<Span['addEvent']>[1], nanosToHrTime(startTime));
+    this.sentrySpan.addEvent(name, attributes as Parameters<Span['addEvent']>[1], this._toSentryTime(startTime));
+  }
+
+  /**
+   * Converts an Effect time to Sentry's clock by adding its offset from the span's start.
+   *
+   * Effect's clock doesn't correct for clock drift (e.g. after the device slept), so its absolute times can be off
+   * from the Sentry spans around this one. Its durations are still correct, and this way we also respect end times
+   * that were passed explicitly.
+   */
+  private _toSentryTime(effectTime: bigint): number | undefined {
+    // Effect passes 0 if tracer timing is disabled. Sentry then takes the current time.
+    if (!effectTime || !this.status.startTime) {
+      return undefined;
+    }
+
+    return this._sentryStartTime + Number(effectTime - this.status.startTime) / 1e9;
   }
 }
 
@@ -381,11 +393,14 @@ function createSentrySpan(
   const op = deriveOp(name);
   const origin = deriveOrigin(name);
 
+  // Effect calls the tracer when the span starts, so we start it on Sentry's clock and convert later Effect times
+  // relative to this (see `_toSentryTime`).
+  const sentryStartTime = timestampInSeconds();
   const newSpan = startSentrySpan(
     startInactiveSpan,
     {
       name,
-      startTime: nanosToHrTime(startTime),
+      startTime: sentryStartTime,
       // Setting these to `undefined` would strip the core defaults instead of leaving them in place.
       attributes: {
         ...(op && { [SENTRY_OP]: op }),
@@ -397,7 +412,7 @@ function createSentrySpan(
   );
   markEffectSpan(newSpan);
 
-  return new SentrySpanWrapper(name, parent, context, links, startTime, kind, newSpan);
+  return new SentrySpanWrapper(name, parent, context, links, startTime, kind, newSpan, sentryStartTime);
 }
 
 const makeSentryTracerV3 = (

packages/effect/test/tracer.test.ts

@@ -3,7 +3,8 @@ import { describe, expect, it } from '@effect/vitest';
 import * as sentryCore from '@sentry/core';
 import * as sentryCoreBrowser from '@sentry/core/browser';
 import { ServerRuntimeClient } from '@sentry/core/server';
-import { Effect } from 'effect';
+import { Effect, Exit } from 'effect';
+import { TestClock } from 'effect/testing';
 import * as Tracer from 'effect/Tracer';
 import { afterEach, beforeEach, vi } from 'vitest';
 import { SentryEffectTracer as clientTracer } from '../src/client/tracer';
@@ -197,6 +198,40 @@ describe.each(VARIANTS)('SentryEffectTracer ($variant)', ({ variant, tracer, spa
 
   // A name we cannot map belongs to user code or a third-party library. Leaving op and origin unset
   // keeps the core defaults (no op, `manual` origin) rather than claiming we instrumented the span.
+  it.effect("starts spans on Sentry's clock and keeps Effect's duration for an explicit end time", () =>
+    Effect.gen(function* () {
+      const end = vi.fn();
+      const addEvent = vi.fn();
+      let sentryStartTime: number | undefined;
+      vi.spyOn(spanApi, 'startInactiveSpan').mockImplementation(options => {
+        sentryStartTime = options.startTime as number;
+        return mockSpan({ end, addEvent });
+      });
+
+      // `it.effect` runs on Effect's `TestClock`, which is far from the wall clock.
+      yield* TestClock.adjust('1 hour');
+      const span = yield* Effect.makeSpan('manual-span');
+      span.event('my-event', span.status.startTime + BigInt(1_000_000_000));
+      span.end(span.status.startTime + BigInt(2_500_000_000), Exit.void);
+
+      expect(sentryStartTime).toBeCloseTo(Date.now() / 1000, 0);
+      expect(addEvent).toHaveBeenCalledWith('my-event', undefined, sentryStartTime! + 1);
+      expect(end).toHaveBeenCalledWith(sentryStartTime! + 2.5);
+    }).pipe(withSentryTracer),
+  );
+
+  it.effect("uses Sentry's clock for the end time if Effect's tracer timing is disabled", () =>
+    Effect.gen(function* () {
+      const end = vi.fn();
+      vi.spyOn(spanApi, 'startInactiveSpan').mockImplementation(() => mockSpan({ end }));
+
+      yield* TestClock.adjust('1 hour');
+      yield* Effect.withSpan('untimed-span')(Effect.succeed('ok')).pipe(Effect.withTracerTiming(false));
+
+      expect(end).toHaveBeenCalledWith(undefined);
+    }).pipe(withSentryTracer),
+  );
+
   it.effect('leaves origin and op unset for spans it cannot map', () =>
     Effect.gen(function* () {
       const attributes = yield* attributesFor('my-operation');