Monotonic and Wall Readings

## One value, two clocks An operating system exposes two different notions of time. The **wall clock** (also called the time-of-day clock) answers "what is the date and time right now?" It is the one that can be corrected: a time-synchronisation daemon can slew it or step it, an administrator can set it, a virtual machine can resume with a stale clock. The **monotonic clock** answers "how much time has passed?" It counts from an arbitrary, meaningless origin — usually something like boot or process start — and is guaranteed never to go backwards. Most languages make you choose between two different functions. Go does not. `time.Now()` returns a single `time.Time` value that contains **both** readings, and the standard library decides which one an operation should use. ## Telling time versus measuring time The rule the `time` package documents is: the wall clock is for telling time, the monotonic clock is for measuring time. - Operations that **tell** you the time — formatting the value, asking for its year or hour, interpreting it in a location — use the wall-clock reading. - Operations that **measure** — `t.Sub(u)`, `t.Before(u)`, `t.After(u)`, `t.Equal(u)`, `t.Compare(u)` — use the monotonic readings, **provided both values carry one**. If either operand has no monotonic reading, these operations fall back to the wall-clock readings. `time.Since(start)` is defined as the elapsed time since `start`, and `time.Until(deadline)` as the time remaining; both are built on `Sub`, so both inherit the monotonic behaviour. In the common case — you captured `start` with `time.Now()` in this process, and you call `time.Since(start)` in the same process — the subtraction is a pure monotonic subtraction and a clock correction in between cannot corrupt it. ## Seeing the monotonic reading The monotonic reading has no textual format of its own: there is no layout element for it, and it is deliberately omitted from every serialised form. But the `String` method includes it for debugging, so printing a value shows something like: ``` 2026-09-02 10:04:05.123456789 +0000 UTC m=+0.000123456 ``` Everything up to `UTC` is the wall-clock reading; the `m=+0.000123456` tail is the monotonic reading expressed as an offset in seconds from the process's monotonic origin. The presence or absence of that suffix is the fastest way to check whether a particular value will be compared monotonically. A value with no suffix has only a wall-clock reading. ## Why the origin is meaningless The monotonic reading is only comparable **inside one process on one machine**. Its zero point is arbitrary, it is not an epoch timestamp, and it cannot be compared with a monotonic reading taken by another process or another host. That is exactly why Go hides it: you never read it as a number, you only ever subtract two `time.Time` values that both have one. It is also why every encoding of a `time.Time` drops it — sending it anywhere would be sending a number that means nothing at the other end. ## The practical consequence For everyday code this means: ```go start := time.Now() doWork() elapsed := time.Since(start) ``` is already the correct way to measure a duration in Go. You do not need to reach for a separate high-resolution timer, and you do not need to defend against the clock being adjusted — as long as `start` is a value you obtained from `time.Now()` and kept as a `time.Time`, without passing it through any operation that discards the monotonic reading. Converting it, rounding it, or serialising and reloading it quietly turns the measurement back into a wall-clock subtraction, which is where the surprising results come from.