Skip to content

Hybrid Logical Clock

Timestamp artifact — instantiates Shared-State Consistency Contract Design

A timestamp that fuses physical wall-clock time with a logical counter, so events get an ordering that tracks real time yet never contradicts causality despite clock skew.

A Hybrid Logical Clock (HLC) is a compact timestamp — a (physical-time, logical-counter) pair — attached to each event so that timestamps both approximate real time and respect causality. Its distinguishing trick is to get the best of two worlds a designer usually has to choose between: pure physical clocks are human-meaningful but drift and run backwards (breaking causality), while pure logical (Lamport) clocks respect causality but are unmoored from real time. HLC advances with the wall clock when it can, but bumps its logical counter whenever it must to stay monotonic and to dominate the timestamp of any message it receives — so two causally-ordered events always compare correctly even when the machines' physical clocks disagree.

Example

A distributed SQL database spread across three datacenters needs to order transactions so that if transaction T2 reads T1's write, T2's commit timestamp is greater than T1's. It cannot trust raw server clocks — a few milliseconds of skew would let a "later" transaction get an earlier physical timestamp and corrupt the order. Each node runs an HLC. When it commits T1 it stamps (physical ≈ 10:00:00.000, logical 0). A node whose wall clock reads 9:59:59.998 but which then receives T1's write updates its HLC to (10:00:00.000, logical 1), so T2's commit is guaranteed to sort after T1's. Real time is tracked closely enough for TTLs and debugging, and causality is never violated even though the physical clocks were a hair apart.

How it works

The distinctive property is that it bounds divergence from physical time while guaranteeing the causal property, all in a fixed-size token. On a local event, the HLC takes the maximum of its last value and the current physical clock, incrementing the logical part on ties. On receiving a message, it takes the maximum of its own clock, the message's timestamp, and physical time — again bumping the counter to break ties — so the received event's clock strictly dominates its cause. The logical counter grows only when physical time fails to (skew or ties), and it stays near zero as long as clocks are roughly synchronized.

Tuning parameters

  • Max clock-skew assumption — the tolerated bound between nodes' physical clocks; a larger assumed bound is safer against reordering but forces larger uncertainty waits wherever recency matters.
  • Counter width — bits for the logical part; more headroom survives bursts and large skew before overflow, at a slightly larger token.
  • Physical-time source — ordinary NTP vs. a tighter time service; better synchronization keeps the logical counter small and timestamps closer to real time.
  • Anomalous-clock clamp — whether to reject or cap a wildly wrong incoming physical time, so one bad clock cannot poison its peers.

When it helps, and when it misleads

Its strength is delivering causally-correct, roughly-real-time ordering cheaply and without a central sequencer, which is why it underpins several production distributed databases. But its correctness rests on an assumption: that physical clock skew stays within an assumed bound. If a node's clock jumps far outside that bound, HLC still preserves causality, but its "real time" meaning degrades, and any logic that treats the timestamp as true wall-clock recency can be fooled.[1] The classic misuse is using HLC timestamps as if they were exact real time — for security expiries or cross-system ordering — rather than as a causal-plus-approximate order. The discipline is to make the max-skew assumption explicit and monitored, and to treat the timestamp as an ordering token, not ground-truth time.

How it implements the components

  • version_token — an HLC value is the version/ordering token stamped on each event and compared to establish precedence.
  • fault_partition_and_clock_assumptions — its design encodes a specific clock model (bounded skew, monotonic advance) and makes that assumption the explicit basis of its guarantee.

It stamps and orders events but does not decide what to do with the order: choosing a winner among concurrent writes is Last-Write-Wins Register's, enforcing causal visibility is Causal-Consistency Protocol's, and tracking exact per-replica concurrency is Version Vector's.

References

[1] Hybrid Logical Clocks (Kulkarni and colleagues) combine Lamport's logical clocks with physical time so that timestamps stay close to real time while never violating happens-before; they are used in systems such as CockroachDB and MongoDB. The guarantee assumes bounded clock skew — a stated assumption, not a free one. ↩