Install Now
dtrace_tcp — a DTrace provider for tracing events related to the tcp(4) protocol
Contents
Arguments
The pktinfo_t argument is currently unimplemented and is included for compatibility with other
implementations of this provider. Its fields are:
uinptr_tpkt_addr Always set to 0.
The csinfo_t argument is currently unimplemented and is included for compatibility with other
implementations of this provider. Its fields are:
uintptr_tcs_addr Always set to 0.
uint64_tcs_cid A pointer to the structinpcb for this packet, or NULL.
pid_tcs_pid Always set to 0.
The ipinfo_t type is a version-agnostic representation of fields from an IP header. Its fields are
described in the dtrace_ip(4) manual page.
The tcpsinfo_t type is used to provide a stable representation of TCP connection state. Some tcp probes,
such as tcp:::accept-refused(), fire in a context where there is no TCP connection; this argument is NULL
in that case. Its fields are:
uintptr_ttcps_addr The address of the corresponding TCP control block. This is currently a
pointer to a structtcpcb.
inttcps_local A boolean indicating whether the connection is local to the host. Currently
unimplemented and always set to -1.
inttcps_active A boolean indicating whether the connection was initiated by the local host.
Currently unimplemented and always set to -1.
uint16_ttcps_lport Local TCP port.
uint16_ttcps_rport Remote TCP port.
stringtcps_laddr Local address.
stringtcps_raddr Remote address.
int32_ttcps_state Current TCP state. The valid TCP state values are given by the constants
prefixed with ‘TCPS_’ in /usr/lib/dtrace/tcp.d.
uint32_ttcps_iss Initial send sequence number.
uint32_ttcps_suna Initial sequence number of sent but unacknowledged data.
uint32_ttcps_snxt Next sequence number for send.
uint32_ttcps_rack Sequence number of received and acknowledged data.
uint32_ttcps_rnxt Next expected sequence number for receive.
u_longtcps_swnd TCP send window size.
int32_ttcps_snd_ws Window scaling factor for the TCP send window.
u_longtcps_rwnd TCP receive window size.
int32_ttcps_rcv_ws Window scaling factor for the TCP receive window.
u_longtcps_cwnd TCP congestion window size.
u_longtcps_cwnd_ssthresh
Congestion window threshold at which slow start ends and congestion avoidance
begins.
uint32_ttcps_sack_fack
Last sequence number selectively acknowledged by the receiver.
uint32_ttcps_sack_snxt
Next selectively acknowledge sequence number at which to begin retransmitting.
uint32_ttcps_rto Round-trip timeout, in milliseconds.
uint32_ttcps_mss Maximum segment size.
inttcps_retransmit A boolean indicating that the local sender is retransmitting data.
inttcps_srtt Smoothed round-trip time.
The tcpinfo_t type exposes the fields in a TCP segment header in host order. Its fields are:
uint16_ttcp_sport Source TCP port.
uint16_ttcp_dport Destination TCP port.
uint32_ttcp_seq Sequence number.
uint32_ttcp_ack Acknowledgement number.
uint8_ttcp_offset Data offset, in bytes.
uint8_ttcp_flags TCP flags.
uint16_ttcp_window TCP window size.
uint16_ttcp_checksum Checksum.
uint16_ttcp_urgent Urgent data pointer.
structtcphdr*tcp_hdr A pointer to the raw TCP header.
The tcplsinfo_t type is used by the tcp:::state-change() probe to provide the from-state of a transition.
Its fields are:
int32_ttcps_state A TCP state. The valid TCP state values are given by the constants prefixed
with ‘TCPS_’ in /usr/lib/dtrace/tcp.d.
Bugs
The tcps_local and tcps_active fields of tcpsinfo_t are not filled in by the translator.
Debian August 1, 2018 DTRACE_TCP(4)
Compatibility
This provider is compatible with the tcp provider in Solaris.
Description
The DTrace tcp provider allows users to trace events in the tcp(4) protocol implementation. This
provider is similar to the dtrace_ip(4) and dtrace_udp(4) providers, but additionally contains probes
corresponding to protocol events at a level higher than packet reception and transmission. All tcp
probes except for tcp:::state-change() have the same number and type of arguments. The last three
arguments are used to describe a TCP segment: the ipinfo_t argument exposes the version-agnostic fields
of the IP header, while the tcpinfo_t argument exposes the TCP header, and the tcpsinfo_t argument
describes details of the corresponding TCP connection state, if any. Their fields are described in the
ARGUMENTS section.
The tcp:::accept-established() probe fires when a remotely-initiated active TCP open succeeds. At this
point the new connection is in the ESTABLISHED state, and the probe arguments expose the headers
associated with the final ACK of the three-way handshake. The tcp:::accept-refused() probe fires when a
SYN arrives on a port without a listening socket. The probe arguments expose the headers associated with
the RST to be transmitted to the remote host in response to the SYN segment.
The tcp:::connect-established(), tcp:::connect-refused(), and tcp:::connect-request() probes are similar
to the ‘accept’ probes, except that they correspond to locally-initiated TCP connections. The
tcp:::connect-established() probe fires when the SYN-ACK segment of a three-way handshake is received
from the remote host and a final ACK is prepared for transmission. This occurs immediately after the
local connection state transitions from SYN-SENT to ESTABLISHED. The probe arguments describe the
headers associated with the received SYN-ACK segment. The tcp:::connect-refused() probe fires when the
local host receives a RST segment in response to a SYN segment, indicating that the remote host refused
to open a connection. The probe arguments describe the IP and TCP headers associated with the received
RST segment. The tcp:::connect-request() probe fires as the kernel prepares to transmit the initial SYN
segment of a three-way handshake.
The tcp:::send() and tcp:::receive() probes fire when the host sends or receives a TCP packet,
respectively. As with the dtrace_udp(4) provider, tcp probes fire only for packets sent by or to the
local host; forwarded packets are handled in the IP layer and are only visible to the dtrace_ip(4)
provider.
The tcp:::state-change() probe fires upon local TCP connection state transitions. Its first, third and
fifth arguments are currently always NULL. Its last argument describes the from-state in the transition,
and the to-state can be obtained from args[3]->tcps_state.
Examples
The following script logs TCP segments in real time:
#pragma D option quiet
#pragma D option switchrate=10hz
dtrace:::BEGIN
{
printf(" %3s %15s:%-5s %15s:%-5s %6s %s\n", "CPU",
"LADDR", "LPORT", "RADDR", "RPORT", "BYTES", "FLAGS");
}
tcp:::send
{
this->length = args[2]->ip_plength - args[4]->tcp_offset;
printf(" %3d %16s:%-5d -> %16s:%-5d %6d (", cpu, args[2]->ip_saddr,
args[4]->tcp_sport, args[2]->ip_daddr, args[4]->tcp_dport,
this->length);
printf("%s", args[4]->tcp_flags & TH_FIN ? "FIN|" : "");
printf("%s", args[4]->tcp_flags & TH_SYN ? "SYN|" : "");
printf("%s", args[4]->tcp_flags & TH_RST ? "RST|" : "");
printf("%s", args[4]->tcp_flags & TH_PUSH ? "PUSH|" : "");
printf("%s", args[4]->tcp_flags & TH_ACK ? "ACK|" : "");
printf("%s", args[4]->tcp_flags & TH_URG ? "URG|" : "");
printf("\s", args[4]->tcp_flags == 0 ? "null " : "");
printf("n;
} "
tcp:::receive
{
this->length = args[2]->ip_plength - args[4]->tcp_offset;
printf(" %3d %16s:%-5d <- %16s:%-5d %6d (", cpu,
args[2]->ip_daddr, args[4]->tcp_dport, args[2]->ip_saddr,
args[4]->tcp_sport, this->length);
printf("%s", args[4]->tcp_flags & TH_FIN ? "FIN|" : "");
printf("%s", args[4]->tcp_flags & TH_SYN ? "SYN|" : "");
printf("%s", args[4]->tcp_flags & TH_RST ? "RST|" : "");
printf("%s", args[4]->tcp_flags & TH_PUSH ? "PUSH|" : "");
printf("%s", args[4]->tcp_flags & TH_ACK ? "ACK|" : "");
printf("%s", args[4]->tcp_flags & TH_URG ? "URG|" : "");
printf("\s", args[4]->tcp_flags == 0 ? "null " : "");
printf("n;
} "
The following script logs TCP connection state changes as they occur:
#pragma D option quiet
#pragma D option switchrate=25hz
int last[int];
dtrace:::BEGIN
{
printf(" %12s %-20s %-20s %s\n",
"DELTA(us)", "OLD", "NEW", "TIMESTAMP");
}
tcp:::state-change
{
this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000;
printf(" %12d %-20s -> %-20s %d\n", this->elapsed,
tcp_state_string[args[5]->tcps_state],
tcp_state_string[args[3]->tcps_state], timestamp);
last[args[1]->cs_cid] = timestamp;
}
tcp:::state-change
/last[args[1]->cs_cid] == 0/
{
printf(" %12s %-20s -> %-20s %d\n", "-",
tcp_state_string[args[5]->tcps_state],
tcp_state_string[args[3]->tcps_state], timestamp);
last[args[1]->cs_cid] = timestamp;
}
Files
/usr/lib/dtrace/tcp.d DTrace type and translator definitions for the tcp provider.
History
The tcp provider first appeared in FreeBSD 10.0.
Name
dtrace_tcp — a DTrace provider for tracing events related to the tcp(4) protocol
See Also
dtrace(1), dtrace_ip(4), dtrace_sctp(4), dtrace_udp(4), dtrace_udplite(4), tcp(4), SDT(9)
Synopsis
tcp:::accept-established(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::accept-refused(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::connect-established(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::connect-refused(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::connect-request(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::receive(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::send(pktinfo_t*, csinfo_t*, ipinfo_t*, tcpsinfo_t*, tcpinfo_t*);
tcp:::state-change(void*, csinfo_t*, void*, tcpsinfo_t*, void*, tcplsinfo_t*);
PNG Icons