d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add manual pages for the io, ip, proc, sched, tcp and udp DTrace providers.

Browse Source 
The format of these pages is somewhat experimental, so they may be subject
to further tweaking.

Differential Revision:	https://reviews.freebsd.org/D2170
Reviewed by:	bcr, rpaulo
MFC after:	2 weeks
This commit is contained in:
Mark Johnston 2015-04-18 21:00:36 +00:00
parent 1321d68db0
commit b9d64941fb
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=281705
9 changed files with 1524 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
cddl/contrib/opensolaris/cmd/dtrace/dtrace.1
View File

@ -21,7 +21,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd October 5, 2013
.Dd April 18, 2015
.Dt DTRACE 1
.Os
.Sh NAME
@ -670,7 +670,8 @@ Invalid command line options or arguments were specified.
.Sh SEE ALSO
.Xr cpp 1 ,
.Xr dtruss 1 ,
.Xr elf 5
.Xr elf 5 ,
.Xr SDT 9
.Rs
.%T Solaris Dynamic Tracing Guide
.Re

15
share/man/man4/Makefile
View File

@ -121,6 +121,12 @@ MAN= aac.4 \
dpt.4 \
ds1307.4 \
ds3231.4 \
${_dtrace_io.4} \
${_dtrace_ip.4} \
${_dtrace_proc.4} \
${_dtrace_sched.4} \
${_dtrace_tcp.4} \
${_dtrace_udp.4} \
dummynet.4 \
ed.4 \
edsc.4 \
@ -812,6 +818,15 @@ SUBDIR= man4.${MACHINE_CPUARCH}
_ccd.4= ccd.4
.endif
.if ${MK_CDDL} != "no"
_dtrace_io.4= dtrace-io.4
_dtrace_ip.4= dtrace-ip.4
_dtrace_proc.4= dtrace-proc.4
_dtrace_sched.4= dtrace-sched.4
_dtrace_tcp.4= dtrace-tcp.4
_dtrace_udp.4= dtrace-udp.4
.endif
.if ${MK_ISCSI} != "no"
MAN+= iscsi.4
MAN+= iscsi_initiator.4

123
share/man/man4/dtrace-io.4 Normal file
View File

@ -0,0 +1,123 @@
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 18, 2015
.Dt DTRACE-IO 4
.Os
.Sh NAME
.Nm dtrace-io
.Nd a DTrace provider for tracing events related to disk I/O
.Sh SYNOPSIS
.Fn io:::start "struct bio *" "struct devstat *"
.Fn io:::done "struct bio *" "struct devstat *"
.Sh DESCRIPTION
The
.Nm io
provider allows the tracing of disk I/O events.
The
.Fn io:::start
probe fires when a I/O request is about to be sent to the backing driver of a
.Xr disk 9
object.
This occurs after all
.Xr GEOM 4
transformations have been performed on the request.
The
.Fn io:::done
probe fires when a I/O request is completed.
Both probes take a
.Vt "struct bio *"
representing the I/O request as their first argument.
The second argument is a
.Vt "struct devstat *"
for the underlying
.Xr disk 9
object.
.Sh ARGUMENTS
The fields of
.Vt "struct bio"
are described in the
.Xr g_bio 9
manual page, and the fields of
.Vt "struct devstat"
are described in the
.Xr devstat 9
manual page.
Translators for the
.Vt bufinfo_t
and
.Vt devinfo_t
D types are defined in
.Pa /usr/lib/dtrace/io.d .
.Sh FILES
.Bl -tag -width "/usr/lib/dtrace/io.d" -compact
.It Pa /usr/lib/dtrace/io.d
DTrace type and translator definitions for the
.Nm io
provider.
.El
.Sh EXAMPLES
The following script shows a per-process breakdown of total I/O by disk device:
.Bd -literal -offset indent
#pragma D option quiet
io:::start
{
@[args[1]->device_name, execname, pid] = sum(args[0]->bio_bcount);
}
END
{
printf("%10s %20s %10s %15s\n", "DEVICE", "APP", "PID", "BYTES");
printa("%10s %20s %10d %15@d\n", @);
}
.Ed
.Sh COMPATIBILITY
This provider is not compatible with the
.Nm io
provider found in Solaris, as its probes use native
.Fx
argument types.
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr devstat 9 ,
.Xr SDT 9
.Sh HISTORY
The
.Nm io
provider first appeared in
.Fx
9.2 and 10.0.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .
.Sh BUGS
The
.Fn io:::wait-start
and
.Fn io:::wait-done
probes are not currently implemented on
.Fx .

285
share/man/man4/dtrace-ip.4 Normal file
View File

