|
| 1 | +package io.sentry.time; |
| 2 | + |
| 3 | +import org.jetbrains.annotations.ApiStatus; |
| 4 | +import org.jetbrains.annotations.NotNull; |
| 5 | + |
| 6 | +/** |
| 7 | + * One wall-clock reading pinned to one monotonic tick, from which related instants are projected. |
| 8 | + * |
| 9 | + * <p>Exists because a group of instants that will be compared against each other — the spans of a |
| 10 | + * transaction, the samples of a profile chunk, the frames of a replay segment — must not each read |
| 11 | + * the wall clock. Two independent readings differ by whatever the device's clock did in between, so |
| 12 | + * a duration taken across them can shorten, lengthen or go negative, and a child can appear to |
| 13 | + * start before its parent. Reading the epoch once and projecting the rest through {@link |
| 14 | + * MonotonicClock} makes every instant in the group an image of the same tick origin, which is what |
| 15 | + * makes subtracting any two of them monotonic by construction rather than by convention. |
| 16 | + * |
| 17 | + * <p>That is what the span protocol needs. It carries a start and an end instant and no duration |
| 18 | + * field, so the server subtracts them; both endpoints coming from one anchor is the only way that |
| 19 | + * subtraction reports measured time rather than whatever the clock did. |
| 20 | + * |
| 21 | + * <p>Projection also buys resolution the wall clock does not have. On Android the epoch is |
| 22 | + * millisecond-granular, so an instant read directly is truncated, whereas one projected from a tick |
| 23 | + * carries nanoseconds. This is the workaround {@link io.sentry.SentryNanotimeDate} describes, |
| 24 | + * applied once per group instead of between each pair of readings. OpenTelemetry's SDK anchors per |
| 25 | + * local root span for the same two reasons. |
| 26 | + * |
| 27 | + * <p>The cost is that a projection drifts from real wall time as the anchor ages: it reports what |
| 28 | + * the clock said when the anchor was taken, plus measured time, so a clock step afterwards is |
| 29 | + * invisible to it. Anchor something short-lived and bounded, and use {@link #driftNanos()} to |
| 30 | + * observe the gap rather than assume it away. |
| 31 | + */ |
| 32 | +@ApiStatus.Internal |
| 33 | +public final class AnchoredClock { |
| 34 | + |
| 35 | + private final @NotNull EpochClock epoch; |
| 36 | + private final @NotNull MonotonicClock clock; |
| 37 | + private final long epochNanos; |
| 38 | + private final long anchorTick; |
| 39 | + |
| 40 | + private AnchoredClock( |
| 41 | + final @NotNull EpochClock epoch, |
| 42 | + final @NotNull MonotonicClock clock, |
| 43 | + final long epochNanos, |
| 44 | + final long anchorTick) { |
| 45 | + this.epoch = epoch; |
| 46 | + this.clock = clock; |
| 47 | + this.epochNanos = epochNanos; |
| 48 | + this.anchorTick = anchorTick; |
| 49 | + } |
| 50 | + |
| 51 | + /** Takes the anchor now: one epoch reading, one tick, as close together as a call allows. */ |
| 52 | + public static @NotNull AnchoredClock create( |
| 53 | + final @NotNull EpochClock epoch, final @NotNull MonotonicClock clock) { |
| 54 | + return new AnchoredClock(epoch, clock, epoch.now().epochNanos(), clock.tickNanos()); |
| 55 | + } |
| 56 | + |
| 57 | + /** The anchor itself — the one instant here that was read rather than projected. */ |
| 58 | + public @NotNull Timestamp start() { |
| 59 | + return Timestamp.anchoredAt(epochNanos, this); |
| 60 | + } |
| 61 | + |
| 62 | + public @NotNull Timestamp now() { |
| 63 | + return at(clock.tickNanos()); |
| 64 | + } |
| 65 | + |
| 66 | + /** |
| 67 | + * The instant a tick corresponds to, for placing something already measured on this clock — a |
| 68 | + * frame, a profiler sample — on the same timeline as the instants projected here. |
| 69 | + */ |
| 70 | + public @NotNull Timestamp at(final long tickNanos) { |
| 71 | + return Timestamp.anchoredAt(epochNanos + (tickNanos - anchorTick), this); |
| 72 | + } |
| 73 | + |
| 74 | + /** |
| 75 | + * The tick an instant was projected from. Exact, and reads no clock: projection adds a tick |
| 76 | + * difference to a fixed epoch, so it inverts by subtraction. |
| 77 | + * |
| 78 | + * @throws IllegalArgumentException if this clock did not project the instant. Its epoch then |
| 79 | + * bears no arithmetic relation to these ticks, and converting it would silently produce a |
| 80 | + * tick derived from a wall-clock difference. |
| 81 | + */ |
| 82 | + public long tickOf(final @NotNull Timestamp timestamp) { |
| 83 | + if (timestamp.anchor() != this) { |
| 84 | + throw new IllegalArgumentException( |
| 85 | + "Timestamp was not projected by this AnchoredClock: " + timestamp); |
| 86 | + } |
| 87 | + return anchorTick + (timestamp.epochNanos() - epochNanos); |
| 88 | + } |
| 89 | + |
| 90 | + /** |
| 91 | + * How far this anchor's projection has fallen behind or ahead of the wall clock, in nanoseconds. |
| 92 | + * |
| 93 | + * <p>Zero means the wall clock has advanced by exactly the time this clock measured. Anything |
| 94 | + * else is a clock step, or — where {@link MonotonicClock} and the wall clock disagree about |
| 95 | + * suspend — device sleep. Read the epoch and the tick in the same order as {@link #create} so |
| 96 | + * that the gap between the two reads biases the result the same way it biased the anchor. |
| 97 | + */ |
| 98 | + public long driftNanos() { |
| 99 | + final long wallElapsed = epoch.now().epochNanos() - epochNanos; |
| 100 | + final long measuredElapsed = clock.tickNanos() - anchorTick; |
| 101 | + return wallElapsed - measuredElapsed; |
| 102 | + } |
| 103 | +} |
0 commit comments