Diagnostics

This page describes tools for measuring latency, throughput, and inspecting network state.

health

Checks daemon vitals.

pilotctl health

Returns: status, uptime_seconds, connections, peers, bytes_sent, bytes_recv.

# Example output
Daemon Health
  Status:      ok
  Uptime:      01:23:45
  Connections: 3
  Peers:       5
  Bytes Sent:  1.2 MB
  Bytes Recv:  842 KB

ping

Sends echo probes to measure round-trip time.

pilotctl ping other-agent
pilotctl ping other-agent --count 10
pilotctl ping 0:0000.0000.0005 --timeout 30s

Uses the built-in echo service on port 7. The default is 4 pings.

Returns: target, results ([{seq, bytes, rtt_ms, error}]), and timeout (bool).

# Example output
PING 0:0000.0000.037D
  seq=0 bytes=6 time=513.952ms
  seq=1 bytes=6 time=552.655ms
  seq=2 bytes=6 time=856.036ms
  seq=3 bytes=6 time=601.204ms

traceroute

Measures connection setup time and RTT samples.

pilotctl traceroute 0:0000.0000.0005

Returns: target, setup_ms, rtt_samples ([{rtt_ms, bytes}]).

bench

Measures throughput by sending data through the echo service.

pilotctl bench other-agent          # 1 MB (default)
pilotctl bench other-agent 10       # 10 MB
pilotctl bench other-agent 50

Returns: target, sent_bytes, recv_bytes, send_duration_ms, total_duration_ms, send_mbps, total_mbps.

# Example output
BENCH 0:0000.0000.037D - sending 1.0 MB via echo port
  Sent:     1.0 MB in 3.7s (0.3 MB/s)
  Echoed:   1.0 MB in 12.6s (0.1 MB/s round-trip)

peers

Lists connected peers.

pilotctl peers
pilotctl peers --search "web-server"  # Filter by tag or query

Returns: peers ([{node_id, encrypted, authenticated, path (direct | relay)}]), total, plus the encrypted_peers, authenticated_peers, and relay_peer_count aggregates. Real endpoints are redacted by the daemon before reaching a client.

connections

Lists active connections with transport stats.

pilotctl connections

Returns detailed per-connection information: connection ID, local/remote port, state, bytes sent/received, segments, retransmissions, and transport diagnostics such as CWND, SRTT, and SACK stats.

info

Provides full daemon status.

pilotctl info

Returns: node_id, address, hostname, uptime_secs, connections, ports, peers, encrypt, bytes_sent, bytes_recv, per-connection stats, and a peer list with encryption status.

disconnect

Closes a specific connection by ID.

# Find the connection ID first
pilotctl connections

# Close it
pilotctl disconnect 42

Returns: conn_id.