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]  [-4  |
11       -6]
12

DESCRIPTION

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

REQUIREMENTS

29       CONFIG_BPF and bcc.
30

OPTIONS

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

EXAMPLES

57       Trace all TCP sessions, and summarize lifespan and throughput:
58              # tcplife
59
60       Include a timestamp column, and wide column output:
61              # tcplife -tw
62
63       Trace PID 181 only:
64              # tcplife -p 181
65
66       Trace connections to local ports 80 and 81 only:
67              # tcplife -L 80,81
68
69       Trace connections to remote port 80 only:
70              # tcplife -D 80
71
72       Trace IPv4 family only:
73              # tcplife -4
74
75       Trace IPv6 family only:
76              # tcplife -6
77

FIELDS

79       TIME   Time of the call, in HH:MM:SS format.
80
81       TIME(s)
82              Time of the call, in seconds.
83
84       PID    Process ID
85
86       COMM   Process name
87
88       IP     IP address family (4 or 6)
89
90       LADDR  Local IP address.
91
92       RADDR  Remote IP address.
93
94       LPORT  Local port.
95
96       RPORT  Remote port.
97
98       TX_KB  Total transmitted Kbytes.
99
100       RX_KB  Total received Kbytes.
101
102       MS     Lifespan of the session, in milliseconds.
103

OVERHEAD

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

SOURCE

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

OS

127       Linux
128

STABILITY

130       Unstable - in development.
131

AUTHOR

133       Brendan Gregg
134