feat(time): Add Timestamp, Timing and EpochClock (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, Timing and EpochClock, built on the
MonotonicClock/Stopwatch primitives from #6028. Nothing calls any of it yet, exactly like #6028.

Timestamp   // an epoch instant. No arithmetic between instants.
Timing      // a Timestamp anchor + a Stopwatch, captured together. end() = anchor + duration.
EpochClock  // now() stamps a moment; start() begins something whose duration gets reported.

Timing composes Stopwatch rather than repeating it, so there is one implementation of a
monotonic delta and Timing owns exactly one operation of its own — end(). Both measure on
MonotonicClock, which counts deep sleep: an interval that excluded it, paired with wall-clock
anchors, would produce an end() that falls further behind real time the longer the device
sleeps.

SentryOptions.getEpochClock() is the injection point. SystemEpochClock reads the epoch itself
rather than going through SentryDateProvider — see below.

💡 Motivation and Context

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 (SentryLongDate, from OTel and the app-start projection). Nothing in the type separates
them, so the guarantees are decided by the runtime class of both operands:

public long diff(final @NotNull SentryDate otherDate) {
  if (otherDate instanceof SentryNanotimeDate) {
    return nanos - ((SentryNanotimeDate) otherDate).nanos;   // monotonic
  }
  return super.diff(otherDate);                              // wall subtraction
}

What that costs today:

• Durations mean different things per platform. The default SentryAutoDateProvider picks
  SentryInstantDate on JVM 9+, which has no monotonic component at all, while Android forces the
  nanotime provider. Span durations are monotonic on Android and wall-derived on the JVM, where a
  clock step mid-span can make one negative.
• The hidden tick leaks out by sentinel hack. SpanFrameMetricsCollector recovers it with
  date.diff(new SentryNanotimeDate(0, 0)), and DriverSpans.computeNanoStartTimestampForChild
  returns null — dropping SQLite sub-span nesting — whenever the date isn't a SentryNanotimeDate.
• The wrong clock reaches control flow. QueuedThreadPoolExecutor.didRejectRecently() is
  dateProvider.now().diff(lastReject): monotonic on Android, wall clock on the JVM.

The split here is along the line that actually matters — whether a value means anything outside this
process. A MonotonicClock tick never does; a Timestamp always does. Conflating those is what put
System.nanoTime() and unixDateMillis in the same object with no way for a caller to tell which
one they were getting.

• 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 therefore byte-identical to what the provider would have returned 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, because a Timing
measures on the monotonic clock instead.

setDateProvider consequently does not reach the epoch clock. Faking time for a future consumer
means overriding getEpochClock() on SentryOptions, the way SentryAndroidOptions already
overrides getMonotonicClock(). There is no setEpochClock because there is nothing to
configure it for yet.

The bridge still cannot run the other way. Reimplementing SentryDateProvider on top of
EpochClock would change serialized values today: SentryNanotimeDate carries System.nanoTime()
as its tick, the two sites above compare that tick against System.nanoTime() directly, and a
Timing measures on the monotonic clock, which counts deep sleep. Swapping the tick source would
change span durations across deep sleep and break both comparisons, so it waits for the major.

💚 How did you test it?

./gradlew :sentry:test :sentry:apiCheck — green. 10 new tests covering the anchor being kept, the
end tracking the clock across reads, the duration surviving a wall-clock jump, and SystemEpochClock
anchoring on the wall clock while measuring on the clock it was given.

.api diff is additions only.

📝 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

Stage 2, at the major: Span/SentryTracer hold a Timing, serialization uses start()/end()
instead of laterDateNanosTimestampByDiff, the two sentinel hacks get a supported accessor, and JVM
durations become monotonic. Stage 3 retires SentryDate.diff, SentryNanotimeDate,
SentryInstantDate, SentryAutoDateProvider and SentryLongDate — including the open question of
whether SentryDate shrinks into Timestamp rather than the two coexisting.

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 7255d5e

[sentry]

📲 Install Builds

Android

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

⚙️ sentry-android Build Distribution Settings