Get the SDK

Guides/Tune sync

Guide

Tune sync

How a segment builds and maintains a shared time reference without a central time server — and how to set the tolerance that decides when that shared time can be trusted.

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.

node A clockdrifts
node B clockdrifts
node C clockdrifts
sharedreference
No master clock — the nodes converge on the reference.

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.

local time
+ offset
shared time

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:

the referencechanges
error exceedsthe tolerance
a partitionreconnects
repeatsynchronization
shared timevalid again
Any one of the three invalidates the shared time until sync repeats.

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.

origint = T0
intermediatenode
intermediatenode
destinationreceived at T1
delay =T1 − T0
The origin timestamp survives every hop, so the delay is measurable.

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:

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

C++ · libDaas
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

See nodes converge on a shared reference.

Open the Lab Simulator