irtt-rs/README.md

irtt-rs

irtt-rs is a Rust implementation of an IRTT-compatible client.

It is not the upstream IRTT project. For the original implementation, protocol background, and broader project documentation, see:

https://github.com/heistp/irtt

Status

This repository currently provides:

• irtt-cli, a command-line IRTT-compatible client
• irtt-client, a Rust library for running client sessions and consuming events
• finite and continuous probe runs
• human, simple, machine-readable, and RTT-only output modes
• optional local summary statistics

Server support is not implemented.

Install

Requires Rust 1.75 or newer.

From a local checkout:

git clone https://github.com/Lochnair/irtt-rs.git
cd irtt-rs
cargo install --path crates/irtt-cli

Or run it directly without installing:

cargo run -p irtt-cli -- <server>

CLI usage

Basic test:

irtt-cli <server>

Set duration and interval:

irtt-cli <server> --duration 30s --interval 100ms

Run continuously:

irtt-cli <server> --duration 0

Use a specific output mode:

irtt-cli <server> --output human
irtt-cli <server> --output simple
irtt-cli <server> --output machine
irtt-cli <server> --output rtt-us

For available options:

irtt-cli --help

Machine output

Use --output machine for line-oriented key=value output intended for scripts, monitoring, and autorate consumers.

Example:

irtt-cli <server> --duration 0 --interval 250ms --output machine

Each line represents one client event and starts with an event field, for example:

event=echo_reply seq=4 logical_seq=4 remote=203.0.113.10:2112 raw_rtt_us=12400 effective_rtt_us=12100 adjusted_rtt_us=12100 server_processing_us=300 dscp=0 ecn=0 kernel_rx_ns=none

Consumers should match on event=... and read the fields they need. Unknown fields should be ignored.

For consumers that only need RTT values, use:

irtt-cli <server> --output rtt-us

Library usage

irtt-client can be used directly from Rust code.

Example Cargo.toml dependency from a local checkout:

[dependencies]
irtt-client = { path = "crates/irtt-client" }

Minimal managed-client example:

use std::time::Duration;

use irtt_client::{
    ClientConfig, ClientEvent, ManagedClient, SubscriberConfig,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfig {
        server_addr: "netperf-eu.bufferbloat.net:2112".to_owned(),
        duration: Some(Duration::from_secs(10)),
        interval: Duration::from_secs(1),
        ..ClientConfig::default()
    };

    let (session, events) =
        ManagedClient::start_with_subscription(config, SubscriberConfig::default())?;

    while let Ok(event) = events.recv() {
        match event {
            ClientEvent::EchoReply { seq, rtt, .. } => {
                println!("seq={seq} rtt_us={}", rtt.effective.as_micros());
            }
            ClientEvent::SessionClosed { .. } => break,
            _ => {}
        }
    }

    let outcome = session.join()?;
    println!("session ended: {:?}", outcome.end_reason);

    Ok(())
}