feat(time): Add Timestamp, EpochClock and AnchoredClock (JAVA-572) (#6045)

SentryDate is asked to be four things at once: an epoch instant to
serialize, one endpoint of a monotonic interval, a carrier of a hidden
System.nanoTime() reading, and an opaque foreign timestamp. Nothing in the
type separates them, so the guarantees are decided by the runtime class of
both operands -- SentryNanotimeDate.diff() is monotonic only when the other
date is also a SentryNanotimeDate, and silently subtracts two wall-clock
readings otherwise. On the JVM, where SentryAutoDateProvider picks
SentryInstantDate, neither endpoint has a monotonic component and span
durations are not monotonic at all.

The fix is not to type the instants more carefully. It is to stop producing
them independently. A group of instants that will be compared against each
other -- the spans of a transaction, the samples of a profile chunk, the
segments of a replay -- reads the epoch once and builds the rest from the
monotonic ticker:

  Timestamp      an epoch instant. No arithmetic between instants; equality
                 is by instant.
  EpochClock     the wall clock, for stamping a moment that leaves the
                 process. Not for computing durations.
  AnchoredClock  one wall-clock reading pinned to one tick, from which now()
                 builds.

Subtracting two instants from one anchor is subtracting two ticks, so a
duration is monotonic by construction rather than by convention, and a clock
step cannot make a child span start before its parent. It also gives Android
nanosecond resolution it cannot read directly, the epoch being
millisecond-granular there -- the workaround SentryNanotimeDate describes,
applied once per group instead of between each pair of readings.
OpenTelemetry's SDK anchors per local root span for the same two reasons.

Only what a caller needs today is exposed. Placing an externally measured
tick on the anchor's timeline, and recovering the tick a timestamp was built
from, are both exact and both trivial to add, but neither is reachable until
spans carry an anchor. They belong to the change that migrates them rather
than to this one, where they would arrive with no caller.

Timing is dropped rather than kept. It paired one Timestamp with one
Stopwatch, which is what AnchoredClock does for a whole group, and no call
site would have wanted the single-interval version.

Nothing calls any of it yet.

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

Author: runningcode

CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Internal
 
 - Add an internal `MonotonicTicker` abstraction with `Deadline` and `Stopwatch` primitives ([#6028](https://github.com/getsentry/sentry-java/pull/6028))
+- Add internal `Timestamp`, `EpochClock` and `AnchoredClock`, so related instants project from one wall-clock reading instead of each reading the clock ([#6045](https://github.com/getsentry/sentry-java/pull/6045))
 
 ### Dependencies
 

sentry/api/sentry.api

@@ -3707,6 +3707,7 @@ public class io/sentry/SentryOptions {
 	public fun getEnvelopeDiskCache ()Lio/sentry/cache/IEnvelopeCache;
 	public fun getEnvelopeReader ()Lio/sentry/IEnvelopeReader;
 	public fun getEnvironment ()Ljava/lang/String;
+	public fun getEpochClock ()Lio/sentry/time/EpochClock;
 	public fun getEventProcessors ()Ljava/util/List;
 	public fun getExecutorService ()Lio/sentry/ISentryExecutorService;
 	public fun getExperimental ()Lio/sentry/ExperimentalOptions;
@@ -7598,6 +7599,12 @@ public final class io/sentry/rrweb/RRWebVideoEvent$JsonKeys {
 	public fun <init> ()V
 }
 
+public final class io/sentry/time/AnchoredClock {
+	public static fun create (Lio/sentry/time/EpochClock;Lio/sentry/time/MonotonicTicker;)Lio/sentry/time/AnchoredClock;
+	public fun now ()Lio/sentry/time/Timestamp;
+	public fun startTime ()Lio/sentry/time/Timestamp;
+}
+
 public final class io/sentry/time/Deadline {
 	public static fun after (Lio/sentry/time/MonotonicTicker;JLjava/util/concurrent/TimeUnit;)Lio/sentry/time/Deadline;
 	public fun hasPassed ()Z
@@ -7606,6 +7613,10 @@ public final class io/sentry/time/Deadline {
 	public fun remaining (Ljava/util/concurrent/TimeUnit;)J
 }
 
+public abstract interface class io/sentry/time/EpochClock {
+	public abstract fun now ()Lio/sentry/time/Timestamp;
+}
+
 public final class io/sentry/time/JavaMonotonicTicker : io/sentry/time/MonotonicTicker {
 	public static fun getInstance ()Lio/sentry/time/MonotonicTicker;
 	public fun tickNanos ()J
@@ -7621,6 +7632,19 @@ public final class io/sentry/time/Stopwatch {
 	public static fun started (Lio/sentry/time/MonotonicTicker;)Lio/sentry/time/Stopwatch;
 }
 
+public final class io/sentry/time/SystemEpochClock : io/sentry/time/EpochClock {
+	public static fun getInstance ()Lio/sentry/time/EpochClock;
+	public fun now ()Lio/sentry/time/Timestamp;
+}
+
+public final class io/sentry/time/Timestamp {
+	public fun epochNanos ()J
+	public fun equals (Ljava/lang/Object;)Z
+	public fun hashCode ()I
+	public static fun ofEpochNanos (J)Lio/sentry/time/Timestamp;
+	public fun toString ()Ljava/lang/String;
+}
+
 public final class io/sentry/transport/AsyncHttpTransport : io/sentry/transport/ITransport {
 	public fun <init> (Lio/sentry/SentryOptions;Lio/sentry/transport/RateLimiter;Lio/sentry/transport/ITransportGate;Lio/sentry/RequestDetails;)V
 	public fun <init> (Lio/sentry/transport/QueuedThreadPoolExecutor;Lio/sentry/SentryOptions;Lio/sentry/transport/RateLimiter;Lio/sentry/transport/ITransportGate;Lio/sentry/transport/HttpConnection;)V

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -21,8 +21,10 @@
 import io.sentry.metrics.IMetricsBatchProcessorFactory;
 import io.sentry.protocol.SdkVersion;
 import io.sentry.protocol.SentryTransaction;
+import io.sentry.time.EpochClock;
 import io.sentry.time.JavaMonotonicTicker;
 import io.sentry.time.MonotonicTicker;
+import io.sentry.time.SystemEpochClock;
 import io.sentry.transport.ITransport;
 import io.sentry.transport.ITransportGate;
 import io.sentry.transport.NoOpEnvelopeCache;
@@ -3061,6 +3063,19 @@ public void setDateProvider(final @NotNull SentryDateProvider dateProvider) {
     this.dateProvider.setValue(dateProvider);
   }
 
+  /**
+   * Returns the wall clock, for stamping an instant that will be serialized.
+   *
+   * <p>Reports the same epoch as {@link #getDateProvider()}, but a {@link io.sentry.time.Timestamp}
+   * carries no {@link System#nanoTime()} tick of its own the way a {@link SentryNanotimeDate} does.
+   * Instants that will be subtracted from each other come from an {@link
+   * io.sentry.time.AnchoredClock} built on this and {@link #getMonotonicTicker()}.
+   */
+  @ApiStatus.Internal
+  public @NotNull EpochClock getEpochClock() {
+    return SystemEpochClock.getInstance();
+  }
+
   /**
    * Returns the ticker used to measure elapsed time, such as rate-limit windows, cache expiry and
    * ANR thresholds.

sentry/src/main/java/io/sentry/time/AnchoredClock.java

@@ -0,0 +1,57 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * One wall-clock reading plus a monotonic ticker, producing timestamps that are safe to subtract
+ * from each other.
+ *
+ * <p>Wall clocks jump. Read the wall clock twice and the device may have changed it in between, so
+ * the gap between the two readings is not the time that actually passed — it can come out too
+ * short, too long, or negative. That is how a child span ends up starting before its parent.
+ *
+ * <p>So for a group of timestamps that will be compared with each other — the spans of a
+ * transaction, the samples of a profile chunk, the frames of a replay segment — read the wall clock
+ * only once (the anchor) and build the rest by adding the time a {@link MonotonicTicker} has
+ * measured since, which only ever moves forward. Gaps between those timestamps are then real
+ * elapsed time. Spans need exactly that: the protocol sends a start and an end timestamp and no
+ * duration, so the server subtracts them.
+ */
+@ApiStatus.Internal
+public final class AnchoredClock {
+
+  private final @NotNull MonotonicTicker ticker;
+  private final long epochNanos;
+  private final long anchorTick;
+
+  private AnchoredClock(
+      final @NotNull MonotonicTicker ticker, final long epochNanos, final long anchorTick) {
+    this.ticker = ticker;
+    this.epochNanos = epochNanos;
+    this.anchorTick = anchorTick;
+  }
+
+  /** Takes the anchor now: one wall-clock reading and one tick, back to back. */
+  public static @NotNull AnchoredClock create(
+      final @NotNull EpochClock epoch, final @NotNull MonotonicTicker ticker) {
+    return new AnchoredClock(ticker, epoch.now().epochNanos(), ticker.tickNanos());
+  }
+
+  /**
+   * The anchor itself: the one timestamp here that was read from the wall clock rather than built
+   * from a tick. Reads no clock and never changes.
+   */
+  public @NotNull Timestamp startTime() {
+    return Timestamp.ofEpochNanos(epochNanos);
+  }
+
+  /** Now: {@link #startTime()} plus the time the ticker has measured since the anchor. */
+  public @NotNull Timestamp now() {
+    return at(ticker.tickNanos());
+  }
+
+  private @NotNull Timestamp at(final long tickNanos) {
+    return Timestamp.ofEpochNanos(epochNanos + (tickNanos - anchorTick));
+  }
+}

sentry/src/main/java/io/sentry/time/EpochClock.java

@@ -0,0 +1,20 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * The source of wall-clock {@link Timestamp}s (aka, instants).
+ *
+ * <p>Stamps a moment that will leave this process, an event, a breadcrumb, a session, and nothing
+ * else. This class should <b>not</b> be used to compute durations. For Durations, use {@link
+ * Stopwatch}, and a group of instants that will be subtracted from each other belongs to an {@link
+ * AnchoredClock}, which reads this once and projects the rest.
+ */
+@ApiStatus.Internal
+public interface EpochClock {
+
+  /** The current instant. Serialize it; do not subtract it from another one. */
+  @NotNull
+  Timestamp now();
+}

sentry/src/main/java/io/sentry/time/InstantEpochNanos.java

@@ -0,0 +1,25 @@
+package io.sentry.time;
+
+import io.sentry.DateUtils;
+import java.time.Instant;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Reads the epoch from {@link Instant}.
+ *
+ * <p>A class of its own so the reference to {@code java.time} is loaded only where {@link
+ * SystemEpochClock} decided to use it. Android's minSdk is below the API 26 that introduced {@code
+ * Instant}.
+ */
+@ApiStatus.Internal
+@SuppressWarnings("NewApi")
+final class InstantEpochNanos {
+
+  private InstantEpochNanos() {}
+
+  static long read() {
+    final Instant now = Instant.now();
+    // No long overflow until year 2262
+    return DateUtils.secondsToNanos(now.getEpochSecond()) + now.getNano();
+  }
+}

sentry/src/main/java/io/sentry/time/SystemEpochClock.java

@@ -0,0 +1,40 @@
+package io.sentry.time;
+
+import io.sentry.DateUtils;
+import io.sentry.util.Platform;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * The {@link EpochClock} backed by the system wall clock.
+ *
+ * <p>Reads the epoch at the best precision the platform offers: {@link java.time.Instant} where it
+ * is sub-millisecond, {@link System#currentTimeMillis()} everywhere else. Android is always the
+ * latter — {@code Instant} is millisecond-granular there whether or not the build desugars it, see
+ * https://github.com/getsentry/sentry-java/pull/2451.
+ *
+ * <p>A millisecond anchor loses less than it looks: an {@link AnchoredClock} adds nanosecond ticks
+ * to one anchor, so only the anchor is coarse.
+ */
+@ApiStatus.Internal
+public final class SystemEpochClock implements EpochClock {
+
+  private static final boolean INSTANT_IS_SUB_MILLISECOND =
+      Platform.isJvm() && Platform.isJavaNinePlus();
+
+  private static final SystemEpochClock instance = new SystemEpochClock();
+
+  public static @NotNull EpochClock getInstance() {
+    return instance;
+  }
+
+  private SystemEpochClock() {}
+
+  @Override
+  public @NotNull Timestamp now() {
+    return Timestamp.ofEpochNanos(
+        INSTANT_IS_SUB_MILLISECOND
+            ? InstantEpochNanos.read()
+            : DateUtils.millisToNanos(System.currentTimeMillis()));
+  }
+}

sentry/src/main/java/io/sentry/time/Timestamp.java

@@ -0,0 +1,57 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * An instant on the wall clock, as nanoseconds since the Unix epoch.
+ *
+ * <p>Unlike a {@link MonotonicTicker} tick, a timestamp means something outside this process: it
+ * can be serialized, stored, and compared against a value from another machine.
+ *
+ * <p>It deliberately offers no arithmetic between instants. Subtracting two independent wall-clock
+ * readings gives a duration the device's clock can lengthen, shorten or make negative. Durations
+ * come from a {@link Stopwatch}, or from two instants an {@link AnchoredClock} projected from the
+ * same tick.
+ *
+ * <p>Nanoseconds since the epoch overflow a long in the year 2262.
+ */
+@ApiStatus.Internal
+public final class Timestamp {
+
+  private final long epochNanos;
+
+  private Timestamp(final long epochNanos) {
+    this.epochNanos = epochNanos;
+  }
+
+  public static @NotNull Timestamp ofEpochNanos(final long epochNanos) {
+    return new Timestamp(epochNanos);
+  }
+
+  public long epochNanos() {
+    return epochNanos;
+  }
+
+  @Override
+  public boolean equals(final @Nullable Object other) {
+    if (this == other) {
+      return true;
+    }
+    if (!(other instanceof Timestamp)) {
+      return false;
+    }
+    return epochNanos == ((Timestamp) other).epochNanos;
+  }
+
+  @Override
+  public int hashCode() {
+    return (int) (epochNanos ^ (epochNanos >>> 32));
+  }
+
+  @Override
+  public @NotNull String toString() {
+    return "Timestamp{epochNanos=" + epochNanos + '}';
+  }
+}

sentry/src/test/java/io/sentry/time/AnchoredClockTest.kt

@@ -0,0 +1,51 @@
+package io.sentry.time
+
+import com.google.common.truth.Truth.assertThat
+import java.util.concurrent.TimeUnit.MILLISECONDS
+import java.util.concurrent.TimeUnit.SECONDS
+import kotlin.test.Test
+
+class AnchoredClockTest {
+  private val epoch = FixedEpochClock(SECONDS.toNanos(1_700_000_000))
+  private val ticker = TestMonotonicTicker(SECONDS.toNanos(5_000))
+  private val anchored = AnchoredClock.create(epoch, ticker)
+
+  @Test
+  fun `startTime is the wall-clock reading the anchor was taken at`() {
+    assertThat(anchored.startTime().epochNanos()).isEqualTo(SECONDS.toNanos(1_700_000_000))
+  }
+
+  @Test
+  fun `now is the anchor plus the time measured since`() {
+    ticker.advance(120, MILLISECONDS)
+
+    assertThat(anchored.now().epochNanos())
+      .isEqualTo(SECONDS.toNanos(1_700_000_000) + MILLISECONDS.toNanos(120))
+  }
+
+  @Test
+  fun `a wall-clock step does not move a projected instant`() {
+    ticker.advance(120, MILLISECONDS)
+    epoch.epochNanos -= SECONDS.toNanos(30)
+
+    assertThat(anchored.now().epochNanos())
+      .isEqualTo(SECONDS.toNanos(1_700_000_000) + MILLISECONDS.toNanos(120))
+  }
+
+  @Test
+  fun `two projected instants differ by measured time, across a wall-clock step`() {
+    val start = anchored.now()
+    epoch.epochNanos += SECONDS.toNanos(30)
+    ticker.advance(750, MILLISECONDS)
+    val end = anchored.now()
+
+    assertThat(end.epochNanos() - start.epochNanos()).isEqualTo(MILLISECONDS.toNanos(750))
+  }
+
+  @Test
+  fun `a millisecond anchor still projects nanoseconds`() {
+    ticker.advance(1_234, java.util.concurrent.TimeUnit.NANOSECONDS)
+
+    assertThat(anchored.now().epochNanos()).isEqualTo(SECONDS.toNanos(1_700_000_000) + 1_234)
+  }
+}

sentry/src/test/java/io/sentry/time/FixedEpochClock.kt

@@ -0,0 +1,6 @@
+package io.sentry.time
+
+/** An [EpochClock] whose instant only moves when a test moves it. */
+internal class FixedEpochClock(var epochNanos: Long = 0) : EpochClock {
+  override fun now(): Timestamp = Timestamp.ofEpochNanos(epochNanos)
+}