ClockReport

Part of Clock diagnostics in the Python API reference.

Related guidance: how-to/check-clock, how-to/troubleshooting.

Runnable examples: check_clock.py.

from picogrid_ecn_client import ClockReport

Summary of one bounded ECN-relative clock measurement.

ClockReport(
    *,
    endpoint: ClockEndpoint,
    offset_seconds: float,
    round_trip_delay_seconds: float,
    local_capture_uncertainty_seconds: float,
    jitter_seconds: float,
    spread_seconds: float,
    samples_requested: int,
    samples_completed: int,
    server_version: Literal[4],
    server_stratum: int,
    leap_state: ClockLeapState,
    measured_at: datetime,
    max_offset_seconds: float | None = None,
    within_tolerance: bool | None = None,
)

Source · models/clock.py

Fields

Name	Type	Required	Default	Constraints	Description
endpoint	ClockEndpoint	yes	—	—	NTP endpoint that produced this measurement.
offset_seconds	float	yes	—	finite	Finite selected offset in seconds, ECN time minus local time; positive means ECN time is ahead.
round_trip_delay_seconds	float	yes	—	ge=0, finite	Finite non-negative round-trip delay in seconds for the selected sample, measured as the bracketed local monotonic interval minus the server receive-to-transmit interval.
local_capture_uncertainty_seconds	float	yes	—	ge=0, finite	Finite non-negative bound in seconds on offset error attributable to the paired local clock reads and tolerated wall/monotonic divergence. It does not bound network asymmetry or server accuracy.
jitter_seconds	float	yes	—	ge=0, finite	Finite non-negative variation in seconds across the completed samples.
spread_seconds	float	yes	—	ge=0, finite	Finite non-negative difference in seconds between the largest and smallest sampled offsets.
samples_requested	int	yes	—	ge=1, le=10	Number of samples the caller requested, from 1 through 10.
samples_completed	int	yes	—	ge=1, le=10	Number of valid samples used, from 1 through 10; never more than samples_requested.
server_version	Literal[4]	yes	—	—	NTP version reported by the server; only version 4 is accepted.
server_stratum	int	yes	—	ge=1, le=15	Server stratum reported in the selected response, from 1 through 15.
leap_state	ClockLeapState	yes	—	—	Leap indicator from the selected response; unsynchronized is rejected.
measured_at	datetime	yes	—	—	Timezone-aware UTC time when the measurement completed locally.
max_offset_seconds	float | None	no	None	ge=0, finite	Finite non-negative tolerance in seconds supplied by a tolerance check; present only together with within_tolerance.
within_tolerance	bool | None	no	None	—	Whether the absolute offset plus local capture uncertainty stayed within max_offset_seconds; present only together with it.