git: ce581fb02fc1 - stable/13 - siftr: document siftr probe to man page of the tcp provider

From: Michael Tuexen <tuexen_at_FreeBSD.org>
Date: Thu, 11 Jan 2024 11:32:23 UTC
The branch stable/13 has been updated by tuexen:

URL: https://cgit.FreeBSD.org/src/commit/?id=ce581fb02fc158b9edd749eadd80f957599020e3

commit ce581fb02fc158b9edd749eadd80f957599020e3
Author:     Michael Tuexen <tuexen@FreeBSD.org>
AuthorDate: 2023-06-30 22:13:00 +0000
Commit:     Michael Tuexen <tuexen@FreeBSD.org>
CommitDate: 2024-01-11 11:32:08 +0000

    siftr: document siftr probe to man page of the tcp provider
    
    This man page documents what is currently implemented in siftr.d.
    It doesn't work right now in head, but in stable/13. Follow-up
    commits will fix it for head.
    
    Reviewed by:            cc, pauamma_gundo.com
    Sponsored by:           Netflix, Inc.
    Differential Revision:  https://reviews.freebsd.org/D40809
    
    (cherry picked from commit 0631830a7a3c9625f1678b0b6ab8b525ba5e3873)
---
 share/man/man4/dtrace_tcp.4 | 138 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 136 insertions(+), 2 deletions(-)

diff --git a/share/man/man4/dtrace_tcp.4 b/share/man/man4/dtrace_tcp.4
index 7d300d0f8068..fa21cb981ed5 100644
--- a/share/man/man4/dtrace_tcp.4
+++ b/share/man/man4/dtrace_tcp.4
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd June 29, 2023
+.Dd July 1, 2023
 .Dt DTRACE_TCP 4
 .Os
 .Sh NAME
@@ -47,6 +47,7 @@ protocol
     "tcpinfo_t *"
 .Fn tcp:::state-change "void *" "csinfo_t *" "void *" "tcpsinfo_t *" "void *" \
     "tcplsinfo_t *"
+.Fn tcp:::siftr "siftrinfo_t *"
 .Sh DESCRIPTION
 The DTrace
 .Nm tcp
@@ -63,6 +64,8 @@ All
 .Nm tcp
 probes except for
 .Fn tcp:::state-change
+and
+.Fn tcp:::siftr
 have the same number and type of arguments.
 The last three arguments are used to describe a TCP segment: the
 .Vt ipinfo_t
@@ -134,6 +137,15 @@ Its first, third and fifth arguments are currently always
 Its last argument describes the from-state in the transition, and the to-state
 can be obtained from
 .Dv args[3]->tcps_state .
+.Pp
+The
+.Fn tcp:::siftr
+probe fires when a TCP segment is sent or received by the host.
+For a detailed description see
+.Xr siftr 4 .
+The
+.Vt siftrinfo_t
+argument provides the information about the TCP connection.
 .Sh ARGUMENTS
 The
 .Vt pktinfo_t
@@ -283,10 +295,111 @@ The valid TCP state values are given by the constants prefixed with
 in
 .Pa /usr/lib/dtrace/tcp.d .
 .El
