Every node keeps its own clock, and no two clocks run at exactly the same rate—they drift apart. dATS gives a segment a shared time reference without a central time server, so that timestamps produced on different nodes remain comparable. Tuning sync means understanding how that reference is built and maintained, and setting the tolerance that decides when the shared time can be trusted.
Why clocks drift, and what dATS does
Each node's clock is an independent oscillator, so relative to the others it gains or loses time. dATS does not appoint a master clock; instead the nodes converge onto a reference shared by the segment through synchronization exchanges. The result is self-synchronizing: there is no single point whose failure stops timekeeping for everyone.
Acquiring the offset
The first synchronization exchange, which happens as a node joins, calculates the correction that node needs. That difference is the offset. Once acquired, the node does not keep asking the network for the time—it produces shared time locally by adding the offset to its own clock.
Correcting drift over time
The offset is not set once and forgotten. Because the local clock keeps drifting, the correction that was accurate at join time slowly stops being accurate. Subsequent exchanges re-measure and adjust, so the offset tracks the drift as it accumulates rather than going stale.
Bounding the drift: tolerance and resync
Left alone, drift grows without limit. Bounding it is the point of tuning. The node always knows whether its residual error is within a configured tolerance, and setATSMaxError is what sets that tolerance—the maximum offset the node will accept before it stops trusting its own shared time.
When the bound is broken, the node does not quietly carry on with a stale reference. It repeats synchronization, and only then considers the shared time valid again. Three situations force this:
When shared time is valid
Synchronized time is not always available, and the API is explicit about it. getSyncedTimestamp returns a shared time only while the node is connected and synchronized; outside that state there is no meaningful shared value to hand back. For the node as a whole, being ready for any operation that needs comparable timestamps requires the dATS state to be valid—alongside a running core, an active driver, and a known effective identity. The core also reports synchronization as an event, so the application can react the moment sync completes rather than polling for it.
What comparable time buys: end-to-end delay
The payoff of a shared reference shows up when a DDO crosses the network. The timestamp assigned at the source is never rewritten by intermediate nodes, so the destination can compare when the object was produced with when it arrived and measure the total delay—even across several hops.
This is exactly why intermediaries preserve the origin timestamp instead of restamping: it separates transport latency from the instant of production. The measurement is only meaningful, though, when the origin node was synchronized at the time it produced the DDO—an unsynchronized source produces a timestamp that cannot be compared against anything.
Tuning the tolerance
setATSMaxError is the main knob, and it is a trade-off rather than a value to maximize. A tighter bound keeps timestamps closer together but tends to break sooner, so it triggers resynchronization more often and adds control-plane traffic. A looser bound is cheaper but weakens every guarantee that depends on comparable time. The right setting follows from what the application actually does with time:
- if it only needs coarse ordering or human-readable timestamps, a wide bound is fine;
- if it measures latency or enforces fine-grained ordering across nodes, the bound has to be tight enough that the error it tolerates is smaller than the differences it wants to observe.
Because the node self-reports whether it is within tolerance, the robust pattern is to gate timestamp-dependent logic on the synchronized state rather than assuming the shared time is always good. When the node reports it is out of tolerance and resynchronizing, comparisons and delay measurements should wait.
Partitions and recovery
During a network partition, nodes in the same segment can end up in temporarily isolated groups. They keep their identities and prior knowledge, but they can only reach the routes that still exist—and their clocks keep drifting independently while apart. When the link returns, time state is checked against the current topology, and a partition rejoin is one of the conditions that forces a fresh synchronization before the shared time is trusted again.
Minimal sequence
node.setATSMaxError(max_offset); // bound: the maximum tolerated offset
// ... after join, the core signals that synchronization has completed ...
if (/* node is connected and synchronized */) {
auto now = node.getSyncedTimestamp(); // valid only in that state
// safe to compare, order, or measure delay against DDO timestamps
}
The method names and the exact way synchronization is reported—an event, a listener, a callback—depend on the SDK; each one exposes the same behavior through its idiomatic constructs, and its reference documentation gives the concrete signatures.
Invariants
- dATS makes timestamps comparable without introducing a central clock.
- The offset is acquired at join and maintained as drift accumulates, never assumed constant.
- The node tracks its residual error against a configured tolerance and resynchronizes when the reference changes, the tolerance is exceeded, or a partition reconnects—treating shared time as invalid until it does.
- A source timestamp is preserved unchanged across every hop, so production time and reception time stay comparable end to end.