feat(time): Add uptime and elapsed-real-time clock abstractions (JAVA-571)

[runningcode]

📜 Description

Adds a clock abstraction to io.sentry.time. This just adds the new APIs. They are never called.

Here's a list of what is added (indents for class hierarchy).

Ticker                    long tickNanos()  — base; "a nanosecond counter with an arbitrary origin"
  UptimeClock             excludes deep sleep  (CLOCK_MONOTONIC / System.nanoTime())
  ElapsedRealtimeClock    includes deep sleep  (CLOCK_BOOTTIME on Android)
JavaUptimeClock, JavaElapsedRealtimeClock     singletons
AndroidElapsedRealtimeClock                   SystemClock.elapsedRealtimeNanos()
Deadline, Stopwatch                           take a Ticker

We also add TestTicker in sentry-test-support that advances by an amount and a unit to make testing easier.

To help review the new APIs with concrete use cases, of these new APIs that aren't called in this PR, I created draft PRs. Please don't review these yet, since I haven't fully reviewed it myself but here they are so you can see the new APIs:

• Usages of Deadline and ElapsedRealtimeClock: fix(android): Treat an unpopulated connection cache as stale (JAVA-717) #6029 and ref(transport): Measure rate-limit backoff on a monotonic clock (JAVA-574) #6030
• Usages of Stopwatch and JavaUptimeClock: ref(checkin): Measure check-in durations with Stopwatch (JAVA-576) #6032

There is deliberately nothing platform-specific for UptimeClock: System.nanoTime() is already CLOCK_MONOTONIC on Android and SystemClock.uptimeNanos() is API 34 against a minSdk of 21, so there is no second implementation to write. Call sites resolve JavaUptimeClock.getInstance() directly.

Elapsed real time is the one that differs per platform — RateLimiter lives in the core module but needs CLOCK_BOOTTIME on Android, which only sentry-android-core can supply. That arrives as an override on SentryAndroidOptions rather than a setter, so there is no mutation point on an internal option, and Android is correct from construction rather than from the moment AndroidOptionsInitializer runs. Consumers that take a clock in their constructor, as RateLimiter will, keep their own injection point for tests. The Android clock ships here rather than with its first consumer so the abstraction is not inert on the platform that motivated it; nothing reads it yet, so it changes no behavior.

Everything is @ApiStatus.Internal, so nothing here is a public contract.

💡 Motivation and Context

ICurrentDateProvider.getCurrentTimeMillis() has two implementations that mean different things: CurrentDateProvider returns wall time, AndroidCurrentDateProvider returns SystemClock.uptimeMillis(), which is monotonic and pauses in deep sleep. Every consumer hand-picks the one matching whatever it compares against; a wrong pairing compiles silently, and the tests inject fakes so nothing catches it.

Naming the guarantee is the fix. A class declaring UptimeClock can no longer be handed an elapsed-real-time one, and vice versa. The distinction is not academic: ANR detection compares against uptimeMillis() precisely so that a suspended device does not look like a blocked main thread on CLOCK_BOOTTIME, a 30 s suspend would fabricate a 30 s ANR.

Deadline and Stopwatch exist so callers never do arithmetic on raw ticks. Three decisions worth reviewing:

• Deadline.passed() gives "not populated yet" a representation outside the numeric range — 0 is a real and very recent instant on any boot-relative clock.
• hasPassed() subtracts rather than compares, so it holds for a negative or wrapping origin.
• remaining() rounds up, so a caller scheduling work for it never wakes to find the deadline still standing.

• resolves: JAVA-571 (partially — this is the API, not the migration)

💚 How did you test it?

Unit tests!

📝 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

This is the first of six pre-v9 PRs; the rest convert call sites whose current semantics are preserved:

1. This PR — the clock types and the options seam
2. Android connection-status cache → the clock added here (fixes JAVA-717, where 0 meant "unset" on a boot-relative clock)
3. RateLimiter → ElapsedRealtimeClock (JAVA-574)
4. All four check-in duration paths → UptimeClock (JAVA-576)
5. ANR thresholds → UptimeClock (JAVA-579)
6. Deprecate ICurrentDateProvider, DateUtils.getCurrentDateTime() and AndroidDateUtils (JAVA-571)

Everything that changes a serialized measurement — span and transaction durations, session durations, app-start spans, replay and profiler timings — is deliberately held for v9.

[linear-code]

JAVA-571

JAVA-717

[github-actions]

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

Generated by 🚫 dangerJS against 058d5c4

[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