ipyrf 2.0.0__tar.gz → 2.1.0__tar.gz

{ipyrf-2.0.0/src/ipyrf.egg-info → ipyrf-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipyrf
-Version: 2.0.0
+Version: 2.1.0
 Summary: A tiny iperf3-like tool with JSON output (TCP/UDP)
 Author: Steinwurf ApS
 License: MIT License
@@ -40,9 +40,12 @@ Classifier: Topic :: System :: Benchmark
 Requires-Python: >=3.8
 Description-Content-Type: text/x-rst
 License-File: LICENSE
+Requires-Dist: plotly>=5.18
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0; extra == "test"
+Provides-Extra: report-export
+Requires-Dist: kaleido>=0.2; extra == "report-export"
 Dynamic: license-file
 
 ipyrf
@@ -56,9 +59,11 @@ Features
 - JSON or human-readable output
 - Optional bandwidth capping (TCP/UDP)
 - UDP packet loss estimation
-- Optional per-datagram UDP packet recording
+- Optional receive-side recording of UDP datagrams and TCP framed records
+- Interactive HTML reports from ``--record`` CSVs (``ipyrf-report``)
 - Linux TCP congestion control selection (if available)
 - Client ``--bind-dev`` to transmit via a specific network interface (Linux)
+- Clock-offset measurement to a remote host over SSH (``ipyrf offset``)
 
 Installation
 ------------
@@ -125,7 +130,7 @@ The project includes a comprehensive test suite using pytest:
 Usage
 -----
 
-The package installs a console script named ``ipyrf``.
+The package installs console scripts named ``ipyrf`` and ``ipyrf-report``.
 
 Quick examples
 ~~~~~~~~~~~~~~
@@ -135,6 +140,7 @@ TCP server:
 .. code-block:: bash
 
    ipyrf tcp server 0.0.0.0 --port 12345
+   ipyrf tcp server 0.0.0.0 --port 12345 --record records.csv
    ipyrf tcp server 0.0.0.0 --port 12345 --trace-dir /var/traces
 
 TCP client:
@@ -154,7 +160,7 @@ UDP server:
 .. code-block:: bash
 
    ipyrf udp server 0.0.0.0 --port 12345
-   ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv
+   ipyrf udp server 0.0.0.0 --port 12345 --record records.csv
    ipyrf udp server 0.0.0.0 --port 12345 --trace-dir /var/traces
 
 UDP client (with bandwidth cap and optional payload size):
@@ -169,6 +175,13 @@ UDP client (with bandwidth cap and optional payload size):
    ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 --reverse
    ipyrf udp client 127.0.0.1 --port 12345 --traffic-pattern trace.json --reverse
 
+Clock offset (this host vs a remote SSH machine):
+
+.. code-block:: bash
+
+   ipyrf offset user@rasp1
+   ipyrf offset user@rasp1 --json
+
 Reverse mode
 ------------
 
@@ -320,12 +333,16 @@ Top-level structure:
 
    ipyrf [tcp|udp] [server|client] [OPTIONS]
    ipyrf generate video -o FILE [OPTIONS]
+   ipyrf offset HOST [OPTIONS]
+   ipyrf-report RECORD [OPTIONS]
 
 Common options (both protocols, both roles):
 
 - ``--port``: Port (default 5201)
 - ``--logfile``: Redirect output to a file
 - ``--json_log``: Emit logs in JSON (newline-delimited)
+- ``--record PATH``: Write received records to a CSV file after the test
+  (UDP datagrams or TCP framed records). On a client, requires ``--reverse``
 
 TCP-specific options:
 
@@ -361,7 +378,6 @@ UDP-specific options:
   is sent; the server must have the same file
 - ``--loops N``: Replay ``--traffic-pattern`` N times (default 1)
 - ``-l/--length``: UDP payload length (default 1200)
-- ``--packet-record PATH``: UDP server: write received packet traces to a CSV file after the test
 - ``--inactivity-timeout SECONDS``: UDP server: exit after this many seconds
   without receiving packets (default 2.0)
 - ``--trace-dir DIR``: UDP server: directory of traffic-pattern files for
@@ -384,33 +400,127 @@ Generate options:
 - ``--duration``: Synthetic length in seconds (default 10), or optional
   truncate when importing from ffprobe
 
-UDP packet recording
---------------------
-
-Pass ``--packet-record PATH`` to a UDP server to record one trace entry per
-received datagram (sequence number, sender timestamp, receiver timestamp,
-packet size, and traffic-pattern ``event_id``). Records are packed into
-fixed-size in-memory chunks during the test so the receive path stays free of
-CSV I/O. Chunks are allocated before the test starts (about 20 s of 1 Gbit/s
-traffic by default) so rotation does not stall the receive loop. When the test
-ends, the CSV file (columns ``sequence``, ``size_bytes``, ``transmitted_ns``,
-``received_ns``, ``event_id``) is written to ``PATH``. Per-packet latency in
-nanoseconds is ``received_ns - transmitted_ns``. ``event_id`` is ``0`` unless
-the client used ``--traffic-pattern``.
+Offset options:
+
+- ``offset HOST``: Measure clock offset to ``HOST`` over SSH
+- ``--samples N``: Number of round-trip samples (default 30)
+- ``--interval SECONDS``: Delay between samples (default 0.2)
+- ``--json``: Write a JSON summary to stdout
+- ``--python CMD``: Python interpreter on the remote host (default
+  ``python3``)
+- ``--ssh-arg ARG``: Extra argument forwarded to ``ssh`` (repeatable)
+
+Report options (``ipyrf-report``):
+
+- ``RECORD``: Record CSV from ``--record``
+- ``-o/--output FILE``: HTML output path (default: ``RECORD`` with ``.html``)
+- ``--traffic-pattern FILE``: Traffic-pattern JSON used during the test
+- ``--json FILE``: Also write analysis results as JSON
+- ``--png [DIR]`` / ``--svg [DIR]``: Export static plots (requires kaleido)
+- ``--bin-ms MS``: Time-series bin size in milliseconds (default: auto)
+- ``--title TITLE``: Report title
+- ``--clock-offset MS``: Add this many milliseconds to one-way latency
+  (value from ``ipyrf offset`` run on the receiving host against the
+  sender). The HTML report can also change this after generation
+
+Receive recording
+-----------------
+
+Pass ``--record PATH`` on the receiving side (a server, or a client with
+``--reverse``) to write one CSV row per received UDP datagram or complete
+TCP framed record (sequence, sender timestamp, receiver timestamp, size,
+and traffic-pattern ``event_id``). UDP uses the sender sequence number so
+loss and reordering stay visible. TCP assigns sequence in receive order
+(1, 2, 3, …) because the stream has no packet sequence. Records are packed
+into fixed-size in-memory chunks during the test so the receive path stays
+free of CSV I/O. Chunks are allocated before the test starts (about 20 s of
+1 Gbit/s traffic by default) so rotation does not stall the receive loop.
+When the test ends, the CSV file is written to ``PATH``. It starts with a
+``# ipyrf-record 1`` magic line and a ``# { ... }`` JSON comment describing
+the run (protocol, sequence kind, addresses, optional traffic pattern),
+then the header row and data (columns ``sequence``, ``size_bytes``,
+``transmitted_ns``, ``received_ns``, ``event_id``).
+One-way latency in nanoseconds is ``received_ns - transmitted_ns``.
+That difference includes any clock offset between sender and receiver;
+use ``ipyrf offset`` to measure it. ``event_id`` is ``0`` unless the
+sender used ``--traffic-pattern``.
+``ipyrf-report`` reads that metadata to label the run and to omit TCP
+loss/reorder charts. Pass ``--traffic-pattern`` to override an embedded
+pattern. Spreadsheet tools treat the ``#`` lines as extra rows; skip them
+or use ``ipyrf-report``.
 
 Quick local test (two terminals):
 
 .. code-block:: bash
 
    # Terminal 1 — server with recording
-   ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv
+   ipyrf udp server 0.0.0.0 --port 12345 --record records.csv
+   # or: ipyrf tcp server 0.0.0.0 --port 12345 --record records.csv
 
    # Terminal 2 — short paced client
    ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 2 -l 1200
+   # or: ipyrf tcp client 127.0.0.1 --port 12345 --bandwidth 50M --time 2
 
-When the client finishes, the server exits and ``packets.csv`` contains the
+When the client finishes, the server exits and ``records.csv`` contains the
 trace. Use ``--enable-latency`` on the client if you also want latency
-stats in the server summary.
+stats in the server summary. Turn the CSV into an interactive HTML report
+with ``ipyrf-report`` (see below).
+
+Reports (ipyrf-report)
+----------------------
+
+``ipyrf-report`` reads a ``--record`` CSV (including the JSON metadata
+comment) and writes one self-contained interactive HTML file (Plotly.js is
+embedded, so the file works offline). Pass ``--traffic-pattern`` to override
+a pattern embedded in the record metadata; otherwise the report uses the
+embedded pattern when present. Pass ``--clock-offset MS`` to add that many
+milliseconds to one-way latency (the HTML header also has a clock-offset
+field you can edit later without regenerating).
+
+The report is laid out like a performance trace: KPI overview at the top,
+then throughput, latency (p50 / p95 / p99), loss and sequence / reordering
+when the recording is UDP, send vs receive spacing, and latency
+distribution / ECDF.
+
+.. code-block:: bash
+
+   ipyrf-report records.csv
+   ipyrf-report records.csv -o report.html --traffic-pattern trace.json
+   ipyrf-report records.csv --json report.json --bin-ms 10
+   ipyrf-report records.csv --png --svg
+   ipyrf-report records.csv --clock-offset 1.23
+
+``-o`` defaults to the record path with a ``.html`` suffix. ``--png`` and
+``--svg`` write individual plots next to the HTML (or to a directory you
+pass); they require the optional ``kaleido`` extra:
+
+.. code-block:: bash
+
+   python3 -m pip install 'ipyrf[report-export]'
+
+Clock offset
+------------
+
+``ipyrf offset HOST`` measures the wall-clock offset between this machine
+and a remote SSH host. It does not change either clock.
+
+This is useful when comparing ``transmitted_ns`` and ``received_ns`` in a
+``--record`` CSV from a two-host test. One-way latency is
+``received_ns - transmitted_ns``. If you run ``ipyrf offset`` on the
+receiving host against the sender, pass that value to
+``ipyrf-report --clock-offset`` (or type it into the HTML report). That
+adds the offset so latency is in the receiver's time base. If this host
+sent and the remote recorded, negate the printed offset first.
+
+The remote host needs ``python3`` (or pass ``--python``). SSH uses your
+normal configuration and keys.
+
+.. code-block:: bash
+
+   ipyrf offset user@rasp1
+   ipyrf offset user@rasp1 --samples 50 --interval 0.1
+   ipyrf offset rasp1 --json
+   ipyrf offset rasp1 --ssh-arg=-p --ssh-arg=2222
 
 JSON logging
 ------------

{ipyrf-2.0.0 → ipyrf-2.1.0}/README.rst

@@ -9,9 +9,11 @@ Features
 - JSON or human-readable output
 - Optional bandwidth capping (TCP/UDP)
 - UDP packet loss estimation
-- Optional per-datagram UDP packet recording
+- Optional receive-side recording of UDP datagrams and TCP framed records
+- Interactive HTML reports from ``--record`` CSVs (``ipyrf-report``)
 - Linux TCP congestion control selection (if available)
 - Client ``--bind-dev`` to transmit via a specific network interface (Linux)
+- Clock-offset measurement to a remote host over SSH (``ipyrf offset``)
 
 Installation
 ------------
@@ -78,7 +80,7 @@ The project includes a comprehensive test suite using pytest:
 Usage
 -----
 
-The package installs a console script named ``ipyrf``.
+The package installs console scripts named ``ipyrf`` and ``ipyrf-report``.
 
 Quick examples
 ~~~~~~~~~~~~~~
@@ -88,6 +90,7 @@ TCP server:
 .. code-block:: bash
 
    ipyrf tcp server 0.0.0.0 --port 12345
+   ipyrf tcp server 0.0.0.0 --port 12345 --record records.csv
    ipyrf tcp server 0.0.0.0 --port 12345 --trace-dir /var/traces
 
 TCP client:
@@ -107,7 +110,7 @@ UDP server:
 .. code-block:: bash
 
    ipyrf udp server 0.0.0.0 --port 12345
-   ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv
+   ipyrf udp server 0.0.0.0 --port 12345 --record records.csv
    ipyrf udp server 0.0.0.0 --port 12345 --trace-dir /var/traces
 
 UDP client (with bandwidth cap and optional payload size):
@@ -122,6 +125,13 @@ UDP client (with bandwidth cap and optional payload size):
    ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 --reverse
    ipyrf udp client 127.0.0.1 --port 12345 --traffic-pattern trace.json --reverse
 
+Clock offset (this host vs a remote SSH machine):
+
+.. code-block:: bash
+
+   ipyrf offset user@rasp1
+   ipyrf offset user@rasp1 --json
+
 Reverse mode
 ------------
 
@@ -273,12 +283,16 @@ Top-level structure:
 
    ipyrf [tcp|udp] [server|client] [OPTIONS]
    ipyrf generate video -o FILE [OPTIONS]
+   ipyrf offset HOST [OPTIONS]
+   ipyrf-report RECORD [OPTIONS]
 
 Common options (both protocols, both roles):
 
 - ``--port``: Port (default 5201)
 - ``--logfile``: Redirect output to a file
 - ``--json_log``: Emit logs in JSON (newline-delimited)
+- ``--record PATH``: Write received records to a CSV file after the test
+  (UDP datagrams or TCP framed records). On a client, requires ``--reverse``
 
 TCP-specific options:
 
@@ -314,7 +328,6 @@ UDP-specific options:
   is sent; the server must have the same file
 - ``--loops N``: Replay ``--traffic-pattern`` N times (default 1)
 - ``-l/--length``: UDP payload length (default 1200)
-- ``--packet-record PATH``: UDP server: write received packet traces to a CSV file after the test
 - ``--inactivity-timeout SECONDS``: UDP server: exit after this many seconds
   without receiving packets (default 2.0)
 - ``--trace-dir DIR``: UDP server: directory of traffic-pattern files for
@@ -337,33 +350,127 @@ Generate options:
 - ``--duration``: Synthetic length in seconds (default 10), or optional
   truncate when importing from ffprobe
 
-UDP packet recording
---------------------
-
-Pass ``--packet-record PATH`` to a UDP server to record one trace entry per
-received datagram (sequence number, sender timestamp, receiver timestamp,
-packet size, and traffic-pattern ``event_id``). Records are packed into
-fixed-size in-memory chunks during the test so the receive path stays free of
-CSV I/O. Chunks are allocated before the test starts (about 20 s of 1 Gbit/s
-traffic by default) so rotation does not stall the receive loop. When the test
-ends, the CSV file (columns ``sequence``, ``size_bytes``, ``transmitted_ns``,
-``received_ns``, ``event_id``) is written to ``PATH``. Per-packet latency in
-nanoseconds is ``received_ns - transmitted_ns``. ``event_id`` is ``0`` unless
-the client used ``--traffic-pattern``.
+Offset options:
+
+- ``offset HOST``: Measure clock offset to ``HOST`` over SSH
+- ``--samples N``: Number of round-trip samples (default 30)
+- ``--interval SECONDS``: Delay between samples (default 0.2)
+- ``--json``: Write a JSON summary to stdout
+- ``--python CMD``: Python interpreter on the remote host (default
+  ``python3``)
+- ``--ssh-arg ARG``: Extra argument forwarded to ``ssh`` (repeatable)
+
+Report options (``ipyrf-report``):
+
+- ``RECORD``: Record CSV from ``--record``
+- ``-o/--output FILE``: HTML output path (default: ``RECORD`` with ``.html``)
+- ``--traffic-pattern FILE``: Traffic-pattern JSON used during the test
+- ``--json FILE``: Also write analysis results as JSON
+- ``--png [DIR]`` / ``--svg [DIR]``: Export static plots (requires kaleido)
+- ``--bin-ms MS``: Time-series bin size in milliseconds (default: auto)
+- ``--title TITLE``: Report title
+- ``--clock-offset MS``: Add this many milliseconds to one-way latency
+  (value from ``ipyrf offset`` run on the receiving host against the
+  sender). The HTML report can also change this after generation
+
+Receive recording
+-----------------
+
+Pass ``--record PATH`` on the receiving side (a server, or a client with
+``--reverse``) to write one CSV row per received UDP datagram or complete
+TCP framed record (sequence, sender timestamp, receiver timestamp, size,
+and traffic-pattern ``event_id``). UDP uses the sender sequence number so
+loss and reordering stay visible. TCP assigns sequence in receive order
+(1, 2, 3, …) because the stream has no packet sequence. Records are packed
+into fixed-size in-memory chunks during the test so the receive path stays
+free of CSV I/O. Chunks are allocated before the test starts (about 20 s of
+1 Gbit/s traffic by default) so rotation does not stall the receive loop.
+When the test ends, the CSV file is written to ``PATH``. It starts with a
+``# ipyrf-record 1`` magic line and a ``# { ... }`` JSON comment describing
+the run (protocol, sequence kind, addresses, optional traffic pattern),
+then the header row and data (columns ``sequence``, ``size_bytes``,
+``transmitted_ns``, ``received_ns``, ``event_id``).
+One-way latency in nanoseconds is ``received_ns - transmitted_ns``.
+That difference includes any clock offset between sender and receiver;
+use ``ipyrf offset`` to measure it. ``event_id`` is ``0`` unless the
+sender used ``--traffic-pattern``.
+``ipyrf-report`` reads that metadata to label the run and to omit TCP
+loss/reorder charts. Pass ``--traffic-pattern`` to override an embedded
+pattern. Spreadsheet tools treat the ``#`` lines as extra rows; skip them
+or use ``ipyrf-report``.
 
 Quick local test (two terminals):
 
 .. code-block:: bash
 
    # Terminal 1 — server with recording
-   ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv
+   ipyrf udp server 0.0.0.0 --port 12345 --record records.csv
+   # or: ipyrf tcp server 0.0.0.0 --port 12345 --record records.csv
 
    # Terminal 2 — short paced client
    ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 2 -l 1200
+   # or: ipyrf tcp client 127.0.0.1 --port 12345 --bandwidth 50M --time 2
 
-When the client finishes, the server exits and ``packets.csv`` contains the
+When the client finishes, the server exits and ``records.csv`` contains the
 trace. Use ``--enable-latency`` on the client if you also want latency
-stats in the server summary.
+stats in the server summary. Turn the CSV into an interactive HTML report
+with ``ipyrf-report`` (see below).
+
+Reports (ipyrf-report)
+----------------------
+
+``ipyrf-report`` reads a ``--record`` CSV (including the JSON metadata
+comment) and writes one self-contained interactive HTML file (Plotly.js is
+embedded, so the file works offline). Pass ``--traffic-pattern`` to override
+a pattern embedded in the record metadata; otherwise the report uses the
+embedded pattern when present. Pass ``--clock-offset MS`` to add that many
+milliseconds to one-way latency (the HTML header also has a clock-offset
+field you can edit later without regenerating).
+
+The report is laid out like a performance trace: KPI overview at the top,
+then throughput, latency (p50 / p95 / p99), loss and sequence / reordering
+when the recording is UDP, send vs receive spacing, and latency
+distribution / ECDF.
+
+.. code-block:: bash
+
+   ipyrf-report records.csv
+   ipyrf-report records.csv -o report.html --traffic-pattern trace.json
+   ipyrf-report records.csv --json report.json --bin-ms 10
+   ipyrf-report records.csv --png --svg
+   ipyrf-report records.csv --clock-offset 1.23
+
+``-o`` defaults to the record path with a ``.html`` suffix. ``--png`` and
+``--svg`` write individual plots next to the HTML (or to a directory you
+pass); they require the optional ``kaleido`` extra:
+
+.. code-block:: bash
+
+   python3 -m pip install 'ipyrf[report-export]'
+
+Clock offset
+------------
+
+``ipyrf offset HOST`` measures the wall-clock offset between this machine
+and a remote SSH host. It does not change either clock.
+
+This is useful when comparing ``transmitted_ns`` and ``received_ns`` in a
+``--record`` CSV from a two-host test. One-way latency is
+``received_ns - transmitted_ns``. If you run ``ipyrf offset`` on the
+receiving host against the sender, pass that value to
+``ipyrf-report --clock-offset`` (or type it into the HTML report). That
+adds the offset so latency is in the receiver's time base. If this host
+sent and the remote recorded, negate the printed offset first.
+
+The remote host needs ``python3`` (or pass ``--python``). SSH uses your
+normal configuration and keys.
+
+.. code-block:: bash
+
+   ipyrf offset user@rasp1
+   ipyrf offset user@rasp1 --samples 50 --interval 0.1
+   ipyrf offset rasp1 --json
+   ipyrf offset rasp1 --ssh-arg=-p --ssh-arg=2222
 
 JSON logging
 ------------

{ipyrf-2.0.0 → ipyrf-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipyrf"
-version = "2.0.0"
+version = "2.1.0"
 description = "A tiny iperf3-like tool with JSON output (TCP/UDP)"
 readme = "README.rst"
 requires-python = ">=3.8"
@@ -21,10 +21,13 @@ classifiers = [
   "Topic :: System :: Networking",
   "Topic :: System :: Benchmark",
 ]
-dependencies = []
+dependencies = [
+  "plotly>=5.18",
+]
 
 [project.optional-dependencies]
 test = ["pytest>=7.0", "pytest-cov>=4.0"]
+report-export = ["kaleido>=0.2"]
 
 [project.urls]
 Homepage = "https://github.com/steinwurf/ipyrf"
@@ -33,6 +36,7 @@ Issues = "https://github.com/steinwurf/ipyrf/issues"
 
 [project.scripts]
 ipyrf = "ipyrf.__main__:main"
+ipyrf-report = "ipyrf.report.cli:main"
 
 [tool.setuptools]
 package-dir = {"" = "src"}