@ -0,0 +1,285 @@
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 18, 2015
.Dt DTRACE-IP 4
.Os
.Sh NAME
.Nm dtrace-ip
.Nd a DTrace provider for tracing events related to the IPv4 and IPv6 protocols
.Sh SYNOPSIS
.Fn ip:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "ifinfo_t *" \
"ipv4info_t *" "ipv6info_t *"
.Fn ip:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "ifinfo_t *" \
"ipv4info_t *" "ipv6info_t *"
.Sh DESCRIPTION
The DTrace
.Nm ip
provider allows users to trace events in the
.Xr ip 4
and
.Xr ip6 4
protocol implementations.
The
.Fn ip:::send
probe fires whenever the kernel prepares to transmit an IP packet, and the
.Fn ip:::receive
probe fires whenever the kernel receives an IP packet.
The arguments to these probes can be used to obtain detailed information about
the IP headers of the corresponding packet, as well as the network interface on
which the packet was sent or received.
Unlike the
.Xr dtrace-tcp 4
and
.Xr dtrace-udp 4
providers,
.Nm ip
provider probes are triggered by forwarded packets.
That is, the probes will fire on packets that are not destined to the local
host.
.Sh ARGUMENTS
The
.Vt pktinfo_t
argument is currently unimplemented and is included for compatibility with other
implementations of this provider.
Its fields are:
.Bl -tag -width "uintptr_t pkt_addr" -offset indent
.It Vt uintptr_t pkt_addr
Always set to 0.
.El
.Pp
The
.Vt csinfo_t
argument is currently unimplemented and is included for compatibility with other
implementations of this provider.
Its fields are:
.Bl -tag -width "uintptr_t cs_addr" -offset indent
.It Vt uintptr_t cs_addr
Always set to 0.
.It Vt uint64_t cs_cid
A pointer to the
.Vt struct inpcb
for this packet, or
.Dv NULL .
.It Vt pid_t cs_pid
Always set to 0.
.El
.Pp
The
.Vt ipinfo_t
argument contains IP fields common to both IPv4 and IPv6 packets.
Its fields are:
.Bl -tag -width "uint32_t ip_plength" -offset indent
.It Vt uint8_t ip_ver
IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets.
.It Vt uint32_t ip_plength
IP payload size.
This does not include the size of the IP header or IPv6 option headers.
.It Vt string ip_saddr
IP source address.
.It Vt string ip_daddr
IP destination address.
.El
.Pp
The
.Vt ifinfo_t
argument describes the outgoing and incoming interfaces for the packet in the
.Fn ip:::send
and
.Fn ip:::receive
probes respectively.
Its fields are:
.Bl -tag -width "uintptr_t if_addr" -offset indent
.It Vt string if_name
The interface name.
.It Vt int8_t if_local
A boolean value indicating whether or not the interface is a loopback interface.
.It Vt uintptr_t if_addr
A pointer to the
.Vt struct ifnet
which describes the interface.
See the
.Xr ifnet 9
manual page.
.El
.Pp
The
.Vt ipv4info_t
argument contains the fields of the IP header for IPv4 packets.
This argument is
.Dv NULL
for IPv6 packets.
DTrace scripts should use the
.Fn ip_ver
field in the
.Vt ipinfo_t
argument to determine whether to use this argument.
Its fields are:
.Bl -tag -width "uint16_t ipv4_checksum" -offset indent
.It Vt uint8_t ipv4_ver
IP version.
This will always be 4 for IPv4 packets.
.It Vt uint8_t ipv4_ihl
The IP header length, including options, in 32-bit words.
.It Vt uint8_t ipv4_tos
IP type of service field.
.It Vt uint16_t ipv4_length
The total packet length, including the header, in bytes.
.It Vt uint16_t ipv4_ident
Identification field.
.It Vt uint8_t ipv4_flags
The IP flags.
.It Vt uint16_t ipv4_offset
The fragment offset of the packet.
.It Vt uint8_t ipv4_ttl
Time to live field.
.It Vt uint8_t ipv4_protocol
Next-level protocol ID.
.It Vt string ipv4_protostr
A string containing the name of the encapsulated protocol.
The protocol strings are defined in the
.Va protocol
array in
.Pa /usr/lib/dtrace/ip.d
.It Vt uint16_t ipv4_checksum
The IP checksum.
.It Vt ipaddr_t ipv4_src
IPv4 source address.
.It Vt ipaddr_t ipv4_dst
IPv4 destination address.
.It Vt string ipv4_saddr
A string representation of the source address.
.It Vt string ipv4_daddr
A string representation of the destination address.
.It Vt ipha_t *ipv4_hdr
A pointer to the raw IPv4 header.
.El
.Pp
The
.Vt ipv6info_t
argument contains the fields of the IP header for IPv6 packets.
Its fields are not set for IPv4 packets; as with the
.Vt ipv4info_t
argument, the
.Fn ip_ver
field should be used to determine whether this argument is valid.
Its fields are:
.Bl -tag -width "uint16_t ipv4_checksum" -offset indent
.It Vt uint8_t ipv6_ver
IP version.
This will always be 6 for IPv6 packets.
.It Vt uint8_t ipv6_tclass
The traffic class, used to set the differentiated services codepoint and
extended congestion notification flags.
.It Vt uint32_t ipv6_flow
The flow label of the packet.
.It Vt uint16_t ipv6_plen
The IP payload size, including extension headers, in bytes.
.It Vt uint8_t ipv6_nexthdr
An identifier for the type of the next header.
.It Vt string ipv6_nextstr
A string representation of the type of the next header.
.It Vt uint8_t ipv6_hlim
The hop limit.
.It Vt ip6_addr_t *ipv6_src
IPv6 source address.
.It Vt ip6_addr_t *ipv6_dst
IPv6 destination address.
.It Vt string ipv6_saddr
A string representation of the source address.
.It Vt string ipv6_daddr
A string representation of the destination address.
.It Vt ip6_t *ipv6_hdr
A pointer to the raw IPv6 header.
.El
.Sh FILES
.Bl -tag -width "/usr/lib/dtrace/ip.d" -compact
.It Pa /usr/lib/dtrace/ip.d
DTrace type and translator definitions for the
.Nm ip
provider.
.El
.Sh EXAMPLES
The following script counts received packets by remote host address.
.Bd -literal -offset indent
ip:::receive
{
@num[args[2]->ip_saddr] = count();
}
.Ed
.Pp
This script will print some details of each IP packet as it is sent or received
by the kernel:
.Bd -literal -offset indent
#pragma D option quiet
#pramga D option switchrate=10Hz
dtrace:::BEGIN
{
printf(" %10s %30s %-30s %8s %6s\n", "DELTA(us)", "SOURCE",
"DEST", "INT", "BYTES");
last = timestamp;
}
ip:::send
{
this->elapsed = (timestamp - last) / 1000;
printf(" %10d %30s -> %-30s %8s %6d\n", this->elapsed,
args[2]->ip_saddr, args[2]->ip_daddr, args[3]->if_name,
args[2]->ip_plength);
last = timestamp;
}
ip:::receive
{
this->elapsed = (timestamp - last) / 1000;
printf(" %10d %30s <- %-30s %8s %6d\n", this->elapsed,
args[2]->ip_daddr, args[2]->ip_saddr, args[3]->if_name,
args[2]->ip_plength);
last = timestamp;
}
.Ed
.Sh COMPATIBILITY
This provider is compatible with the
.Nm ip
providers found in Solaris and Darwin.
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr dtrace-tcp 4 ,
.Xr dtrace-udp 4 ,
.Xr ip 4 ,
.Xr ip6 4 ,
.Xr ifnet 9 ,
.Xr SDT 9
.Sh HISTORY
The
.Nm ip
provider first appeared in
.Fx
10.0.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .

