focal (8) tcpretrans-perf.8.gz

Provided by: perf-tools-unstable_1.0.1~20200130+git49b8cdf-1ubuntu1_all bug

NAME
       tcpretrans - show TCP retransmits, with address and other details. Uses Linux ftrace.


SYNOPSIS
       tcpretrans [-hsp]


DESCRIPTION
       This  traces  TCP  retransmits  that are sent by the system tcpretrans is executed from, showing address,
       port, and TCP state information, and sometimes the PID  (although  usually  not,  since  retransmits  are
       usually  sent  by  the  kernel on timeout events). To keep overhead low, only tcp_retransmit_skb() kernel
       calls are traced (this does not trace every packet).

       This was written as a proof of concept for ftrace, for older Linux systems, and without kernel debuginfo.
       It  uses  dynamic tracing of tcp_retransmit_skb(), and reads /proc/net/tcp for socket details. Its use of
       dynamic tracing  and  CPU  registers  is  an  unstable  platform-specific  workaround,  and  may  require
       modifications  to  work  on  different kernels and platforms. This would be better written using a tracer
       such as SystemTap, and will likely be rewritten in the future when certain tracing features are added  to
       the Linux kernel.

       When -l is used, this also uses dynamic tracing of tcp_send_loss_probe() and a register.

       Currently  only  IPv4 is supported, on x86_64. If you try this on a different architecture, you'll likely
       need to adjust the register locations (search for %di).

       Since this uses ftrace, only the root user can use this tool.


REQUIREMENTS
       FTRACE and KPROBE CONFIG, tcp_retransmit_skb() kernel function.  You may have these already have these on
       recent kernels. And Perl.  TCP tail loss probes were added in Linux 3.10.


OPTIONS
       -h     Print usage message.

       -s     Include kernel stack traces.

       -l     Include TCP tail loss probes.


EXAMPLES
       Trace TCP retransmits
              # tcpretrans

       TIME   Time of retransmit (may be rounded up to the nearest second).

       PID    Process  ID  that was on-CPU. This is less useful than it might sound, as it may usually be 0, for
              the kernel, for timer-based retransmits.

       LADDR  Local address.

       LPORT  Local port.

       --     Packet type: "R>" for retransmit, and "L>" for tail loss probe.

       RADDR  Remote address.

       RPORT  Remote port.

       STATE  TCP session state.


OVERHEAD
       The CPU overhead is relative to the rate of TCP retransmits, and is designed to be low as this  does  not
       examine  every  packet.  Once per second the /proc/net/tcp file is read, and a buffer of retransmit trace
       events is retrieved from the kernel and processed.


SOURCE
       This is from the perf-tools collection.

              https://github.com/brendangregg/perf-tools

       Also look under the examples directory for a text file containing example usage, output,  and  commentary
       for this tool.


OS
       Linux


STABILITY
       Unstable - in development.


AUTHOR
       Brendan Gregg


SEE ALSO
       tcpdump(1)