git: 0631830a7a3c - main - siftr: document siftr probe to man page of the tcp provider
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 30 Jun 2023 23:30:51 UTC
The branch main has been updated by tuexen:
URL: https://cgit.FreeBSD.org/src/commit/?id=0631830a7a3c9625f1678b0b6ab8b525ba5e3873
commit 0631830a7a3c9625f1678b0b6ab8b525ba5e3873
Author: Michael Tuexen <tuexen@FreeBSD.org>
AuthorDate: 2023-06-30 22:13:00 +0000
Commit: Michael Tuexen <tuexen@FreeBSD.org>
CommitDate: 2023-06-30 22:18:15 +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
MFC after: 3 days
Sponsored by: Netflix, Inc.
Differential Revision: https://reviews.freebsd.org/D40809
---
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 5372b1a858f0..205317819c56 100644
--- a/share/man/man4/dtrace_tcp.4
+++ b/share/man/man4/dtrace_tcp.4
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd June 29, 2023
+.Dd July 1, 2023
.Dt DTRACE_TCP 4
.Os
.Sh NAME
@@ -49,6 +49,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
@@ -65,6 +66,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
@@ -136,6 +139,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
@@ -285,10 +297,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
@@ -367,6 +480,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
@@ -377,6 +510,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