+.Pp
+The
+.Vt siftrinfo_t
+type is used by the
+.Fn tcp:::siftr
+probe to provide the state of the TCP connection.
+Its fields are:
+.Bl -tag -width "u_int sent_inflight_bytes" -offset indent
+.It Vt uint8_t direction
+Direction of packet that triggered the log message.
+Either
+.Qq 0
+for in, or
+.Qq 1
+for out.
+.It Vt uint8_t ipver
+The version of the IP protocol being used.
+Either
+.Qq 1
+for IPv4, or
+.Qq 2
+for IPv6.
+.It Vt uint32_t hash
+Hash of the packet that triggered the log message.
+.It Vt uint16_t tcp_localport
+The TCP port that the local host is communicating via.
+.It Vt uint16_t tcp_foreignport
+The TCP port that the foreign host is communicating via.
+.It Vt uint64_t snd_cwnd
+The current congestion window (CWND) for the flow, in bytes.
+.It Vt u_long snd_wnd
+The current sending window for the flow, in bytes.
+The post scaled value is reported, except during the initial handshake (first
+few packets), during which time the unscaled value is reported.
+.It Vt u_long rcv_wnd
+The current receive window for the flow, in bytes.
+The post scaled value is always reported.
+.It Vt u_long snd_bwnd
+The current bandwidth-controlled window for the flow, in bytes.
+This field is currently unused and reported as zero.
+.It Vt u_long snd_ssthresh
+The slow start threshold (SSTHRESH) for the flow, in bytes.
+.It Vt int conn_state
+A TCP state.
+The valid TCP state values are given by the constants prefixed with
+.Ql TCPS_
+in
+.Pa /usr/lib/dtrace/tcp.d .
+.It Vt u_int max_seg_size
+The maximum segment size for the flow, in bytes.
+.It Vt int smoothed_rtt
+The current smoothed RTT estimate for the flow, in units of TCP_RTT_SCALE * HZ,
+where TCP_RTT_SCALE is a define found in
+.Pa /usr/include/netinet/tcp_var.h ,
+and HZ is the kernel's tick timer.
+Divide by TCP_RTT_SCALE * HZ to get the RTT in secs.
+.It Vt u_char sack_enabled
+SACK enabled indicator. 1 if SACK enabled, 0 otherwise.
+.It Vt u_char snd_scale
+The current window scaling factor for the sending window.
+.It Vt u_char rcv_scale
+The current window scaling factor for the receiving window.
+.It Vt u_int flags
+The current value of the t_flags for the flow.
+.It Vt int rxt_length
+The current retransmission timeout length for the flow, in units of HZ, where HZ
+is the kernel's tick timer.
+Divide by HZ to get the timeout length in seconds.
+.It Vt u_int snd_buf_hiwater
+The current size of the socket send buffer in bytes.
+.It Vt u_int snd_buf_cc
+The current number of bytes in the socket send buffer.
+.It Vt u_int rcv_buf_hiwater
+The current size of the socket receive buffer in bytes.
+.It Vt u_int rcv_buf_cc
+The current number of bytes in the socket receive buffer.
+.It Vt u_int sent_inflight_bytes
+The current number of unacknowledged bytes in-flight.
+Bytes acknowledged via SACK are not excluded from this count.
+.It Vt int t_segqlen
+The current number of segments in the reassembly queue.
+.It Vt u_int flowid
+Flowid for the connection.
+A caveat: Zero '0' either represents a valid flowid or a default value when
+the flowid is not being set.
+.It Vt u_int flowtype
+Flow type for the connection.
+Flowtype defines which protocol fields are hashed to produce the flowid.
+A complete listing is available in
+.Pa /usr/include/sys/mbuf.h
+under
+.Dv M_HASHTYPE_* .
+.El
 .Sh FILES
-.Bl -tag -width "/usr/lib/dtrace/tcp.d" -compact
+.Bl -tag -width "/usr/lib/dtrace/siftr.d" -compact
 .It Pa /usr/lib/dtrace/tcp.d
+DTrace type and translator definitions for all the probes of the
+.Nm tcp
+provider except the
+.Nm siftr
+probe.
+.It Pa /usr/lib/dtrace/siftr.d
 DTrace type and translator definitions for the
+.Nm siftr
+probe of the
 .Nm tcp
 provider.
 .El
@@ -365,6 +478,26 @@ tcp:::state-change
         last[args[1]->cs_cid] = timestamp;
 }
 .Ed
+The following script uses the siftr probe to show the current value of CWND
+and SSTHRESH when a packet is sent or received:
+.Bd -literal -offset indent
+#pragma D option quiet
+#pragma D option switchrate=10hz
+
+dtrace:::BEGIN
+{
+        printf(" %3s %5s %5s %10s %10s\\n",
+               "DIR", "LPORT", "RPORT", "CWND", "SSTHRESH");
+}
+
+tcp:::siftr
+{
+        printf(" %3s %5d %5d %10d %10d\\n",
+            siftr_dir_string[args[0]->direction],
+            args[0]->tcp_localport, args[0]->tcp_foreignport,
+            args[0]->snd_cwnd, args[0]->snd_ssthresh);
+}
+.Ed
 .Sh COMPATIBILITY
 This provider is compatible with the
 .Nm tcp
@@ -375,6 +508,7 @@ provider in Solaris.
 .Xr dtrace_sctp 4 ,
 .Xr dtrace_udp 4 ,
 .Xr dtrace_udplite 4 ,
+.Xr siftr 4 ,
 .Xr tcp 4 ,
 .Xr SDT 9
 .Sh HISTORY