264
share/man/man4/dtrace-proc.4 Normal file
View File

@ -0,0 +1,264 @@
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 18, 2015
.Dt DTRACE-PROC 4
.Os
.Sh NAME
.Nm dtrace-proc
.Nd a DTrace provider for tracing events related to user processes
.Sh SYNOPSIS
.Fn proc:::create "struct proc *" "struct proc *" "int"
.Fn proc:::exec "char *"
.Fn proc:::exec-failure "int"
.Fn proc:::exec-success "char *"
.Fn proc:::exit "int"
.Fn proc:::signal-clear "int" "ksiginfo_t *"
.Fn proc:::signal-discard "struct thread *" "struct proc *" "int"
.Fn proc:::signal-send "struct thread *" "struct proc *" "int"
.Sh DESCRIPTION
The DTrace
.Nm proc
provider provides insight into events related to user processes: process and
thread creation and termination events, and process signalling.
.Pp
The
.Fn proc:::create
probe fires when a user process is created via the
.Xr fork 2 ,
.Xr vfork 2 ,
.Xr pdfork 2 ,
or
.Xr rfork 2
system calls.
In particular, kernel processes created with the
.Xr kproc 9
KPI will not trigger this probe.
The
.Fn proc:::create
probe's first two arguments are the parent process and new child process,
respectively.
The third argument is a mask of
.Xr rfork 2
flags indicating which process resources are to be shared between the parent and
child processes.
.Pp
The
.Fn proc:::exec
probe fires when a process attempts to execute a file.
Its argument is the specified filename for the file.
If the attempt fails because of an error, the
.Fn proc:::exec-failure
probe will subsequently fire, providing the corresponding
.Xr errno 2
value in its first argument.
Otherwise, the
.Fn proc:::exec-success
probe will fire.
.Pp
The
.Fn proc:::exit
probe fires when a process exits or is terminated.
Its argument is the corresponding
.Dv SIGCHLD
signal code; valid values are documented in the
.Xr siginfo 3
manual page and defined in
.Pa signal.h .
For example, when a process exits normally, the value of
.Dv args[0]
will be
.Dv CLD_EXITED .
.Pp
The
.Fn proc:::signal-send
probe fires when a signal is about to be sent to a process.
The
.Fn proc:::signal-discard
probe fires when a signal is sent to a process that ignores it.
This probe will fire after the
.Fn proc:::signal-send
probe for the signal in question.
The arguments to these probes are the thread and process to which the signal
will be sent, and the signal number of the signal.
Valid signal numbers are defined in the
.Xr signal 3
manual page.
The
.Fn proc:::signal-clear
probe fires when a pending signal has been cleared by one of the
.Xr sigwait 2 ,
.Xr sigtimedwait 2 ,
or
.Xr sigwaitinfo 2
system calls.
Its arguments are the signal number of the cleared signal, and a pointer to
the corresponding signal information.
The
.Vt siginfo_t
for the signal can be obtained from
.Dv args[1]->ksi_info .
.Sh ARGUMENTS
Though the
.Nm proc
provider probes use native
.Fx
arguments types, standard D types for processes and threads are available.
These are
.Vt psinfo_t
and
.Vt lwpsinfo_t
respectively, and are defined in
.Pa /usr/lib/dtrace/psinfo.d .
This file also defines two global variables,
.Va curpsinfo
and
.Va curlwpsinfo ,
which provide representations of the current process and thread using these
types.
.Pp
The fields of
.Vt psinfo_t
are:
.Bl -tag -width "uintptr_t pr_addr" -offset indent
.It Vt int pr_nlwp
Number of threads in the process.
.It Vt pid_t pr_pid
Process ID.
.It Vt pid_t pr_ppid
Process ID of the parent process, or 0 if the process does not have a parent.
.It Vt pid_t pr_pgid
Process ID of the process group leader.
.It Vt pid_t pr_sid
Session ID, or 0 if the process does not belong to a session.
.It Vt pid_t pr_uid
Real user ID.
.It Vt pid_t pr_euid
Effective user ID.
.It Vt pid_t pr_gid
Real group ID.
.It Vt pid_t pr_egid
Effective group ID.
.It Vt uintptr_t pr_addr
Pointer to the
.Vt struct proc
for the process.
.It Vt string pr_psargs
Process arguments.
.It Vt u_int pr_arglen
Length of the process argument string.
.It Vt u_int pr_jailid
Jail ID of the process.
.El
.Pp
The fields of
.Vt lwpsinfo_t
are:
.Bl -tag -width "uintptr_t pr_wchar" -offset indent
.It Vt id_t pr_lwpid
Thread ID.
.It Vt int pr_flag
Thread flags.
.It Vt int pr_pri
Real scheduling priority of the thread.
.It Vt char pr_state
Currently always 0.
.It Vt char pr_sname
Currently always
.Ql ? .
.It Vt short pr_syscall
Currently always 0.
.It Vt uintptr_t pr_addr
Pointer to the
.Vt struct thread
for the thread.
.It Vt uintptr_t pr_wchan
Current wait address on which the thread is sleeping.
.El
.Sh FILES
.Bl -tag -width "/usr/lib/dtrace/psinfo.d" -compact
.It Pa /usr/lib/dtrace/psinfo.d
DTrace type and translator definitions for the
.Nm proc
provider.
.El
.Sh EXAMPLES
The following script logs process execution events as they occur:
.Bd -literal -offset indent
#pragma D option quiet
proc:::exec-success
{
printf("%s", curpsinfo->pr_psargs);
}
.Ed
.Pp
Note that the
.Dv pr_psargs
field is subject to the limit defined by the
.Va kern.ps_arg_cache_limit
sysctl.
In particular, processes with an argument list longer than the value defined by
this sysctl cannot be logged in this way.
.Sh COMPATIBILITY
The
.Nm proc
provider in
.Fx
is not compatible with the
.Nm proc
provider in Solaris.
In particular,
.Fx
uses the native
.Vt "struct proc"
and
.Vt "struct thread"
types for probe arguments rather than translated types.
Additionally, a number of
.Nm proc
provider probes found in Solaris are not currently available on
.Fx .
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr errno 2 ,
.Xr fork 2 ,
.Xr pdfork 2 ,
.Xr rfork 2 ,
.Xr vfork 2 ,
.Xr siginfo 3 ,
.Xr signal 3 ,
.Xr dtrace-sched 4 ,
.Xr kproc 9
.Sh HISTORY
The
.Nm proc
provider first appeared in
.Fx
7.1.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .

