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

[runningcode]

PR Stack (Clock semantics hardening)

• feat(time): Add a monotonic clock abstraction (JAVA-571) #6028
• this PR
• fix(android): Treat an unpopulated connection cache as stale (JAVA-717) #6029
• ref(transport): Measure rate-limit backoff on a monotonic clock (JAVA-574) #6030
• ref(checkin): Measure check-in durations with Stopwatch (JAVA-576) #6032
• ref(android): Measure ANR thresholds on the monotonic clock (JAVA-579) #6041
• ref(time): Deprecate the legacy date and clock providers (JAVA-571) #6043

---

📜 Description

Adds the wall-clock half of the time API — Timestamp, EpochClock and AnchoredClock — on top of
the MonotonicClock/Stopwatch primitives from #6028. Nothing calls any of it yet, like #6028.

Timestamp      // an epoch instant, plus the anchor that projected it (or null if read directly).
               // No arithmetic between instants; equality is by instant.
EpochClock     // now() stamps a moment that leaves the process. Cannot report a duration.
AnchoredClock  // one epoch reading pinned to one tick. now()/at(tick) project, tickOf() inverts
               // exactly, driftNanos() reports how far the projection trails the wall clock.

SentryOptions.getEpochClock() is the injection point.

💡 Motivation and Context

Why anchoring, rather than more careful types

The bug class is not "wall vs monotonic". It is pairwise arithmetic between two independently
produced instants. Better types narrow that; they do not close it, because a mixed pair is still
reachable and still has to answer.

So the fix is to stop producing the instants independently. A group 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 projects the rest through the monotonic clock:

epoch(t) = anchorEpoch + (tick(t) − anchorTick)

The projection is affine with slope 1, so subtracting two instants from one anchor is subtracting
two ticks. A duration is then monotonic by construction rather than by convention, and a clock step
cannot make a child span start before its parent. It also buys resolution the wall clock does not
have: Android's epoch is millisecond-granular, so a directly read instant is truncated while a
projected one carries nanoseconds. OpenTelemetry's SDK does the same thing, per local root span, for
the same two reasons.

tickOf() refusing an instant it did not project is what makes this safer rather than merely
tidier, and it is why Timestamp references its anchor at all: mixing domains raises an
IllegalArgumentException instead of returning a plausible-looking wrong number. An instant read
straight from the wall clock, or stated by something outside the process, has no anchor and can only
be serialized.

• resolves: JAVA-572 (partially — this is the additive, behaviour-free half)

The epoch clock does not go through SentryDateProvider

SystemEpochClock reads the wall clock directly, picking precision the way SentryAutoDateProvider
does: Instant.now() on JVM 9+, System.currentTimeMillis() otherwise. Android is always the
latter — Instant is millisecond-granular there whether or not the build desugars it (#2451). The
values are byte-identical to what the provider returns on every platform; what changes is that
reading one no longer allocates a SentryDate, and on Android no longer takes a System.nanoTime()
reading that an EpochClock never looks at.

setDateProvider therefore does not reach the epoch clock. Faking time means overriding
getEpochClock() on SentryOptions, the way SentryAndroidOptions already overrides
getMonotonicClock(). There is no setEpochClock because nothing consumes it yet.

💚 How did you test it?

./gradlew :sentry:test — 3551 tests, 0 failures. spotlessApply apiDump clean; the .api diff
against the merge base is additions only, with no <init> leaks.

14 new tests on AnchoredClock, including the ones that were impossible to write before:

• step the epoch clock backwards and forwards after taking the anchor, and assert projected instants
  and the differences between them do not move
• tickOf inverts a projection exactly, and throws for a bare instant and for another anchor's instant
• a millisecond anchor still projects nanoseconds
• driftNanos() is zero while the wall clock keeps pace, and reports the signed size of a step

📝 Checklist

• I added GH Issue ID & Linear ID
• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.
• Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

SentryTracer creates one AnchoredClock per transaction, before its root Span, and every Span
below projects from that anchor. Span then holds two Timestamps instead of two SentryDates,
serialization reads end().epochNanos() instead of laterDateNanosTimestampByDiff, and the two
sentinel hacks call anchor.tickOf(...). That retires laterDateNanosTimestampByDiff,
SentryNanotimeDate's diff/compareTo/nanotimeDiff overrides,
SentryAutoDateProvider/SentryInstantDate, and two SentryDate allocations per span endpoint.

Two things that PR has to settle, flagged here so they get argued before code exists:

• Clock base. Choreographer hands us frame timestamps in the System.nanoTime() timebase, while
  AndroidMonotonicClock is SystemClock.elapsedRealtimeNanos(); the two differ by accumulated
  suspend. The plan is to keep a single MonotonicClock and put that last hop inside
  SpanFrameMetricsCollector, which already has an onSpanStarted hook to capture both readings and
  can detect sleep by comparing the deltas — skipping attribution honestly rather than returning a
  plausible-but-wrong projection.
• v9 gating. Eager projection moves every child span's start_timestamp by sub-millisecond
  amounts (root spans are unaffected — the anchor is read at root start). Under the "serialized values
  are frozen until the major" rule that puts the flip behind v9, even though it is an improvement.

Separately, JAVA-572's original subject — the tracer idle/deadline timeout — is stale on the timer half
(SentryTracer already uses getTimerExecutorService()), but "clamp the finish timestamp when the
deadline fires late" is still real and is the actual fix for the multi-hour ui.load artifact. It
wants its own ticket. QueuedThreadPoolExecutor's wall-clock backoff is internal control flow, so it
can be fixed before the major, like #6030.

⚠️ Merge this PR using a merge commit (not squash), so the rest of the stack keeps a clean history.

[linear-code]

JAVA-572

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against d484855

[sentry]

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.55.0 (1)	release

⚙️ sentry-android Build Distribution Settings

[0xadam-brown]

Nice! 🥇

Some comments for your consideration. (Apologies in advance for the doc suggestions, but hope they'll be helpful in a cut-and-paste way – seems worthwhile one-up the clanker because these APIs are so important.) Looking great though 💯

[0xadam-brown]

Thanks! Responded to your major questions here, but nothing that has to block us 👍