From 13a907bc28518e72f14eae31bb69d5a4b43f4a7f Mon Sep 17 00:00:00 2001 From: Nils Andreas Svee Date: Thu, 20 Aug 2026 14:56:50 +0700 Subject: [PATCH] docs: document Linux kernel-timestamp preference for OWD On Linux, one-way delay measurement best-effort prefers kernel send/receive timestamps over userspace timing, falling back whenever a kernel reading is unavailable or implausible. RTT is unaffected and remains userspace-timed. Add a user-facing README note near the measurement/output explanation, and bring OneWayDelaySample::client_to_server's rustdoc in line with the send-endpoint behavior, matching the style already used for server_to_client. Also fix a stale socket_io module doc that still claimed the captured kernel receive timestamp went unconsumed; ServerCore has used it via preferred_receive_wall_ns since d3f93a9. --- README.md | 2 ++ crates/irtt-client/src/event.rs | 8 +++++++- crates/irtt-server/src/socket_io.rs | 10 +++++----- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e209d23..b4bb6f4 100644 --- a/README.md +++ b/README.md @@ -185,6 +185,8 @@ Useful measurement fields include: Adjusted RTT can be negative when server processing exceeds the measured raw RTT. One-way delay estimates can be negative because of clock skew between the client and server. +On Linux, `sd_us` and `rd_us` (and the underlying one-way delay samples) prefer kernel-captured send/receive timestamps over userspace timing where the platform and socket support them, reducing the effect of scheduling and queuing delay on these measurements. This is a best-effort fallback: unsupported or implausible kernel timestamps fall back to userspace timing. RTT always uses userspace timing and is unaffected. + Default table output prints a final summary after completed finite runs and interrupted continuous runs when the run policy permits it. CSV, TSV, and JSON Lines output do not print this summary. A peer closing a finite CLI or TUI run is accepted as a terminal outcome. In diff --git a/crates/irtt-client/src/event.rs b/crates/irtt-client/src/event.rs index 6f74089..ef700c0 100644 --- a/crates/irtt-client/src/event.rs +++ b/crates/irtt-client/src/event.rs @@ -351,7 +351,13 @@ pub struct OneWayDelaySample { /// Client-to-server delay. /// /// This is computed from the client send wall time and the server receive - /// wall time when both are available. + /// wall time when both are available. The client send endpoint is the + /// correlated Linux kernel TX timestamp for this send when one is + /// available and plausible for this send, and the userspace post-send wall + /// time otherwise. The server receive endpoint is the server's kernel + /// receive timestamp when one is available and plausible, and its + /// userspace receive wall time otherwise. RTT is unaffected and remains a + /// userspace monotonic measurement. pub client_to_server: Option, /// Server-to-client delay. /// diff --git a/crates/irtt-server/src/socket_io.rs b/crates/irtt-server/src/socket_io.rs index 1a9b93c..cc2d2e2 100644 --- a/crates/irtt-server/src/socket_io.rs +++ b/crates/irtt-server/src/socket_io.rs @@ -32,11 +32,11 @@ //! instant, is served normally with no timestamp. Nothing about which datagrams //! reach [`ServerCore`](crate::ServerCore) depends on it. //! -//! **Nothing consumes it yet.** It is captured here so a follow-up change can -//! decide how a kernel-observed arrival time enters the protocol core; today -//! the core still samples its own receive instant and no protocol timing is -//! affected. It is a software wall-clock reading only — not a NIC hardware -//! timestamp, not monotonic, and not a transmit timestamp. +//! [`ServerCore`](crate::ServerCore) prefers it over its own receive sample +//! when reporting a request's receive instant, falling back to that sample +//! when no plausible kernel reading is available; see +//! `preferred_receive_wall_ns`. It is a software wall-clock reading only — +//! not a NIC hardware timestamp, not monotonic, and not a transmit timestamp. use std::{io, net::SocketAddr, time::SystemTime};