227
share/man/man4/dtrace-sched.4 Normal file
View File

@ -0,0 +1,227 @@
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 18, 2015
.Dt DTRACE-SCHED 4
.Os
.Sh NAME
.Nm dtrace-sched
.Nd a DTrace provider for tracing CPU scheduling events
.Sh SYNOPSIS
.Fn sched:::change-pri "struct thread *" "struct proc *" "uint8_t"
.Fn sched:::dequeue "struct thread *" "struct proc *" "void *"
.Fn sched:::enqueue "struct thread *" "struct proc *" "void *" "int"
.Fn sched:::lend-pri "struct thread *" "struct proc *" "uint8_t" "struct thread *"
.Fn sched:::load-change "int" "int"
.Fn sched:::off-cpu "struct thread *" "struct proc *"
.Fn sched:::on-cpu
.Fn sched:::preempt
.Fn sched:::remain-cpu
.Fn sched:::surrender "struct thread *" "struct proc *"
.Fn sched:::sleep
.Fn sched:::tick "struct thread *" "struct proc *"
.Fn sched:::wakeup "struct thread *" "struct proc *"
.Sh DESCRIPTION
The DTrace
.Nm sched
provider allows the tracing of events related to CPU scheduling in the 4BSD and
ULE schedulers.
.Pp
The
.Fn sched:::change-pri
probe fires when a thread's active scheduling priority is about to be updated.
The first two arguments are the thread whose priority is about to be changed,
and the corresponding process.
The third argument is the new absolute priority for the thread, while the
current value is given by
.Dv args[0]->td_priority .
The
.Fn sched:::lend-pri
probe fires when the currently-running thread elevates the priority of another
thread via priority lending.
The first two arguments are the thread whose priority is about to be changed,
and the corresponding process.
The third argument is the new absolute priority for the thread.
The fourth argument is the currently-running thread.
.Pp
The
.Fn sched:::dequeue
probe fires immediately before a runnable thread is removed from a scheduler
run queue.
This may occur when the thread is about to begin execution on a CPU, or because
the thread is being migrated to a different run queue.
The latter event may occur in several circumstances: the scheduler may be
attempting to rebalance load between multiple CPUs, the thread's scheduling
priority may have changed, or the thread's CPU affinity settings may have
changed.
The first two arguments to
.Fn sched:::dequeue
are the thread and corresponding process.
The third argument is currently always
.Dv NULL .
The
.Fn sched:::enqueue
probe fires when a runnable thread is about to be added to a scheduler run
queue.
Its first two arguments are the thread and corresponding process.
The third argument is currently always
.Dv NULL .
The fourth argument is a boolean value that is non-zero if the thread is
enqueued at the beginning of its run queue slot, and zero if the thread is
instead enqueued at the end.
.Pp
The
.Fn sched:::load-change
probe fires after the load of a thread queue is adjusted.
The first argument is the cpuid for the CPU associated with the thread queue,
and the second argument is the adjusted load of the thread queue, i.e., the
number of elements in the queue.
.Pp
The
.Fn sched:::off-cpu
probe is triggered by the scheduler suspending execution of the
currently-running thread, and the
.Fn sched:::on-cpu
probe fires when the current thread has been selected to run on a CPU and is
about to begin or resume execution.
The arguments to
.Fn sched:::off-cpu
are the thread and corresponding process selected to run following the
currently-running thread.
If these two threads are the same, the
.Fn sched:::remain-cpu
probe will fire instead.
.Pp
The
.Fn sched:::surrender
probe fires when the scheduler is called upon to make a scheduling decision by
a thread running on a different CPU, via an interprocessor interrupt.
The arguments to this probe are the interrupted thread and its corresponding
process.
This probe currently always fires in the context of the interrupted thread.
.Pp
The
.Fn sched:::preempt
probe will fire immediately before the currently-running thread is preempted.
When this occurs, the scheduler will select a new thread to run, and one of the
.Fn sched:::off-cpu
or
.Fn sched:::remain-cpu
probes will subsequently fire, depending on whether or not the scheduler selects
the preempted thread.
.Pp
The
.Fn sched:::sleep
probe fires immediately before the currently-running thread is about to suspend
execution and begin waiting for a condition to be met.
The
.Fn sched:::wakeup
probe fires when a thread is set up to resume execution after having gone to
sleep.
Its arguments are the thread being awoken, and the corresponding process.
.Pp
The
.Fn sched:::tick
fires before each scheduler clock tick.
Its arguments are the currently-running thread and its corresponding process.
.Sh ARGUMENTS
The
.Nm sched
provider probes use the kernel types
.Vt "struct proc"
and
.Vt "struct thread"
to represent processes and threads, respectively.
These structures have many fields and are defined in
.Pa sys/proc.h .
In a probe body, the currently-running thread can always be obtained with the
.Va curthread
global variable, which has type
.Vt "struct thread *" .
For example, when a running thread is about to sleep, the
.Fn sched:::sleep
probe fires in the context of that thread, which can be accessed using
.Va curthread .
The
.Va curcpu
global variable contains the cpuid of the CPU on which the currently-running
thread is executing.
.Sh EXAMPLES
The following script gives a breakdown of CPU utilization by process name:
.Bd -literal -offset indent
sched:::on-cpu
{
self->ts = timestamp;
}
sched:::off-cpu
/self->ts != 0/
{
@[execname] = sum((timestamp - self->ts) / 1000);
self->ts = 0;
}
.Ed
.Pp
Here, DTrace stores a timestamp each time a thread is scheduled to run, and
computes the time elapsed in microseconds when it is descheduled.
The results are summed by process name.
.Sh COMPATIBILITY
This provider is not compatible with the
.Nm sched
provider found in Solaris.
In particular, the probe argument types are native
.Fx
types, and the
.Fn sched:::cpucaps-sleep ,
.Fn sched:::cpucaps-wakeup ,
.Fn sched:::schedctl-nopreempt ,
.Fn sched:::schedctl-preempt ,
and
.Fn sched:::schedctl-yield
probes are not available in
.Fx .
.Pp
The
.Fn sched:::lend-pri
and
.Fn sched:::load-change
probes are specific to
.Fx .
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr sched_4bsd 4 ,
.Xr sched_ule 4 ,
.Xr SDT 9 ,
.Xr sleepqueue 9
.Sh HISTORY
The
.Nm sched
provider first appeared in
.Fx
8.4 and 9.1.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .

