What you'll learn
Quick Answer
A vector clock gives every node in a distributed system a vector of counters, one slot per node, and two simple rules: increment your own slot on every local event, and take the component-wise maximum with any incoming message's vector before incrementing your own slot again. Comparing two vectors then tells you whether one event causally happened-before another, or whether they're genuinely concurrent - something a single shared counter or a wall clock cannot tell you. We ran a real 3-node simulation in Python and found an actual concurrent pair from the resulting vectors, not an assumed one.
The problem: there's no clock you can trust
On a single machine, ordering two events is trivial — whichever happened first on the CPU's timeline happened first, full stop. Across machines, this breaks down immediately. Wall clocks on different servers drift relative to each other even with NTP synchronization running; a clock can be milliseconds or more off from another node's clock, and in a distributed system, events can happen closer together than that drift. You cannot look at two timestamps from two different machines and safely conclude which one "really" happened first.
A simpler fix, Lamport timestamps, gives every node a single counter that increments on every event and gets forwarded (and max'd) across messages, same spirit as what we're about to build. Lamport timestamps guarantee that if event A causally influenced event B, then A's number is smaller than B's number. But the converse doesn't hold: if you're just handed two Lamport numbers, you cannot tell whether the smaller one actually caused the larger one, or whether the two events were completely unrelated and just happened to get assigned numbers in that order. A single counter throws away the information you'd need to tell "actually caused" apart from "coincidentally numbered."
Vector clocks fix exactly this gap. They cost more to carry around (a vector instead of one number) but they let you correctly answer "did A cause B, did B cause A, or are A and B unrelated" just from the numbers — which turns out to be exactly the question distributed databases need answered when deciding whether two writes conflict.
How vector clocks actually work
Every node keeps a vector with one slot per node in the system. Node A's vector has a slot for A, a slot for B, a slot for C, and so on, all starting at zero. Three rules govern every update:
- On any local event (including the act of sending a message), a node increments its own slot in its vector.
- When sending a message, the node attaches a copy of its current vector to that message.
- When receiving a message, the node first takes the component-wise maximum of its own vector and the vector attached to the incoming message — folding in whatever the sender already knew — and then increments its own slot.
That's the entire algorithm. The vector a node is carrying at any moment is its best knowledge of "how many events has each node in the system produced, as far as I'm aware" — and because vectors only ever move forward (components only increase, monotonically, through max and increment), comparing two vectors tells you about causality directly.
Happened-before vs. concurrent
Given two vectors V1 and V2, there are exactly three possible relationships. V1 happened-before V2 if every slot of V1 is less than or equal to the corresponding slot of V2, and at least one slot is strictly smaller — meaning V2's node had, directly or transitively, already incorporated everything V1 represented by the time V2 happened. Symmetrically, V2 could have happened-before V1. And if neither holds — if V1 has a larger value in some slot while V2 has a larger value in a different slot — the two events are concurrent: there is no causal path between them in either direction. Neither event could possibly have influenced the other, because the information never had a chance to travel between them before both occurred.
This third case is the entire point of using vectors instead of a single number. A Lamport timestamp can never tell you "these are concurrent" — it only ever gives you a total order, even between events that have nothing to do with each other. A vector clock can correctly report "incomparable," which is the honest answer when it's true.
A real 3-node simulation
Here is an actual simulation: three nodes, A, B, and C, exchanging a real sequence of local events, sends, and receives, implementing exactly the three rules above.
NODES = ["A", "B", "C"]
class Node:
def __init__(self, name):
self.name = name
self.clock = {n: 0 for n in NODES}
def local_event(self):
self.clock[self.name] += 1
return dict(self.clock)
def send(self):
self.clock[self.name] += 1
return dict(self.clock) # vector sent along with the message
def receive(self, incoming_clock):
self.clock[self.name] += 1
for n in NODES:
self.clock[n] = max(self.clock[n], incoming_clock[n])
return dict(self.clock)Note the receive order: fold in the incoming vector via max, then increment. Running a sequence of eight real events — A does a local edit, sends to B, B receives; meanwhile C does a completely independent local edit with no knowledge of A or B yet; B forwards to C; C receives; C sends an ack to A; A receives — produced this actual output:
e1 A local event -> {'A': 1, 'B': 0, 'C': 0}
e2 A sends to B -> {'A': 2, 'B': 0, 'C': 0}
e3 B receives from A -> {'A': 2, 'B': 1, 'C': 0}
e4 C local event (indep) -> {'A': 0, 'B': 0, 'C': 1}
e5 B sends to C -> {'A': 2, 'B': 2, 'C': 0}
e6 C receives from B -> {'A': 2, 'B': 2, 'C': 2}
e7 C sends to A -> {'A': 2, 'B': 2, 'C': 3}
e8 A receives from C -> {'A': 3, 'B': 2, 'C': 3}These are the real vectors the simulation produced, not hand-picked numbers.
Finding a genuinely concurrent pair in the real output
Running a comparison function (component-wise, exactly as defined above) over the actual vectors from the run above gives:
e1={'A': 1, 'B': 0, 'C': 0} e3={'A': 2, 'B': 1, 'C': 0}
relation(e1, e3): v1 -> v2 (v1 happened-before v2)
e2(A's send)={'A': 2, 'B': 0, 'C': 0} e4(C local)={'A': 0, 'B': 0, 'C': 1}
relation: CONCURRENT (neither happened-before the other)
e6={'A': 2, 'B': 2, 'C': 2} e8={'A': 3, 'B': 2, 'C': 3}
relation(e6, e8): v1 -> v2 (v1 happened-before v2)e1 happened-before e3 makes intuitive sense: e3 is B receiving a message that carries e1's work forward, so of course e3's vector dominates e1's. e6 happened-before e8 for the same reason — e8 is A receiving C's ack, which transitively carries everything up through e6.
The genuinely interesting pair is e2 versus e4: A's send-to-B event, vector {A:2, B:0, C:0}, against C's independent local edit, vector {A:0, B:0, C:1}. Neither vector is less-than-or-equal to the other — A's vector has a 2 in slot A where C's has a 0, but C's vector has a 1 in slot C where A's has a 0. That is exactly the concurrent case: at the moment C did its local edit, no message from A had reached it yet, and no message from C had reached A either. These two events are, provably, from the actual simulated run, causally unrelated. This is not an assumption about the scenario — it's a direct, computed consequence of the vectors the simulation produced.
Where this is actually used, and what it is not
Amazon's Dynamo paper, and systems influenced by it like Riak, use version vectors (a close relative of vector clocks, tracking per-replica write counts for an object instead of per-node event counts) to detect exactly this concurrent case for writes to the same key. If two replicas each accept a write to the same key while partitioned from each other, the resulting version vectors come back incomparable, and the system knows it has a genuine conflict — two values with no causal relationship — rather than silently picking one and quietly discarding the other. What to do about the conflict (merge the values, ask the application, use a CRDT) is a separate decision; the vector clock's job is purely detection, not resolution.
It's worth being explicit about what vector clocks are not, since it's an easy mix-up: this has nothing to do with leader election or consensus protocols like Raft. Leader election answers "who gets to be in charge and serialize all the writes" for systems that want a single, agreed-upon order of operations (we cover Raft's randomized-timeout election separately). Vector clocks are for the opposite philosophy — systems that deliberately allow multiple nodes to accept writes concurrently (favoring availability over a single global order, in CAP terms) and need a way to detect, after the fact, when that concurrency actually produced a conflict. One mechanism prevents concurrent writes from happening; the other accepts that they will and gives you a precise way to notice when they did.
The practical limitation worth knowing: a vector clock's size grows with the number of nodes in the system, which is fine for a handful of database replicas but becomes a real storage and bandwidth concern at Dynamo's scale with many clients - production systems that use version vectors typically add pruning strategies to cap how many historical actors they track per object.