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 005fa73

[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]

If you're up for improving on the clanker, maybe something like:

 * An {@link EpochClock} and a {@link MonotonicClock} that together let us generate multiple {@link
 * Timestamp}s (aka, instants) that share a common epochal anchor.
 *
 * <p>Lets us:
 *
 * <ol>
 *   <li>safely create accurate interval timings (e.g., for spans) by avoiding clock drift, NTP
 *       resets, or other sources of skew that intervals are subject to when they're computed from
 *       multiple wall clock readings; and
 *   <li>produce intervals with nanosecond precision.
 * </ol>
 *
 * <p>(Item (2) especially helpful on Android, as nano-precise system time is only available for API
 * 33+.)
 *
 * <p>Because {@code AnchoredClock} uses a single epochal time source, the timestamps it generates
 * are accurate relative to one another, but are always subject to any initial inaccuracy of the
 * epochal anchor. The {@link #driftNanos} method lets you estimate that inaccuracy by comparing
 * against more current wall clock readings.

Up to you of course...

(If your curious, you can see the comment here for one of the unexpected – and impactful – consequences of not having (2).)

[0xadam-brown]

l: My vote would be for started() here, since we're returning a timestamp from the past rather than staring a timer.

[runningcode]

I'm following Guava's convention here where static methods have the ed ending and instance methods don't.
I do see your point that this isn't the best name though as it doesn't distinguish between this and now(). I've updated to origin() to make it more clear what it does.

[0xadam-brown]

...or really, the relative distance between the original anchor wall clock time and an updated reading of that wall clock. (To my ear, the current wording makes it sound like any returned value besides 0 means the anchor has become less accurate relative to "true time", when it could have been perfectly accurate to begin with and has since skewed.)

...which raises the more fundamental question: How exactly do we expect folks to use this method? Do we plan on taking a bunch of these measures and using a computed average (or whatever) to offset what we actually report to Relay?

[runningcode]

This is a good point. I had a branch where I was using it to attach metadata to spans (we could also calculate sleep time by subtracting the difference of the two monotonic clocks) but both blow up the scope significantly. I will remove this!

[0xadam-brown]

l: Not quite sure I understand what "a clock step" means, and I'm skeptical that we can claim "anything else" is caused by one of these two things. (Clankers gonna clank, apparently.)

[0xadam-brown]

l: Worth mentioning that this can return negative values.

[runningcode]

good point!

[0xadam-brown]

Maybe:

 * A source of wall-clock {@link Timestamp}s (aka, instants).
 *
 * <p>This class should <b>not</b> be used to compute durations. Instead, see {@link AnchoredClock}
 * if you need shareable timestamps for an interval's start and end point, or {@link Deadline} if
 * you need a monotonic endpoint. 

Again, up to you – but could be worth avoiding the clanker for these Javadocs as clarity is esp valuable for such central APIs.

[runningcode]

I think the wording on "will leave this process" is important. i'll add your point about not computing durations but otherwise i thought the existing comment was good.

[0xadam-brown]

l: Thoughts about an API like this instead:

InstantUtils.toEpochNanos(Instant)

...fwiw, that^^ seems a bit more intuitive to me than InstantEpochNanos.read(), and it also lets callers supply their own Instant made at call time or at some other time.

Up to you of course.

[runningcode]

The issue with callers supplying their own Instant is that it won't compile since we still have min SDK < 26. I also personally dislike classes named with Utils after working at Square ;)

[0xadam-brown]

m: This is surprising to me, as I'd expect the dependency to be solely from AnchoredClock -> Timestamp, rather than circular. It's also an instance that can't be gc'd when it otherwise might be.

Thoughts about living without this field? Or do we really need AnchoredClock.tickOf() (its sole caller at present via Timestamp.anchored())?

Not sure about what you had in mind for tickOf() and anchored(), but maybe we could live with a general purpose tickOf() that returns a long based on its AnchoredClock without caring where it came from / trusting the caller?

[runningcode]

This is a good point. 😄 There are two design decisions that impact this here. The second one we discussed on the call but I'll repeat it here.

Choice one: Ability to verify we are comparing against the same anchor
Without this, we don't have any way to check that two timestamps are being compared against the same anchor. Otherwise the timestamps are not relative to each other and the comparison is invalid.

Choice two: Single anchor or multiple anchors
An alternative design would have been where we have a single Anchor for the entire process. In that world, we don't need a way to check that we are comparing two Timestamps against the same anchor. We made the choice here to have multiple anchors. The idea was to make it easier to mesh with our current span design.

If it helps understand how the anchor method is used, check the usage here: https://github.com/getsentry/sentry-java/pull/6055/changes#diff-8fb51c60f3cd9eba198cd0702cf5b06a1b4e0ff676dccaa371840a44a5a5bd8eR334

I didn't follow your point about GC, can you explain it to me?

If we do reverse the dependency, what data structure would we use to keep track of all the Timestamps in clock and make it thread safe?

[0xadam-brown]

l: Curious as to why we evaluate lazily here but not for the monotonic clock exposed via SentryOptions?

[runningcode]

that's slop, thanks for pointing this out.

[0xadam-brown]

m: Similarly to here, do we want to expose this via SentryOptions, or just AnchoredClock instead?

[runningcode]

I understand that there's no PR right now that uses this so maybe it is confusing.

There are some uses cases where we want an epoch to serialize from EpochClock.now() for example in Breadcrumb and SentryEvent. Do you mean to not expose this and then all the callers grab a singleton directly from whichever implementation of EpochClock they need?

[0xadam-brown]

There are some uses cases where we want an epoch to serialize from EpochClock.now() for example in Breadcrumb and SentryEvent.

That sounds a good enough reason to expose this to me. (Just wanted to make sure we had considered whether hiding some of these abstractions was possible / desired. No concerns about exposing them if we have specific use cases supporting it.)