Nils Andreas Svee
97bd903769
8.2 KiB
irtt-tui
Name
irtt-tui - IRTT-compatible terminal UI client
Synopsis
irtt-tui [OPTIONS] [LABEL=]TARGET...
Description
irtt-tui gives you a live graph and status dashboard using the same probing
engine as irtt-client(1). You need at least one target to start it.
Targets and pacing work the same as in irtt-client(1). See that manual
for [LABEL=]TARGET syntax, multiple targets, and the
--pacing staggered|burst option. The configuration flags
(--interval, --timeouts, --length, --hmac, --clock, --tstamp,
--stats, --sfill, --dscp, --ttl, --loose) are also shared with
irtt-client, so the same descriptions apply.
Address-family controls are shared too: -4 / --ipv4 uses IPv4 only,
-6 / --ipv6 uses IPv6 only, and --dual-stack gives each available family
of a hostname its own measurement row and graph series. These switches are
mutually exclusive. Explicit IP literals remain single targets; a literal
conflicting with -4 or -6 is rejected before the dashboard starts.
irtt-tui -4 uk-cov1.irtt.lochnair.net
irtt-tui --dual-stack cov=uk-cov1.irtt.lochnair.net
The second command creates cov/v4 and/or cov/v6 according to the system
resolver's initial results, letting you compare the two paths directly.
See the client manual's address-family section for discovery errors and labels.
Continuous default
The TUI defaults to continuous mode (--duration 0) and runs until you
quit. If you're used to irtt-client, which defaults to a finite run,
keep that difference in mind. To set a finite run, pass an explicit
--duration. Both --duration and --interval use the
client duration syntax,
including fractional values (2.5s), composite values (1m30s), and units
from nanoseconds (ns) through hours (h):
irtt-tui <server> --duration 30s
In continuous mode, the TUI reconnects after a target fails, the peer closes the session, or the session ends because the server limited its duration. After a 1.5-second delay, it groups completed targets into one retry while healthy sessions keep running. Even if every target fails, the TUI stays open until you quit.
Explicit stops, removed or replaced targets, and no-test completion do not trigger retries. Quitting cancels any pending retry work.
With --dual-stack, a failed family reconnects independently while its healthy
sibling continues. Reconnect resolves the original hostname again within the
target's family. It does not discover additional families or pin the address
returned by initial discovery.
Reconnecting keeps the target in the same row. Statistics reset when a new session generation is accepted, including attempts that fail before opening. The TUI keeps graph history and the age of the last actual reply, with a gap in the graph between generations.
Dashboard
The dashboard uses the same layout for any target count and terminal size. It shows:
- Run status, elapsed time, and finite duration or continuous mode.
- The selected target's label and remote address, plus latest signed
client-to-server and server-to-client delays (
-means unavailable). - Target rows with latest effective RTT, cumulative loss percentage, jitter (standard deviation of round-trip IPDV), and age of the last primary reply.
- A graph overlaying all targets, with matching target colors and a visible live/history indicator and window size.
An active session shows waiting until it gets a primary reply. Check the
reply age to see how fresh the displayed RTT is. The loss estimate comes
from the shared statistics collector, so outstanding sends can temporarily
count towards cumulative loss. Jitter stays - until an IPDV pair is
available.
Use Tab / Shift-Tab to select a target and bring its row into view.
The dashboard shows up to six target rows, with fewer on smaller terminals.
Selecting a target changes the identification, one-way summary, and details.
The graph still compares every target.
Press d to open details in the graph's space. You'll find the selected
target's session and negotiation, packet counters, progress, latest timing
sample, full timing statistics, and warnings, along with recent events
from all targets.
Scroll with the arrows or page keys. You can scroll horizontally to read
long lines and timing columns, including labels and remote addresses that
don't fit in the header. Press d or Esc to return to the graph with its
metric and viewport preserved. You can also use g as an alias for d.
You need a terminal at least 56 columns wide and 18 rows tall. Below that size, the TUI asks you to resize while continuing to collect measurements. Resizing and important status redraws still work when the display is paused.
Controls
| Key | Action |
|---|---|
q, Ctrl-C |
Quit |
p |
Toggle display pause (probing and acquisition continue) |
Tab / Shift-Tab |
Select next / previous target |
d, g |
Toggle target details |
Esc |
Close target details |
r |
Clear graph history for all targets; keep latest samples and statistics |
m |
Cycle graph metric (graph visible) |
← / → |
Pan graph; scroll columns in details |
↑ / ↓ |
Scroll details |
PageUp / PageDown |
Page-pan graph; page-scroll details |
Home / End |
Oldest / live graph; top / bottom of details |
+ / = |
Zoom graph in (graph visible) |
- |
Zoom graph out (graph visible) |
0 |
Reset graph window and zoom, keeping live/history position (graph visible) |
The six graph metrics are effective RTT, raw RTT, adjusted RTT, client-to-server delay, server-to-client delay, and server processing time. Signed effective/adjusted RTT and one-way values are preserved. Graph windows range from 5 seconds to 24 hours and default to one minute. The footer shows controls appropriate to the currently open graph or details sheet.
Retained history
Along with the statistics described in irtt-client(1), the TUI keeps
some history for the display:
- Up to 500,000 graph samples per target.
- Up to 80 recent status/log messages.
At 500,000 replies per target, you get approximately 13h53m20s of history with 100ms intervals, 27h46m40s at 200ms, or 5d18h53m20s at 1s. Each graph sample stores both clocks, six values ready for graphing, and a flag marking session boundaries. The latest details keep the full typed timing values and sequence number.
On 64-bit macOS, each retained sample takes 88 bytes, giving about 42 MiB per target at the cap. Statistics and temporary rendering buffers use additional memory. History grows as needed and reserves exactly to the cap on its final growth step, so you don't pay for the full history of every target at startup.
Press r to clear graph history for all targets and return to the live
view. This leaves the 500,000-sample cap unchanged. Display history is kept
in addition to the client's statistics (see Measurements and memory in
irtt-client(1)). During a long continuous TUI session, whichever uses more
memory for your target count will dominate the total.
If you set a finite --duration, the TUI retains exact statistics samples
just as irtt-client(1) does in finite mode. Memory then grows with the
probe count. The TUI does not print the memory warnings you get from
irtt-client, since a stderr warning on the alternate screen could be
invisible or corrupt the display. For a long finite run, plan memory using
the figures in irtt-client(1) under Measurements and memory, or use the
continuous default.
Exit behavior
Quitting with q or Ctrl-C counts as an interrupted, successful exit.
In continuous mode, the TUI reconnects after peer closure and target failures.
A managed driver failure or an unexpected reconnect-update failure still
ends the run with an error.
Finite runs do not reconnect. They complete after their target sessions end; a peer closure is a normal session ending, while a run whose targets all fail exits with an error.
Examples
irtt-tui host.example
irtt-tui eu=host.example
irtt-tui eu=host-a.example us=host-b.example --pacing burst
irtt-tui host.example --duration 30s
See also
irtt-client(1) for target syntax, pacing, negotiation flags, and
finite/continuous memory behavior; irtt-server(1); irtt-rs(1).