Notesdistributed🌱 seedling
Hybrid Logical Clock
Also: HLC · Hybrid Clock · Logical Physical Clock
A timestamp (l, c) where l is the largest physical time a node has seen and c is a counter for events sharing that l. It respects causality like a Lamport clock and stays within the clock skew of physical time.
Why it exists
Databases want timestamps that respect causality (for MVCC snapshots) and also mean something in wall-clock terms ("read as of 10:00:05"), without buying atomic clocks.
How it works
- Send or local event: l = max(l, pt). If l didn't change, c += 1; else c = 0.
- Receive (l_m, c_m): l = max(l, l_m, pt); c is the max of the tied counters + 1, or 0 if physical time won outright.
- Guarantees a → b ⇒ HLC(a) < HLC(b), and l − pt never exceeds the clock skew ε.
- c stays small: it only counts while physical time lags, and resets when it catches up.
- Fits in 64 bits (48 for l, 16 for c), so it can replace a physical timestamp in place.
Trade-offs
| Gains | Costs |
|---|---|
| causality-safe, close to wall time | no error bound: unrelated events on skewed nodes can still be misordered in real time |
| commodity NTP is enough | correctness depends on a configured maximum offset; nodes outside it must be removed |
| compact | needs uncertainty windows (read restarts) to avoid stale reads |
In practice
- CockroachDB: HLC timestamps; reads carry an uncertainty interval of the max clock offset (500 ms default) and restart when they see a value inside it. A node out of sync with at least half the cluster by 80% of the max offset shuts down. It doesn't promise linearizability for transactions on unrelated keys.
- MongoDB: a signed hybrid logical cluster time since 3.6, used for causally consistent sessions.
- YugabyteDB uses HLCs and, since 2.23, can take clock error bounds from AWS ClockBound to shrink its uncertainty window.
Pitfalls
- Treating an HLC as TrueTime. It tracks causality, not real-time bounds.
- A node with a wildly fast clock drags every HLC it talks to forward; enforce a max offset.
Connections
- Part of
- Lamport Clock
- Contrasts with
- TrueTime
- In real systems
- CockroachDBMongoDB
Recall
These cards are also in your review deck, scheduled with spaced repetition.