docs(time): Steer new measurements at the io.sentry.time clock APIs (#6088)

* docs(time): Steer new measurements at the io.sentry.time clock APIs

Document on each singleton clock's getInstance() that callers should read
the ticker or wall clock off the options object instead, so they get the
per-platform implementation rather than pinning themselves to one. Calling
JavaMonotonicTicker.getInstance() on Android is the trap worth naming: it
stops counting through a device suspend, so intervals spanning a deep sleep
come out short.

Add an AGENTS.md section so new measurement code reaches for io.sentry.time
rather than DateUtils.getCurrentDateTime() or a SentryDateProvider, picks the
abstraction by what the number is for, and treats adding a new abstraction as
a deliberate step rather than a way around an awkward call site.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(time): Shorten the Measuring Time section in AGENTS.md

Name the legacy clock interfaces instead of listing their
implementations, which also covers ICurrentDateProvider. Drop the
table's notes column and the history of why the old types remain, and
cut the two rules to a sentence each. The getInstance() Javadoc already
carries the detail where callers see it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(time): Shorten the getInstance() Javadoc on the clock singletons

Drop the paragraph on when getInstance() may still be called directly.
Only the options accessors and test support do, so it restated the
code. Keep the one reason that matters: JavaMonotonicTicker stops
counting while an Android device is suspended.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: runningcode

AGENTS.md

@@ -213,6 +213,29 @@ Two more rules that catch most of the rest:
 
 Prefer `AutoClosableReentrantLock` over `synchronized`, matching the rest of the codebase.
 
+### Measuring Time
+
+**New code that reads a clock uses `io.sentry.time`**, not `System.currentTimeMillis()`,
+`System.nanoTime()`, `SystemClock`, `DateUtils.getCurrentDateTime()`, a `SentryDateProvider`, or an
+`ICurrentDateProvider`. Those are legacy, not a precedent to follow.
+
+Pick the type by what the number is for:
+
+| You need | Use |
+|---|---|
+| An instant that leaves the process (event, breadcrumb, session) | `EpochClock` → `Timestamp`. Never subtract two of them |
+| How long something took | `Stopwatch` |
+| Whether a window has elapsed (TTL, backoff, timeout) | `Deadline` |
+| Several instants compared with each other (spans of a transaction) | `AnchoredClock` |
+| A raw tick, when none of the above fits | `MonotonicTicker` |
+
+Get the clock from `options.getEpochClock()` or `options.getMonotonicTicker()`, not a
+`getInstance()`: on Android the ticker keeps counting through device suspend, and `System.nanoTime()`
+does not. Take it as a constructor parameter; tests use `TestMonotonicTicker` instead of sleeping.
+
+If none of these fits, propose a new type, and the clock bug it makes impossible, before writing
+call sites against it. Don't inline raw tick arithmetic as a stopgap.
+
 ### Testing Requirements
 - Write comprehensive unit tests for new features
 - Android modules require both unit tests and instrumented tests where applicable

sentry-android-core/src/main/java/io/sentry/android/core/internal/time/AndroidMonotonicTicker.java

@@ -16,6 +16,7 @@ public final class AndroidMonotonicTicker implements MonotonicTicker {
 
   private static final AndroidMonotonicTicker instance = new AndroidMonotonicTicker();
 
+  /** Prefer {@link io.sentry.SentryOptions#getMonotonicTicker()}; on Android it returns this. */
   public static @NotNull MonotonicTicker getInstance() {
     return instance;
   }

sentry/src/main/java/io/sentry/time/JavaMonotonicTicker.java

@@ -9,6 +9,11 @@ public final class JavaMonotonicTicker implements MonotonicTicker {
 
   private static final JavaMonotonicTicker instance = new JavaMonotonicTicker();
 
+  /**
+   * Prefer {@link io.sentry.SentryOptions#getMonotonicTicker()}, which picks the platform's ticker.
+   * On Android this one stops counting during device suspend, so intervals spanning a deep sleep
+   * come out short.
+   */
   public static @NotNull MonotonicTicker getInstance() {
     return instance;
   }

sentry/src/main/java/io/sentry/time/SystemEpochClock.java

@@ -24,6 +24,10 @@ public final class SystemEpochClock implements EpochClock {
 
   private static final SystemEpochClock instance = new SystemEpochClock();
 
+  /**
+   * Prefer {@link io.sentry.SentryOptions#getEpochClock()}, which is where a platform would
+   * substitute its own wall clock, the way Android already substitutes the ticker.
+   */
   public static @NotNull EpochClock getInstance() {
     return instance;
   }