bcc-tcpstates(8)

1tcpstates(8)                System Manager's Manual               tcpstates(8)
2
3
4

NAME

6       tcpstates  - Trace TCP session state changes with durations. Uses Linux
7       eBPF/bcc.
8

SYNOPSIS

10       tcpstates [-h] [-T] [-t] [-w] [-s] [-D PORTS] [-L PORTS] [-Y] [-4 | -6]
11

DESCRIPTION

13       This tool traces TCP session state changes while  tracing,  and  prints
14       details including the duration in each state. This can help explain the
15       latency of TCP connections: whether the time is  spent  in  the  ESTAB‐
16       LISHED state (data transfer), or initialization state (SYN_SENT), etc.
17
18       This  tool  works  using the sock:inet_sock_set_state tracepoint, which
19       was added to Linux 4.16. Linux 4.16 also included extra  state  transi‐
20       tions so that all TCP transitions could be observed by this tracepoint.
21
22       Only  TCP state changes are traced, so it is expected that the overhead
23       of this tool is much lower than typical send/receive tracing.
24
25       Since this uses BPF, only the root user can use this tool.
26

REQUIREMENTS

28       CONFIG_BPF and bcc, and the sock:inet_sock_set_state tracepoint.
29

OPTIONS

31       -h     Print usage message.
32
33       -s     Comma separated values output (parseable).
34
35       -t     Include a timestamp column (seconds).
36
37       -T     Include a time column (HH:MM:SS).
38
39       -w     Wide column output (fits IPv6 addresses).
40
41       -L PORTS
42              Comma-separated list of local ports to trace  (filtered  in-ker‐
43              nel).
44
45       -D PORTS
46              Comma-separated list of destination ports to trace (filtered in-
47              kernel).
48
49       -Y     Log session state changes to the systemd journal.
50
51       -4     Trace IPv4 family only.
52
53       -6     Trace IPv6 family only.
54

EXAMPLES

56       Trace all TCP sessions, and show all state changes:
57              # tcpstates
58
59       Include a timestamp column, and wide column output:
60              # tcpstates -tw
61
62       Trace connections to local ports 80 and 81 only:
63              # tcpstates -L 80,81
64
65       Trace connections to remote port 80 only:
66              # tcpstates -D 80
67
68       Trace IPv4 family only:
69              # tcpstates -4
70
71       Trace IPv6 family only:
72              # tcpstates -6
73

FIELDS

75       TIME   Time of the change, in HH:MM:SS format.
76
77       TIME(s)
78              Time of the change, in seconds.
79
80       C-PID  The current on-CPU process ID. This may show  the  process  that
81              owns the TCP session if the state change executes in synchronous
82              process context, else it is likely to show the kernel (asynchro‐
83              nous state change).
84
85       C-COMM The  current on-CPU process name. This may show the process that
86              owns the TCP session if the state change executes in synchronous
87              process context, else it is likely to show the kernel (asynchro‐
88              nous state change).
89
90       IP     IP address family (4 or 6)
91
92       LADDR  Local IP address.
93
94       RADDR  Remote IP address.
95
96       LPORT  Local port.
97
98       RPORT  Remote port.
99
100       OLDSTATE
101              Previous TCP state.
102
103       NEWSTATE
104              New TCP state.
105
106       MS     Duration of this state.
107

OVERHEAD

109       This traces the kernel TCP set state function, which should  be  called
110       much  less  often  than  send/receive tracing, and therefore have lower
111       overhead. The overhead of the tool is relative to the rate of  new  TCP
112       sessions:  if  this  is high, over 10,000 per second, then there may be
113       noticeable overhead just to print out 10k lines of formatted output per
114       second.
115
116       You can find out the rate of new TCP sessions using "sar -n TCP 1", and
117       adding the active/s and passive/s columns.
118
119       As always, test and understand this tools overhead for  your  types  of
120       workloads before production use.
121

SOURCE

123       This is from bcc.
124
125              https://github.com/iovisor/bcc
126
127       Also  look  in  the bcc distribution for a companion _examples.txt file
128       containing example usage, output, and commentary for this tool.
129

OS

131       Linux
132

STABILITY

134       Unstable - in development.
135

AUTHOR

137       Brendan Gregg
138