ip-tcp_metrics

ip tcp_metrics { show | flush } [ ADDRESS ] [ dev NAME ] [ table TABLE_ID ]

show
    Displays the cached TCP metrics for specified or all destinations.

flush
    Clears the cached TCP metrics for specified or all destinations. Requires root privileges.

ADDRESS
    An optional destination IP address (IPv4 or IPv6) for which to show or flush metrics. If omitted, all cached entries are displayed/flushed.

dev NAME
    An optional network device name (e.g., eth0) to filter metrics by the outgoing interface.

table TABLE_ID
    An optional routing table ID to filter metrics associated with a specific routing table.

The ip tcp_metrics command is part of the iproute2 suite, providing an interface to the Linux kernel's TCP metrics cache. This cache stores performance-related information for various network paths, such as Round Trip Time (RTT), congestion window, reordering, and retransmission statistics, for destinations that the kernel has previously communicated with.

By analyzing these cached metrics, system administrators and network engineers can gain insights into the performance characteristics of specific network routes without actively establishing new connections. This is invaluable for network troubleshooting, identifying congested paths, or verifying network configuration changes. The command allows users to display these metrics or to flush (clear) them, forcing the kernel to re-evaluate the path characteristics for future connections. These cached values are used by the kernel to optimize TCP behavior for subsequent connections to the same destination.

The metrics displayed by ip tcp_metrics are cached by the kernel; they represent historical data for previous connections and might not reflect the current real-time performance of a path, especially if network conditions have recently changed.

The kernel periodically ages out or invalidates entries in the cache, and certain network events (like link changes) can also trigger a flush. Flushing the cache can temporarily affect performance for new connections as the kernel re-learns path characteristics.

Flushing metrics requires root privileges.

The output of ip tcp_metrics show typically includes fields such as:

• rtt: Round Trip Time (smoothed average).
• rttvar: RTT variance, indicating the stability of the RTT.
• ato: Ack Timeout (timeout for acknowledgements).
• pmtu: Path Maximum Transmission Unit (largest packet size that can traverse the path without fragmentation).
• reordering: Number of times packets were received out of order.
• retrans: Number of retransmissions.
• ssthresh: Slow start threshold.
• cwnd: Congestion Window.
• last_output/last_input: Timestamps of the last packet sent/received for this path.

Understanding these values can help diagnose network performance issues, such as high latency (high RTT), packet loss (high retransmissions), or MTU problems.

The TCP metrics cache is an internal data structure within the Linux kernel's networking stack. It's populated dynamically as TCP connections are established and data is exchanged. The kernel uses these cached values to optimize subsequent TCP connections to the same destination, potentially allowing for faster ramp-up of bandwidth and more efficient congestion control. The cache helps reduce the overhead of re-discovering optimal path parameters for every new connection to a host that has been communicated with recently.

The ip tcp_metrics command is part of the iproute2 utility suite, which has progressively replaced older network configuration tools like net-tools (e.g., ifconfig, route, netstat) in modern Linux distributions. The caching of TCP metrics within the kernel has been a fundamental optimization for TCP performance for a long time, allowing the kernel to avoid repeated path discovery and setup costs for common destinations. The ip tcp_metrics command provides a user-space interface to inspect and manage this internal kernel mechanism, evolving alongside the kernel's networking capabilities to offer more granular control and visibility.

ip(8), ss(8), route(8), netstat(8), tcp(7)