| .TH tcpsynbl 8 "2019-07-03" "USER COMMANDS" |
| .SH NAME |
| tcpsynbl \- Show the TCP SYN backlog as a histogram. Uses BCC/eBPF. |
| .SH SYNOPSIS |
| .B tcpsynbl [\-4 | \-6] |
| .SH DESCRIPTION |
| This tool shows the TCP SYN backlog size during SYN arrival as a histogram. |
| This lets you see how close your applications are to hitting the backlog limit |
| and dropping SYNs (causing performance issues with SYN retransmits), and is a |
| measure of workload saturation. The histogram shown is measured at the time of |
| SYN received, and a separate histogram is shown for each backlog limit. |
| |
| This works by tracing the tcp_v4_syn_recv_sock() and tcp_v6_syn_recv_sock() |
| kernel functions using dynamic instrumentation. Since these functions may |
| change in future kernels, this tool may need maintenance to keep working. |
| |
| Since this uses BPF, only the root user can use this tool. |
| .SH REQUIREMENTS |
| CONFIG_BPF and BCC. |
| .SH OPTIONS |
| .TP |
| \-h |
| Print usage message. |
| .TP |
| \-4 |
| Trace IPv4 family only. |
| .TP |
| \-6 |
| Trace IPv6 family only. |
| .SH EXAMPLES |
| .TP |
| Show the TCP SYN backlog as a histogram. |
| # |
| .B tcpsynbl |
| .TP |
| Trace IPv4 family only: |
| # |
| .B tcpsynbl -4 |
| .TP |
| Trace IPv6 family only: |
| # |
| .B tcpsynbl -6 |
| .SH FIELDS |
| .TP |
| backlog |
| The backlog size when a SYN was received. |
| .TP |
| count |
| The number of times this backlog size was encountered. |
| .TP |
| distribution |
| An ASCII visualization of the count column. |
| .SH OVERHEAD |
| Inbound SYNs should be relatively low compared to packets and other events, |
| so the overhead of this tool is expected to be negligible. |
| .SH SOURCE |
| This originated as a bpftrace tool from the book "BPF Performance Tools", |
| published by Addison Wesley (2019): |
| .IP |
| http://www.brendangregg.com/bpf-performance-tools-book.html |
| .PP |
| See the book for more documentation on this tool. |
| .PP |
| This version is in the BCC repository: |
| .IP |
| https://github.com/iovisor/bcc |
| .PP |
| Also look in the bcc distribution for a companion _examples.txt file |
| containing example usage, output, and commentary for this tool. |
| .SH OS |
| Linux |
| .SH STABILITY |
| Unstable - in development. |
| .SH AUTHOR |
| Brendan Gregg |
| .SH SEE ALSO |
| tcptop(8) |
