getsentry · runningcode · Sep 4, 2026
@@ -5,6 +5,7 @@
 ### Internal
 
 - Add an internal `MonotonicClock` 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))
 
 ## 8.55.0
 

@@ -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,15 @@ public final class io/sentry/rrweb/RRWebVideoEvent$JsonKeys {
 	public fun <init> ()V
 }
 
+public final class io/sentry/time/AnchoredClock {
+	public fun at (J)Lio/sentry/time/Timestamp;
+	public static fun create (Lio/sentry/time/EpochClock;Lio/sentry/time/MonotonicClock;)Lio/sentry/time/AnchoredClock;
+	public fun driftNanos ()J
+	public fun now ()Lio/sentry/time/Timestamp;
+	public fun start ()Lio/sentry/time/Timestamp;
+	public fun tickOf (Lio/sentry/time/Timestamp;)J
+}
+
 public final class io/sentry/time/Deadline {
 	public static fun after (Lio/sentry/time/MonotonicClock;JLjava/util/concurrent/TimeUnit;)Lio/sentry/time/Deadline;
 	public fun hasPassed ()Z
@@ -7606,6 +7616,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/JavaMonotonicClock : io/sentry/time/MonotonicClock {
 	public static fun getInstance ()Lio/sentry/time/MonotonicClock;
 	public fun tickNanos ()J
@@ -7621,6 +7635,19 @@ public final class io/sentry/time/Stopwatch {
 	public static fun started (Lio/sentry/time/MonotonicClock;)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

@@ -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.JavaMonotonicClock;
 import io.sentry.time.MonotonicClock;
+import io.sentry.time.SystemEpochClock;
 import io.sentry.transport.ITransport;
 import io.sentry.transport.ITransportGate;
 import io.sentry.transport.NoOpEnvelopeCache;
@@ -527,6 +529,9 @@ public class SentryOptions {
   private final @NotNull LazyEvaluator<SentryDateProvider> dateProvider =
       new LazyEvaluator<>(() -> new SentryAutoDateProvider());
 
+  private final @NotNull LazyEvaluator<EpochClock> epochClock =
+      new LazyEvaluator<>(() -> SystemEpochClock.getInstance());
+
   private final @NotNull List<IPerformanceCollector> performanceCollectors = new ArrayList<>();
 
   /** Performance collector that collect performance stats while transactions run. */
@@ -3061,6 +3066,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 #getMonotonicClock()}.
+   */
+  @ApiStatus.Internal
+  public @NotNull EpochClock getEpochClock() {
+    return epochClock.getValue();
+  }
+
   /**
    * Returns the clock used to measure elapsed time, such as rate-limit windows, cache expiry and
    * ANR thresholds.

@@ -0,0 +1,101 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * One wall-clock reading pinned to one monotonic tick, from which related instants are projected.
+ *
+ * <p>Exists because a group of instants that will be compared against each other — the spans of a
+ * transaction, the samples of a profile chunk, the frames of a replay segment — must not each read
+ * the wall clock. Two independent readings differ by whatever the device's clock did in between, so
+ * a duration taken across them can shorten, lengthen or go negative, and a child can appear to
+ * start before its parent. Reading the epoch once and projecting the rest through {@link
+ * MonotonicClock} makes every instant in the group an image of the same tick, so subtracting any
+ * two of them reports measured time.
+ *
+ * <p>The span protocol needs exactly that: it carries a start and an end instant and no duration
+ * field, so the server subtracts them.
+ *
+ * <p>Projection also buys resolution the wall clock does not have. On Android the epoch is
+ * millisecond-granular, so an instant read directly is truncated, whereas one projected from a tick
+ * carries nanoseconds — the workaround {@link io.sentry.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.
+ *
+ * <p>The cost is that a projection drifts as the anchor ages: it reports what the clock said when
+ * the anchor was taken, plus measured time, so a clock step afterwards is invisible to it. Anchor
+ * something short-lived, and use {@link #driftNanos()} to observe the gap.
+ */
+@ApiStatus.Internal
+public final class AnchoredClock {
+
+  private final @NotNull EpochClock epoch;
+  private final @NotNull MonotonicClock clock;
+  private final long epochNanos;
+  private final long anchorTick;
+
+  private AnchoredClock(
+      final @NotNull EpochClock epoch,
+      final @NotNull MonotonicClock clock,
+      final long epochNanos,
+      final long anchorTick) {
+    this.epoch = epoch;
+    this.clock = clock;
+    this.epochNanos = epochNanos;
+    this.anchorTick = anchorTick;
+  }
+
+  /** Takes the anchor now: one epoch reading, one tick, as close together as a call allows. */
+  public static @NotNull AnchoredClock create(
+      final @NotNull EpochClock epoch, final @NotNull MonotonicClock clock) {
+    return new AnchoredClock(epoch, clock, epoch.now().epochNanos(), clock.tickNanos());
+  }
+
+  /** The anchor itself — the one instant here that was read rather than projected. */
+  public @NotNull Timestamp start() {
+    return Timestamp.anchoredAt(epochNanos, this);
+  }
+
+  public @NotNull Timestamp now() {
+    return at(clock.tickNanos());
+  }
+
+  /**
+   * The instant a tick corresponds to, for placing something already measured on this clock — a
+   * frame, a profiler sample — on the same timeline as the instants projected here.
+   */
+  public @NotNull Timestamp at(final long tickNanos) {
+    return Timestamp.anchoredAt(epochNanos + (tickNanos - anchorTick), this);
+  }
+
+  /**
+   * The tick an instant was projected from. Exact, and reads no clock: projection adds a tick
+   * difference to a fixed epoch, so subtraction inverts it.
+   *
+   * @throws IllegalArgumentException if this clock did not project the instant. Its epoch bears no
+   *     arithmetic relation to these ticks, so converting it would silently produce a tick derived
+   *     from a wall-clock difference.
+   */
+  public long tickOf(final @NotNull Timestamp timestamp) {
+    if (timestamp.anchor() != this) {
+      throw new IllegalArgumentException(
+          "Timestamp was not projected by this AnchoredClock: " + timestamp);
+    }
+    return anchorTick + (timestamp.epochNanos() - epochNanos);
+  }
+
+  /**
+   * How far this anchor's projection has fallen behind or ahead of the wall clock, in nanoseconds.
+   *
+   * <p>Zero means the wall clock advanced by exactly the time this clock measured. Anything else is
+   * a clock step, or — where {@link MonotonicClock} and the wall clock disagree about suspend —
+   * device sleep. Reads the epoch and the tick in the same order as {@link #create}, so the gap
+   * between the two reads biases the result the same way it biased the anchor.
+   */
+  public long driftNanos() {
+    final long wallElapsed = epoch.now().epochNanos() - epochNanos;
+    final long measuredElapsed = clock.tickNanos() - anchorTick;
+    return wallElapsed - measuredElapsed;
+  }
+}
@@ -0,0 +1,20 @@
+package io.sentry.time;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * The source of wall-clock time.
+ *
+ * <p>Stamps a moment that will leave this process — an event, a breadcrumb, a session — and nothing
+ * else. It deliberately cannot report a duration: measuring belongs to {@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();
+}
@@ -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();
+  }
+}
@@ -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()));
+  }
+}
@@ -0,0 +1,79 @@
+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 MonotonicClock} 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>{@link #anchor()} records which of those this is. An instant read straight from the wall
+ * clock, or stated by something outside this process, has no anchor and can only be serialized. One
+ * an {@link AnchoredClock} produced references that clock, which lets {@link AnchoredClock#tickOf}
+ * recover the tick it came from and reject instants it did not produce.
+ *
+ * <p>Nanoseconds since the epoch overflow a long in the year 2262.
+ */
+@ApiStatus.Internal
+public final class Timestamp {
+
+  private final long epochNanos;
+  private final @Nullable AnchoredClock anchor;
+
+  private Timestamp(final long epochNanos, final @Nullable AnchoredClock anchor) {
+    this.epochNanos = epochNanos;
+    this.anchor = anchor;
+  }
+
+  /** An instant read straight from a wall clock, or stated by something outside this process. */
+  public static @NotNull Timestamp ofEpochNanos(final long epochNanos) {
+    return new Timestamp(epochNanos, null);
+  }
+
+  static @NotNull Timestamp anchoredAt(final long epochNanos, final @NotNull AnchoredClock anchor) {
+    return new Timestamp(epochNanos, anchor);
+  }
+
+  public long epochNanos() {
+    return epochNanos;
+  }
+
+  /** The clock that projected this instant, or null if it was read or stated directly. */
+  @Nullable
+  AnchoredClock anchor() {
+    return anchor;
+  }
+
+  /**
+   * Equality is by instant. The anchor records how the instant was obtained, not what it denotes,
+   * so two readings of the same moment are equal whether or not they were projected.
+   */
+  @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 + '}';
+  }
+}