fix(core): Correct sleep clock drift on telemetry timestamps (#23054)

This PR fixes* clock drift that occurs when devices go to sleep. After
devices sleep for a few seconds, the browser's monotonic clock (accessed
via `performance.now()`) stops counting. Once the sleep stops, the
monotonic clock resumes right where it left off before the sleep,
causing significant discrepancies between the actual time (wall clock)
and the browser's monotonic clock time. Or in other words, there are two
ways to get an absolute timestamp:

- Using the monotonic clock via `peformance.timeOrigin +
performance.now()` - has high, sub-millisecond precision and a guarantee
that there are no time jumps or adjustments. But suffers from the sleep
problem described above
- Using the wall clock via `Date.now()` - lower millisecond precision,
is known to be corrected (NTP or via users) and can even cause back
jumps. But no sleep problem.

With this fix, we make the following adjustments, to kinda get the best
of both worlds:

- Every `timestampInSecondsCall` checks the monotonic against the wall
clock. If a threshold of difference is enocuntered, it corrects the
`timeOrigin` so that we can keep using the precise monotonic clock, but
anchor its relative time to a corrected time origin.
- On every time origin correction, we remember the previous origin (up
to 30 corrections). Needed for performance entries
- Makes `browserPerformanceTimeOrigin` a time origin corrected helper
function, where you pass in a relative time that comes from monotonic
clock relative timestamps and it returns the time origin that was most
accurate at that relative time point.
- All spans and other telemetry we create from browsers
`PerformanceEntry` objects carry relative times which are completely
sleep-drift uncorrected. We use `browserPerformanceTimeOrigin` to return
a corrected time stamp so that we can create an absolute timestamp and
bring the performance entries to their respective actual time.

### FAQ

If you think this sounds complicated, I agree. So let me answer the most
obvious questions, because I asked myself these a lot, too:

**Why not just always use `Date.now()` and avoid the complicated click
drift detection and correction logic?**

The main issue with this is that we still need to rely on relative
monotonic clock timestamps for performance entries. We cannot correct
them just with `Date.now()` alone but we still need to anchor them. So
either we rely on the original `window.timeOrigin` and therefore have
all performance entry telemetry happen much "earlier" than its
surrounding telemetry relying on `Date.now()`, or we keep the time
origin correction logic. But even in the second case (where we already
pay the tax for drift detection and correction), telemetry would still
have two different anchors: `Date.now()` for regular telemetry and the
corrected time origin + monotonic time for performance entry telemetry.

Another reason is that the monotonic clock gives us sun-millisecond
precision while the wall clock stops at a millisecond resolution.

**Why the reduction from a drift detection threshold of 5 minutes to
just one second?**

Because we keep everything centered around detection and origin offset
correction, these timestamps need to be as accurate as possible. On
phones, short frequent sleeps are very likely to happen. A lot of sleeps
can accumulate until that 5 minutes threshold is reached. So it's really
important we make these timestamps as accurate as possible.

Fwiw, I reproduced this locally and the drift is already noticeable
after just a few seconds of sleep. The 5 minutes threshold was arguably
far too big beforehand.


**Is there precedence for all of this stuff?**

Somewhat, but I'd argue we're doing a bit more: OTel uses a mixture of
`Date.now()` and `performance.now`:
- Spans start at `Date.now()` and at start time, they record a
`performance.now()` timestamp. On span end, they also take
`performance.now()`, compute the diff and convert that to an end
timestamp based on the start timestamp + diff. This is neat because it
guarantees monotony in span durations. I stole this in #24903

In other places, OTel relies purely on Date.now(), and for performance
entries, they simply take uncorrected timestamps. So our fix is more
complete.

\* **So... we're good now?**

Well, not perfectly and we never will. With this choice we make another
commitment (which we already did previously in less obvious cases) to
`Date.now()`. This value can drift as well, just not for sleeps:

- NTP adjustments: Can make hard correction of the wall clock, or make
the clock tick just a bit faster or slower until the device wall clock
synced with the network time.
- User adjustments: Users can adjust the device time at any time into
any direction.

I think we'll have to live with both and I'm not particularly worried
about them. My main objective is getting rid of the sleep drift.

Fixes #2590
Supersedes #22488, #22585, #23067, #23068

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Lms24

packages/browser-utils/src/performance/entries.ts

