bcc-tcplife(8)

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

NAME

6       tcplife  -  Trace  TCP  sessions  and  summarize  lifespan.  Uses Linux
7       eBPF/bcc.
8

SYNOPSIS

10       tcplife [-h] [-T] [-t] [-w] [-s] [-p PID] [-D PORTS] [-L PORTS]
11

DESCRIPTION

13       This tool traces TCP sessions that open and close  while  tracing,  and
14       prints  a  line  of  output to summarize each one. This includes the IP
15       addresses, ports, duration, and throughput for  the  session.  This  is
16       useful  for  workload characterisation and flow accounting: identifying
17       what connections are happening, with the bytes transferred.
18
19       This tool works using the  sock:inet_sock_set_state  tracepoint  if  it
20       exists, added to Linux 4.16, and switches to using kernel dynamic trac‐
21       ing for older kernels. Only TCP state changes  are  traced,  so  it  is
22       expected  that  the  overhead  of  this tool is much lower than typical
23       send/receive tracing.
24
25       Since this uses BPF, only the root user can use this tool.
26

REQUIREMENTS

28       CONFIG_BPF and bcc.
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       -p PID Trace this process ID only (filtered in-kernel).
42
43       -L PORTS
44              Comma-separated list of local ports to trace  (filtered  in-ker‐
45              nel).
46
47       -D PORTS
48              Comma-separated list of destination ports to trace (filtered in-
49              kernel).
50

EXAMPLES

52       Trace all TCP sessions, and summarize lifespan and throughput:
53              # tcplife
54
55       Include a timestamp column, and wide column output:
56              # tcplife -tw
57
58       Trace PID 181 only:
59              # tcplife -p 181
60
61       Trace connections to local ports 80 and 81 only:
62              # tcplife -L 80,81
63
64       Trace connections to remote port 80 only:
65              # tcplife -D 80
66

FIELDS

68       TIME   Time of the call, in HH:MM:SS format.
69
70       TIME(s)
71              Time of the call, in seconds.
72
73       PID    Process ID
74
75       COMM   Process name
76
77       IP     IP address family (4 or 6)
78
79       LADDR  Local IP address.
80
81       RADDR  Remote IP address.
82
83       LPORT  Local port.
84
85       RPORT  Remote port.
86
87       TX_KB  Total transmitted Kbytes.
88
89       RX_KB  Total received Kbytes.
90
91       MS     Lifespan of the session, in milliseconds.
92

OVERHEAD

94       This traces the kernel TCP set state function, which should  be  called
95       much  less  often  than  send/receive tracing, and therefore have lower
96       overhead. The overhead of the tool is relative to the rate of  new  TCP
97       sessions:  if  this  is high, over 10,000 per second, then there may be
98       noticeable overhead just to print out 10k lines of formatted output per
99       second.
100
101       You can find out the rate of new TCP sessions using "sar -n TCP 1", and
102       adding the active/s and passive/s columns.
103
104       As always, test and understand this tools overhead for  your  types  of
105       workloads before production use.
106

SOURCE

108       This is from bcc.
109
110              https://github.com/iovisor/bcc
111
112       Also  look  in  the bcc distribution for a companion _examples.txt file
113       containing example usage, output, and commentary for this tool.
114

OS

116       Linux
117

STABILITY

119       Unstable - in development.
120

AUTHOR

122       Brendan Gregg
123