400
share/man/man4/dtrace-tcp.4 Normal file
View File

@ -0,0 +1,400 @@
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 18, 2015
.Dt DTRACE-TCP 4
.Os
.Sh NAME
.Nm dtrace-tcp
.Nd a DTrace provider for tracing events related to the
.Xr tcp 4
protocol
.Sh SYNOPSIS
.Fn tcp:::accept-established "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
"tcpsinfo_t *" "tcpinfo_t *"
.Fn tcp:::accept-refused "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
"tcpsinfo_t *" "tcpinfo_t *"
.Fn tcp:::connect-established "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
"tcpsinfo_t *" "tcpinfo_t *"
.Fn tcp:::connect-refused "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
"tcpsinfo_t *" "tcpinfo_t *"
.Fn tcp:::connect-request "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
"tcpsinfo_t *" "tcpinfo_t *"
.Fn tcp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \
"tcpinfo_t *"
.Fn tcp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \
"tcpinfo_t *"
.Fn tcp:::state-change "void *" "csinfo_t *" "void *" "tcpsinfo_t *" "void *" \
"tcplsinfo_t *"
.Sh DESCRIPTION
The DTrace
.Nm tcp
provider allows users to trace events in the
.Xr tcp 4
protocol implementation.
This provider is similar to the
.Xr dtrace-ip 4
and
.Xr dtrace-udp 4
providers, but additionally contains probes corresponding to protocol events at
a level higher than packet reception and transmission.
All
.Nm tcp
probes except for
.Fn tcp:::state-change
have the same number and type of arguments.
The last three arguments are used to describe a TCP segment: the
.Vt ipinfo_t
argument exposes the version-agnostic fields of the IP header, while the
.Vt tcpinfo_t
argument exposes the TCP header, and the
.Vt tcpsinfo_t
argument describes details of the corresponding TCP connection state, if any.
Their fields are described in the ARGUMENTS section.
.Pp
The
.Fn 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
.Fn 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.
.Pp
The
.Fn tcp:::connect-established ,
.Fn tcp:::connect-refused ,
and
.Fn tcp:::connect-request
probes are similar to the
.Ql accept
probes, except that they correspond to locally-initiated TCP connections.
The
.Fn 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
.Fn 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
.Fn tcp:::connect-request
probe fires as the kernel prepares to transmit the initial SYN segment of a
three-way handshake.
.Pp
The
.Fn tcp:::send
and
.Fn tcp:::receive
probes fire when the host sends or receives a TCP packet, respectively.
As with the
.Xr dtrace-udp 4
provider,
.Nm 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
.Xr dtrace-ip 4
provider.
.Pp
The
.Fn tcp:::state-change
probe fires upon local TCP connection state transitions.
Its first, third and fifth arguments are currently always
.Dv NULL .
Its last argument describes the from-state in the transition, and the to-state
can be obtained from
.Dv args[2]->tcps_state .
.Sh ARGUMENTS
The
.Vt pktinfo_t
argument is currently unimplemented and is included for compatibility with other
implementations of this provider.
Its fields are:
.Bl -tag -width "uinptr_t pkt_addr" -offset indent
.It Vt uinptr_t pkt_addr
Always set to 0.
.El
.Pp
The
.Vt csinfo_t
argument is currently unimplemented and is included for compatibility with other
implementations of this provider.
Its fields are:
.Bl -tag -width "uintptr_t cs_addr" -offset indent
.It Vt uintptr_t cs_addr
Always set to 0.
.It Vt uint64_t cs_cid
A pointer to the
.Vt struct inpcb
for this packet, or
.Dv NULL .
.It Vt pid_t cs_pid
Always set to 0.
.El
.Pp
The
.Vt ipinfo_t
type is a version-agnostic representation of fields from an IP header.
Its fields are described in the
.Xr dtrace-ip 4
manual page.
.Pp
The
.Vt tcpsinfo_t
type is used to provide a stable representation of TCP connection state.
Some
.Nm tcp
probes, such as
.Fn tcp:::accept-refused ,
fire in a context where there is no TCP connection; this argument is
.Dv NULL
in that case.
Its fields are:
.Bl -tag -width "uint16_t tcps_lport" -offset indent
.It Vt uintptr_t tcps_addr
The address of the corresponding TCP control block.
This is currently a pointer to a
.Vt struct tcpcb .
.It Vt int tcps_local
A boolean indicating whether the connection is local to the host.
Currently unimplemented and always set to -1.
.It Vt int tcps_active
A boolean indicating whether the connection was initiated by the local host.
Currently unimplemented and always set to -1.
.It Vt uint16_t tcps_lport
Local TCP port.
.It Vt uint16_t tcps_rport
Remote TCP port.
.It Vt string tcps_laddr
Local address.
.It Vt string tcps_raddr
Remote address.
.It Vt int32_t tcps_state
Current 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 uint32_t tcps_iss
Initial send sequence number.
.It Vt uint32_t tcps_suna
Initial sequence number of sent but unacknowledged data.
.It Vt uint32_t tcps_snxt
Next sequence number for send.
.It Vt uint32_t tcps_rack
Sequence number of received and acknowledged data.
.It Vt uint32_t tcps_rnxt
Next expected sequence number for receive.
.It Vt uint32_t tcps_swnd
TCP send window size.
.It Vt int32_t tcps_snd_ws
Window scaling factor for the TCP send window.
.It Vt uint32_t tcps_rwnd
TCP receive window size.
.It Vt int32_t tcps_rcv_ws
Window scaling factor for the TCP receive window.
.It Vt uint32_t tcps_cwnd
TCP congestion window size.
.It Vt uint32_t tcps_cwnd_ssthresh
Congestion window threshold at which slow start ends and congestion avoidance
begins.
.It Vt uint32_t tcps_sack_fack
Last sequence number selectively acknowledged by the receiver.
.It Vt uint32_t tcps_sack_snxt
Next selectively acknowledge sequence number at which to begin retransmitting.
.It Vt uint32_t tcps_rto
Round-trip timeout, in milliseconds.
.It Vt uint32_t tcps_mss
Maximum segment size.
.It Vt int tcps_retransmit
A boolean indicating that the local sender is retransmitting data.
.It Vt int tcps_srtt
Smoothed round-trip time.
.El
.Pp
The
.Vt tcpinfo_t
type exposes the fields in a TCP segment header in host order.
Its fields are:
.Bl -tag -width "struct tcphdr *tcp_hdr" -offset indent
.It Vt uint16_t tcp_sport
Source TCP port.
.It Vt uint16_t tcp_dport
Destination TCP port.
.It Vt uint32_t tcp_seq
Sequence number.
.It Vt uint32_t tcp_ack
Acknowledgement number.
.It Vt uint8_t tcp_offset
Data offset, in bytes.
.It Vt uint8_t tcp_flags
TCP flags.
.It Vt uint16_t tcp_window
TCP window size.
.It Vt uint16_t tcp_checksum
Checksum.
.It Vt uint16_t tcp_urgent
Urgent data pointer.
.It Vt struct tcphdr *tcp_hdr
A pointer to the raw TCP header.
.El
.Pp
The
.Vt tcplsinfo_t
type is used by the
.Fn tcp:::state-change
probe to provide the from-state of a transition.
Its fields are:
.Bl -tag -width "int32_t tcps_state" -offset indent
.It Vt int32_t tcps_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 .
.El
.Sh FILES
.Bl -tag -width "/usr/lib/dtrace/tcp.d" -compact
.It Pa /usr/lib/dtrace/tcp.d
DTrace type and translator definitions for the
.Nm tcp
provider.
.El
.Sh EXAMPLES
The following script logs TCP segments in real time:
.Bd -literal -offset indent
#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("\b)\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("\b)\n");
}
.Ed
The following script logs TCP connection state changes as they occur:
.Bd -literal -offset indent
#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;
}
.Ed
.Sh COMPATIBILITY
This provider is compatible with the
.Nm tcp
provider in Solaris.
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr dtrace-ip 4 ,
.Xr dtrace-udp 4 ,
.Xr tcp 4 ,
.Xr SDT 9
.Sh HISTORY
The
.Nm tcp
provider first appeared in
.Fx
10.0.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .
.Sh BUGS
The
.Fn tcp:::state-change
probe does not fire upon transitions to the TIME-WAIT state.
.Pp
The
.Vt tcps_local
and
.Vt tcps_active
fields of
.Vt tcpsinfo_t
are not filled in by the translator.