@@ -2,9 +2,9 @@
 import type { Span, SpanAttributes } from '@sentry/core';
 import {
   BROWSER_NAVIGATION_TIMING_SPAN_NAMES,
-  browserPerformanceTimeOrigin,
   getActiveSpan,
   parseUrl,
+  _INTERNAL_performanceTimeToSeconds,
   RESOURCE_SPAN_NAME_FALLBACK,
   setMeasurement,
   spanToJSON,
@@ -108,7 +108,10 @@ export function startTrackingLongTasks(): void {
     const { attributes: parentAttributes, start_timestamp: parentStartTimestamp } = spanToJSON(parent);
 
     for (const entry of entries) {
-      const startTime = msToSec((browserPerformanceTimeOrigin() as number) + entry.startTime);
+      const startTime = _INTERNAL_performanceTimeToSeconds(entry.startTime);
+      if (!startTime) {
+        continue;
+      }
       const duration = msToSec(entry.duration);
 
       if (parentAttributes[SENTRY_OP] === 'navigation' && parentStartTimestamp && startTime < parentStartTimestamp) {
@@ -143,12 +146,11 @@ export function startTrackingLongAnimationFrames(): void {
       return;
     }
     for (const entry of list.getEntries() as PerformanceLongAnimationFrameTiming[]) {
-      if (!entry.scripts[0]) {
+      const startTime = _INTERNAL_performanceTimeToSeconds(entry.startTime);
+      if (!startTime || !entry.scripts[0]) {
         continue;
       }
 
-      const startTime = msToSec((browserPerformanceTimeOrigin() as number) + entry.startTime);
-
       const {
         start_timestamp: parentStartTimestamp,
         attributes: { [SENTRY_OP]: parentOp },
@@ -209,22 +211,22 @@ interface AddPerformanceEntriesOptions {
 /** Add performance related spans to a transaction */
 export function addPerformanceEntries(span: Span, options: AddPerformanceEntriesOptions): void {
   const performance = getBrowserPerformanceAPI();
-  const origin = browserPerformanceTimeOrigin();
-  if (!performance?.getEntries || !origin) {
+  if (!performance?.getEntries) {
     // Gatekeeper if performance API not available
     return;
   }
 
   const { spanStreamingEnabled, ignoreResourceSpans } = options;
 
-  const timeOrigin = msToSec(origin);
-
   const performanceEntries = performance.getEntries();
 
   const { attributes, start_timestamp: transactionStartTime } = spanToJSON(span);
 
   performanceEntries.slice(_performanceCursor).forEach(entry => {
-    const startTime = msToSec(entry.startTime);
+    const startTimestamp = _INTERNAL_performanceTimeToSeconds(entry.startTime);
+    if (!startTimestamp) {
+      return;
+    }
     const duration = msToSec(
       // Inexplicably, Chrome sometimes emits a negative duration. We need to work around this.
       // There is a SO post attempting to explain this, but it leaves one with open questions: https://stackoverflow.com/questions/23191918/peformance-getentries-and-negative-duration-display
@@ -233,31 +235,26 @@ export function addPerformanceEntries(span: Span, options: AddPerformanceEntries
       Math.max(0, entry.duration),
     );
 
-    if (
-      attributes[SENTRY_OP] === 'navigation' &&
-      transactionStartTime &&
-      timeOrigin + startTime < transactionStartTime
-    ) {
+    if (attributes[SENTRY_OP] === 'navigation' && transactionStartTime && startTimestamp < transactionStartTime) {
       return;
     }
 
     switch (entry.entryType) {
       case 'navigation': {
-        _addNavigationSpans(span, entry as PerformanceNavigationTiming, timeOrigin, spanStreamingEnabled);
+        _addNavigationSpans(span, entry as PerformanceNavigationTiming, spanStreamingEnabled);
         break;
       }
       case 'paint': {
-        _addPaintSpan(span, entry, startTime, duration, timeOrigin);
+        _addPaintSpan(span, entry, startTimestamp, duration);
         break;
       }
       case 'resource': {
         _addResourceSpans(
           span,
           entry as PerformanceResourceTiming,
           entry.name,
-          startTime,
+          startTimestamp,
           duration,
-          timeOrigin,
           ignoreResourceSpans,
           spanStreamingEnabled,
         );
@@ -276,15 +273,7 @@ export function addPerformanceEntries(span: Span, options: AddPerformanceEntries
  * Create a span for a browser paint performance entry.
  * Exported only for tests.
  */
-export function _addPaintSpan(
-  span: Span,
-  entry: PerformanceEntry,
-  startTime: number,
-  duration: number,
-  timeOrigin: number,
-): void {
-  const startTimestamp = timeOrigin + startTime;
-
+export function _addPaintSpan(span: Span, entry: PerformanceEntry, startTimestamp: number, duration: number): void {
   startAndEndSpan(span, startTimestamp, startTimestamp + duration, {
     // The entry name (`first-paint`, `first-contentful-paint`) is already the low-cardinality name
     // the conventions ask for, so only the attribute backing it has to be added.
@@ -304,19 +293,27 @@ export function _addPaintSpan(
 export function _addNavigationSpans(
   span: Span,
   entry: PerformanceNavigationTiming,
-  timeOrigin: number,
   spanStreamingEnabled?: boolean,
 ): void {
-  _addPerformanceNavigationTiming(span, entry, 'unloadEvent', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'redirect', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'domContentLoadedEvent', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'loadEvent', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'connect', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'secureConnection', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'fetch', timeOrigin, spanStreamingEnabled);
-  _addPerformanceNavigationTiming(span, entry, 'domainLookup', timeOrigin, spanStreamingEnabled);
-
-  _addRequest(span, entry, timeOrigin, spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'unloadEvent', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'redirect', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'domContentLoadedEvent', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'loadEvent', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'connect', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'secureConnection', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'fetch', spanStreamingEnabled);
+  _addPerformanceNavigationTiming(span, entry, 'domainLookup', spanStreamingEnabled);
+
+  _addRequest(span, entry, spanStreamingEnabled);
+}
+
+/**
+ * Navigations can happen long after page load, after the time origin was corrected for drift. We use the origin from
+ * the entry's start for all its timings, so its duration stays correct.
+ */
+function _navigationTimeToSeconds(entry: PerformanceNavigationTiming, time: number): number {
+  // The cast is safe: `addPerformanceEntries` only adds navigation spans if the time origin is available.
+  return _INTERNAL_performanceTimeToSeconds(time, entry.startTime) as number;
 }
 
 type StartEventName =
@@ -354,7 +351,6 @@ function _addPerformanceNavigationTiming(
   span: Span,
   entry: PerformanceNavigationTiming,
   event: StartEventName,
-  timeOrigin: number,
   spanStreamingEnabled: boolean | undefined,
 ): void {
   const eventEnd = _getEndPropertyNameForNavigationTiming(event) satisfies keyof PerformanceNavigationTiming;
@@ -364,7 +360,7 @@ function _addPerformanceNavigationTiming(
     return;
   }
   const op = NAVIGATION_TIMING_SPAN_OPS[event];
-  startAndEndSpan(span, timeOrigin + msToSec(start), timeOrigin + msToSec(end), {
+  startAndEndSpan(span, _navigationTimeToSeconds(entry, start), _navigationTimeToSeconds(entry, end), {
     // With span streaming, span names have to be low cardinality, so we can't fall back to the
     // document URL. `url.full` keeps it, and is what Relay derives the description from.
     name: spanStreamingEnabled ? BROWSER_NAVIGATION_TIMING_SPAN_NAMES[op] : entry.name,
@@ -388,15 +384,10 @@ function _getEndPropertyNameForNavigationTiming(event: StartEventName): EndEvent
 }
 
 /** Create request and response related spans */
-function _addRequest(
-  span: Span,
-  entry: PerformanceNavigationTiming,
-  timeOrigin: number,
-  spanStreamingEnabled: boolean | undefined,
-): void {
-  const requestStartTimestamp = timeOrigin + msToSec(entry.requestStart);
-  const responseEndTimestamp = timeOrigin + msToSec(entry.responseEnd);
-  const responseStartTimestamp = timeOrigin + msToSec(entry.responseStart);
+function _addRequest(span: Span, entry: PerformanceNavigationTiming, spanStreamingEnabled: boolean | undefined): void {
+  const requestStartTimestamp = _navigationTimeToSeconds(entry, entry.requestStart);
+  const responseEndTimestamp = _navigationTimeToSeconds(entry, entry.responseEnd);
+  const responseStartTimestamp = _navigationTimeToSeconds(entry, entry.responseStart);
   if (entry.responseEnd) {
     // It is possible that we are collecting these metrics when the page hasn't finished loading yet, for example when the HTML slowly streams in.
     // In this case, ie. when the document request hasn't finished yet, `entry.responseEnd` will be 0.
@@ -435,9 +426,8 @@ export function _addResourceSpans(
   span: Span,
   entry: PerformanceResourceTiming,
   resourceUrl: string,
-  startTime: number,
+  startTimestamp: number,
   duration: number,
-  timeOrigin: number,
   ignoredResourceSpanOps?: Array<string>,
   spanStreamingEnabled?: boolean,
 ): void {
@@ -497,7 +487,6 @@ export function _addResourceSpans(
 
   const attributesWithResourceTiming: SpanAttributes = { ...attributes, ...resourceTimingToSpanAttributes(entry) };
 
-  const startTimestamp = timeOrigin + startTime;
   const endTimestamp = startTimestamp + duration;
 
   startAndEndSpan(span, startTimestamp, endTimestamp, {

packages/browser-utils/src/performance/interactions.ts

@@ -16,13 +16,13 @@ import {
 import { UI_ACTION_CLICK, UI_INTERACTION_CLICK } from '@sentry/conventions/op';
 import type { Client, IntegrationFn, Span, StartSpanOptions, TransactionSource } from '@sentry/core';
 import {
-  browserPerformanceTimeOrigin,
   debug,
   defineIntegration,
   filterCollectedUrl,
   getActiveSpan,
   getRootSpan,
   hasSpanStreamingEnabled,
+  _INTERNAL_performanceTimeToSeconds,
   spanToJSON,
   UI_ACTION_CLICK_SPAN_NAME_FALLBACK,
   UI_INTERACTION_CLICK_SPAN_NAME_FALLBACK,
@@ -242,7 +242,10 @@ function trackInteractionsAsSpans(client: Client): void {
     }
     for (const entry of entries) {
       if (entry.name === 'click') {
-        const startTime = msToSec((browserPerformanceTimeOrigin() as number) + entry.startTime);
+        const startTime = _INTERNAL_performanceTimeToSeconds(entry.startTime);
+        if (!startTime) {
+          continue;
+        }
         const duration = msToSec(entry.duration);
 
         const selector = htmlTreeAsString(entry.target);

packages/browser-utils/src/performance/resourceTiming.ts

@@ -1,12 +1,6 @@
 import type { SpanAttributes } from '@sentry/core';
-import { browserPerformanceTimeOrigin } from '@sentry/core';
-import { extractNetworkProtocol, getBrowserPerformanceAPI } from './utils';
-
-function getAbsoluteTime(time: number | undefined): number | undefined {
-  // falsy values should be preserved so that we can later on drop undefined values and
-  // preserve 0 vals for cross-origin resources without proper `Timing-Allow-Origin` header.
-  return time ? ((browserPerformanceTimeOrigin() || performance.timeOrigin) + time) / 1000 : time;
-}
+import { _INTERNAL_performanceTimeToSeconds } from '@sentry/core';
+import { extractNetworkProtocol, msToSec } from './utils';
 
 /**
  * Converts a PerformanceResourceTiming entry to span data for the resource span. Most importantly,
@@ -28,10 +22,16 @@ export function resourceTimingToSpanAttributes(resourceTiming: PerformanceResour
     timingSpanData['network.protocol.name'] = name;
   }
 
-  if (!(browserPerformanceTimeOrigin() || getBrowserPerformanceAPI()?.timeOrigin)) {
+  if (_INTERNAL_performanceTimeToSeconds(resourceTiming.startTime) === undefined) {
     return timingSpanData;
   }
 
+  // Use the origin from the request start for all timings, so the durations between them stay correct.
+  const getAbsoluteTime = (time: number | undefined): number | undefined =>
+    // falsy values should be preserved so that we can later on drop undefined values and
+    // preserve 0 vals for cross-origin resources without proper `Timing-Allow-Origin` header.
+    time ? _INTERNAL_performanceTimeToSeconds(time, resourceTiming.startTime) : time;
+
   return dropUndefinedKeysFromObject({
     ...timingSpanData,
 
@@ -58,7 +58,7 @@ export function resourceTimingToSpanAttributes(resourceTiming: PerformanceResour
     // This way, TTFB always measures the "first page load" experience.
     // see: https://web.dev/articles/ttfb#measure-resource-requests
     'http.request.time_to_first_byte':
-      resourceTiming.responseStart != null ? resourceTiming.responseStart / 1000 : undefined,
+      resourceTiming.responseStart != null ? msToSec(resourceTiming.responseStart) : undefined,
   });
 }