More sources, instruments and clock-error bounds¶
Live PTP clients¶
ntpstats watch samples a running PTP client, just as it samples chrony or ntpd:
ntpstats watch ptp4l -i 1 -o ptp4l.csv # linuxptp: pmc -u -b 0 'GET CURRENT_DATA_SET' 'GET TIME_STATUS_NP'
ntpstats watch ptpcheck -i 1 -o ptpcheck.csv # facebook/time: ptpcheck stats
ntpstats watch ptp4l --metrics-port 9124 # and serve it to Prometheus
Recorded columns:
- ptp4l: offsetFromMaster, then meanPathDelay, master_offset, stepsRemoved and
gmPresent, and from GET PORT_DATA_SET the state of every port: ports, slave_port,
faulty_ports and, on the console, port_states such as 1:SLAVE 2:MASTER for a boundary
clock.
- ptpcheck: ptp.offset_ns and ptp.mean_path_delay_ns.
Both tools report local − master, so the offsets are negated into the ntpstats convention (reference − local). The web UI's Live workspace offers the same sources.
PTP hardware clocks and the OCP Time Card¶
ntpstats watch phc -i 1 -o phc.csv # /dev/ptp0 against the system clock
ntpstats watch phc --command-override "/dev/ptp1 37" # another PHC, TAI - UTC given
ntpstats watch timecard -i 1 -o timecard.csv # /sys/class/timecard/ocp0
watch phc reads a PTP hardware clock against the system clock with the kernel's
PTP_SYS_OFFSET_EXTENDED ioctl, as linuxptp's phc2sys does: of nine readings
[system, PHC, system] the one with the shortest system window is kept, and the PHC is compared
with its midpoint. The offset is PHC − system (reference − local); a PHC on TAI is reduced by the
whole seconds between the two clocks (whole_seconds, or the TAI − UTC you give), and
read_window records the system window, which bounds the error of the reading. It needs read
access to /dev/ptpN, nothing else.
watch timecard does the same for an OCP Time Card
through its ptp link and adds the status of the Linux ptp_ocp driver
(Documentation/ABI/testing/sysfs-timecard): gnss_sync (1 for SYNC, 0 once LOST),
clock_source, utc_tai_offset (used as TAI − UTC) and the firmware's clock_status_offset
and clock_status_drift, kept in the firmware's own units. Logs of phc2sys itself are read like
any linuxptp log.
gpsd¶
ntpstats watch gpsd -i 1 -o gpsd-pps.csv # localhost:2947
ntpstats watch gpsd --command-override timeserver.lan:2947 # another host
Each sample is the offset of the latest PPS edge (GNSS time minus the system clock's time stamp),
or of the serial time (TOFF) when the receiver has no PPS, with gpsd's precision and the
receiver's qErr when reported. See Research data for recorded gpspipe -w
logs.
ntpd-rs¶
ntpstats watch ntpd-rs -i 16 -o ntpd-rs.csv # runs: ntp-ctl -f prometheus status
ntpstats watch ntpd-rs --command-override http://127.0.0.1:9975/metrics # or its metrics exporter
ntpd-rs 1.x exports ntp_source_offset_seconds (source − local, the ntpstats convention),
ntp_source_uncertainty_seconds and ntp_source_delay_seconds for every source. Each sample's
offset is the inverse-variance mean over the sources, and the log keeps the number of sources,
the best source's uncertainty and delay, and the system root delay, root dispersion and stratum.
The 2.0 pre-releases (July 2026) reworked ntpd-rs internals and no longer export per-source
offsets; watch says so instead of logging nothing. For those, analyse a packet capture (NTP,
NTP over PTP or CSPTP, see PTP captures).
Windows (w32tm)¶
w32tm /stripchart /computer:time.windows.com /dataonly /samples:1000 > w32tm.txt
ntpstats stability w32tm.txt -k tdev,mtie # format detected automatically
Both the /dataonly text (HH:MM:SS, d:+00.0541615s o:-00.0031265s, or the older form without
d:) and the /rdtsc CSV (RdtscStart,RdtscEnd,FileTime,RoundtripDelay,NtpOffset) are read.
Microsoft documents NtpOffset as "computed as per NTP offset computations" (server − local),
which is the ntpstats convention. The text form prints only a time of day: the date comes from
the "The current time is …" line when it can be read, midnight rollovers are handled, and the
times are the Windows host's local wall clock. The /rdtsc form carries exact FILETIME
timestamps.
Prometheus (ntpd-rs, chrony_exporter, …)¶
Anything already in Prometheus can be pulled into ntpstats: ntpd-rs 1.x metrics
(ntp_source_offset_seconds), chrony_exporter, or ntpstats' own exporter.
ntpstats prom http://prometheus:9090 'ntp_source_offset_seconds' --since 7d --step 60 -o ntpd-rs.json
ntpstats stability ntpd-rs.json --all-peers -k oadev,tdev
The saved query_range JSON is a regular input format with one series per label set. Offsets are
taken as reference − local; ntpd-rs documents ntp_source_offset_seconds as the "offset between
the upstream source and system time". For a metric that reports local − reference, add
--negate (available on every command).
Validating clock-error bounds¶
AWS ClockBound, Meta's fbclock and TrueTime-style APIs report a window
[earliest, latest] that should contain true time. ntpstats bounds checks this against a
better reference for the same host, for example a PPS/PTP comparison, or NTS measurements when
the bound is much wider than their delay:
ntpstats bounds clockbound.txt reference.csv # exit code 3 on any violation
ntpstats bounds windows.csv ptp4l.csv --max-violation-rate 1e-4 --json
Accepted bound inputs:
- ClockBound: the example client's output lines (… true time was somewhere within A and B
seconds …). ClockBound builds the window around the system clock reading.
- CSV: earliest,latest columns (POSIX seconds), plus unix_time (the local clock read
together with the window; needed when the window is not centred on the system clock, as
with PHC-based fbclock) and an optional status. Values are parsed as exact decimals, because
a float cannot hold nanoseconds at today's epoch.
Each window is classed as inside, violated, or indeterminate (the reference's own uncertainty, half its round-trip delay by default, is too large to tell). The report gives the violation rate, the worst excess, the median bound and the tightness (median |error| / median bound).
Try it on the bundled examples:
ntpstats bounds examples/data/clockbound.txt examples/data/clockbound-reference.csv.
The bounds can also be recorded live:
ntpstats watch clockbound -i 1 -o clockbound.csv # libclockbound's clockbound_now(), in process
ntpstats watch fbclock -i 1 -o fbclock.csv # ptpcheck fbclock --utc (facebook/time)
ntpstats bounds clockbound.csv phc.csv # then check them against a reference
watch clockbound loads the ClockBound client library (clock-bound-ffi; set
NTPSTATS_LIBCLOCKBOUND to its path if it is not on the library path) and calls
clockbound_now(), reading the system clock just before and after; watch fbclock runs
ptpcheck fbclock --utc, so its read_window is the time the command took. Both logs keep
earliest and latest to the nanosecond and are read back as bounds files; the exporter
(--metrics-port) publishes ntpstats_offset_bound_seconds as |offset| plus the service's own
half-width.
Instrument export profiles¶
Time-interval counters and PTP/SyncE testers export CSV files whose layout varies by vendor. A profile describes a layout in a few TOML lines, so a new instrument needs no code:
# my-counter.toml
name = "my-counter"
value_column = "TI (ns)" # header name or index
units = "ns" # s, ms, us, ns, ps
quantity = "te" # te: local - reference (DUT - REF); offset: reference - local
time_column = "Timestamp" # optional; else tau0 spacing
time_format = "iso" # unix | iso | mjd | elapsed
skip_rows = 2 # instrument banner lines
delimiter = ";"
extra_columns = ["Temperature"]
ntpstats timeerror export.csv -f profile:my-counter.toml --limits limits.csv
ntpstats timeerror tic.txt -f profile:tic-ns # built-in: one ns reading per line, 1 s apart
Built-in profiles:
- te-csv: unix time and TE in seconds;
- tic-ns and tic-s: one time-interval reading per line, 1 s apart;
- iso-te-ns: ISO 8601 timestamp and TE in ns.
Vendor profiles are added from sample exports that users share, via the Share a sample log issue form or issue #35.
Mapping columns without a profile¶
--columns (or -f columns:SPEC) maps the columns of any CSV or TSV export on the command
line, and ntpstats columns FILE proposes the mapping from the file itself:
$ ntpstats columns export.csv --save my-counter.toml
export.csv: 4 columns, with a header
0 Time iso 2026-10-20T10:00:00Z
1 TIE (ns) number 12.5
2 Delay (ns) number 1520
3 Status text OK
proposed mapping: --columns 'time=Time:iso,te=TIE (ns),units=ns,delimiter=comma,extra=Delay (ns)'
- units ns from the column name 'TIE (ns)'
- sign: taken as time error, local (DUT) - reference, as instruments report it; ...
ntpstats timeerror export.csv --columns 'time=Time:iso,te=TIE (ns),units=ns'
ntpstats stability export.csv -f profile:my-counter.toml # the saved mapping
Keys: time (a column, optionally :unix, :iso, :mjd or :elapsed), te= (local −
reference) or offset= (reference − local) for the value, units, time_units, tau0 (when
there is no time column), delimiter (comma, semicolon, tab, space), skip, header
and extra (more columns joined with +). Columns are 0-based indices or header names. The
units and the sign are what a guess cannot know for sure: check them before trusting a result.
In the web UI, a text file that no format recognises opens a Map columns dialog with the proposed mapping and a preview, and map columns in the format menu opens it on purpose.