Skip to content

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.