TrueTime API (Clock Uncertainty Interval)

Conventional NTP-synchronized clocks return a point estimate with an unbounded and unknowable error. TrueTime instead returns TT.now() -> [earliest, latest], an interval derived from hardware time sources (GPS receivers and atomic clocks distributed across datacenters) combined with a rigorously bounded worst-case drift rate (Spanner’s original implementation bounded epsilon at ~7ms average, capped near 1-7ms in steady state). Every timestamp assignment in the system is accompanied by an explicit uncertainty bound, and the system architecture is built around never trusting a timestamp until the uncertainty window has provably elapsed.

The mechanism that makes this useful is commit-wait. When a transaction commits with timestamp s, the coordinator does not release the commit acknowledgment until TT.after(s) is true — i.e., until TT.now().earliest > s. This guarantees that by the time any client can observe the effects of the transaction, real time has actually advanced past s on every node in the system, regardless of local clock skew. This is what enables Spanner’s external consistency guarantee: if transaction T2 starts after T1 commits (in real time), T2 is guaranteed to see T1’s effects, without any cross-shard locking or consensus round dedicated purely to time agreement.

The architectural cost is real and non-negotiable: commit latency is lower-bounded by 2 * epsilon, so the entire system’s tail latency is hostage to the tightness of the uncertainty bound. This is why TrueTime is inseparable from specialized hardware — GPS/atomic clock reference stations (‘time masters’) per datacenter, with client-side daemons (timeslaved) polling multiple masters and applying a bounded worst-case drift extrapolation between polls. A time master failure, GPS antenna fault, or leap-second mishandling doesn’t cause incorrect answers (the interval semantics are safety-preserving), but it does widen epsilon and directly inflates commit-wait latency across the fleet — a textbook case of a non-functional infrastructure dependency leaking directly into transactional throughput.

The broader lesson generalized beyond Spanner: uncertainty-bounded time is a strictly more powerful primitive than a Hybrid Logical Clock for enforcing external consistency, because HLC only orders observed causal relationships via message passing, whereas TrueTime bounds the relationship between logical timestamps and unobserved real-world concurrency. Systems like CockroachDB explicitly forgo TrueTime hardware and instead accept a hybrid approach — HLC plus an uncertainty interval bounded by max clock offset — which trades commit-wait latency for a weaker (but still practically sufficient) guarantee, and requires read-side uncertainty restarts when a transaction’s read timestamp falls inside another transaction’s ambiguity window.