199
share/man/man4/dtrace-udp.4 Normal file
View File

@ -0,0 +1,199 @@
.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 18, 2015
.Dt DTRACE-UDP 4
.Os
.Sh NAME
.Nm dtrace-udp
.Nd a DTrace provider for tracing events related to the UDP protocol
.Sh SYNOPSIS
.Fn udp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udpsinfo_t *" \
"udpinfo_t *"
.Fn udp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udpsinfo_t *" \
"udpinfo_t *"
.Sh DESCRIPTION
The DTrace
.Nm udp
provider allows users to trace events in the
.Xr udp 4
protocol implementation.
The
.Fn udp:::send
probe fires whenever the kernel prepares to transmit a UDP packet, and the
.Fn udp:::receive
probe fires whenever the kernel receives a UDP packet.
The arguments to these probes can be used to obtain detailed information about
the IP and UDP headers of the corresponding packet.
.Sh ARGUMENTS
The
.Vt pktinfo_t
argument is currently unimplemented and is included for compatibility with other
implementations of this provider.
Its fields are:
.Bl -tag -width "uintptr_t pkt_addr" -offset indent
.It Vt uintptr_t pkt_addr
Always set to 0.
.El
.Pp
The
.Vt csinfo_t
argument is currently unimplemented and is included for compatibility with other
implementations of this provider.
Its fields are:
.Bl -tag -width "uintptr_t cs_addr" -offset indent
.It Vt uintptr_t cs_addr
Always set to 0.
.It Vt uint64_t cs_cid
A pointer to the
.Vt struct inpcb
for this packet, or
.Dv NULL .
.It Vt pid_t cs_pid
Always set to 0.
.El
.Pp
The
.Vt ipinfo_t
argument contains IP fields common to both IPv4 and IPv6 packets.
Its fields are:
.Bl -tag -width "uint32_t ip_plength" -offset indent
.It Vt uint8_t ip_ver
IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets.
.It Vt uint32_t ip_plength
IP payload size.
This does not include the size of the IP header or IPv6 option headers.
.It Vt string ip_saddr
IP source address.
.It Vt string ip_daddr
IP destination address.
.El
.Pp
The
.Vt udpsinfo_t
argument contains the state of the UDP connection associated with the packet.
Its fields are:
.Bl -tag -width "uintptr_t udps_addr" -offset indent
.It Vt uintptr_t udps_addr
Pointer to the
.Vt struct inpcb
containing the IP state for the associated socket.
.It Vt uint16_t udps_lport
Local UDP port.
.It Vt uint16_t udps_rport
Remote UDP port.
.It Vt string udps_laddr
Local IPv4 or IPv6 address.
.It Vt string udps_raddr
Remote IPv4 or IPv6 address.
.El
.Pp
The
.Vt udpinfo_t
argument is the raw UDP header of the packet, with all fields in host order.
Its fields are:
.Bl -tag -width "struct udphdr *udp_hdr" -offset indent
.It Vt uint16_t udp_sport
Source UDP port.
.It Vt uint16_t udp_dport
Destination UDP port.
.It Vt uint16_t udp_length
Length of the UDP header and payload, in bytes.
.It Vt uint16_t udp_checksum
A checksum of the UDP header and payload, or 0 if no checksum was calculated.
.It Vt struct udphdr *udp_hdr
A pointer to the raw UDP header.
.El
.Sh FILES
.Bl -tag -width "/usr/lib/dtrace/udp.d" -compact
.It Pa /usr/lib/dtrace/udp.d
DTrace type and translator definitions for the
.Nm udp
provider.
.El
.Sh EXAMPLES
The following script counts transmitted packets by destination port.
.Bd -literal -offset indent
udp:::send
{
@num[args[4]->udp_dport] = count();
}
.Ed
.Pp
This script will print some details of each UDP packet as it is sent or received
by the kernel:
.Bd -literal -offset indent
#pragma D option quiet
#pragma D option switchrate=10Hz
dtrace:::BEGIN
{
printf(" %10s %36s %-36s %6s\n", "DELTA(us)", "SOURCE",
"DEST", "BYTES");
last = timestamp;
}
udp:::send
{
this->elapsed = (timestamp - last) / 1000;
self->dest = strjoin(strjoin(args[2]->ip_daddr, ":"),
lltostr(args[4]->udp_dport));
printf(" %10d %30s:%-5d -> %-36s %6d\n", this->elapsed,
args[2]->ip_saddr, args[4]->udp_sport,
self->dest, args[4]->udp_length);
last = timestamp;
}
udp:::receive
{
this->elapsed = (timestamp - last) / 1000;
self->dest = strjoin(strjoin(args[2]->ip_saddr, ":"),
lltostr(args[4]->udp_sport));
printf(" %10d %30s:%-5d <- %-36s %6d\n", this->elapsed,
args[2]->ip_daddr, args[4]->udp_dport,
self->dest, args[4]->udp_length);
last = timestamp;
}
.Ed
.Sh COMPATIBILITY
This provider is compatible with the
.Nm udp
provider in Solaris.
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr dtrace-ip 4 ,
.Xr dtrace-tcp 4 ,
.Xr udp 4 ,
.Xr SDT 9
.Sh HISTORY
The
.Nm udp
provider first appeared in
.Fx
10.0.
.Sh AUTHORS
This manual page was written by
.An Mark Johnston Aq Mt markj@FreeBSD.org .

10
share/man/man9/SDT.9
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2013 Mark Johnston <markj@freebsd.org>
.\" Copyright (c) 2013-2015 Mark Johnston <markj@freebsd.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -304,7 +304,13 @@ SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *",
"struct icmp_hdr_dt *");
.Ed
.Sh SEE ALSO
.Xr dtrace 1
.Xr dtrace 1 ,
.Xr dtrace-io 4 ,
.Xr dtrace-ip 4 ,
.Xr dtrace-proc 4 ,
.Xr dtrace-sched 4 ,
.Xr dtrace-tcp 4 ,
.Xr dtrace-udp 4
.Sh AUTHORS
.An -nosplit
DTrace and the