Index: cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 =================================================================== --- cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 +++ cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 @@ -670,6 +670,7 @@ .Sh SEE ALSO .Xr cpp 1 , .Xr dtruss 1 , +.Xr dtrace-ip 4 , .Xr elf 5 .Rs .%T Solaris Dynamic Tracing Guide Index: share/man/man4/Makefile =================================================================== --- share/man/man4/Makefile +++ share/man/man4/Makefile @@ -121,6 +121,12 @@ 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 @@ _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 Index: share/man/man4/dtrace-io.4 =================================================================== --- /dev/null +++ share/man/man4/dtrace-io.4 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 March 22, 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 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 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 io provider found in Solaris, as its +probes use native FreeBSD argument types. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr devstat 9 , +.Xr SDT 9 +.Sh HISTORY +The io provider first appeared in FreeBSD 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 FreeBSD. Index: share/man/man4/dtrace-ip.4 =================================================================== --- /dev/null +++ share/man/man4/dtrace-ip.4 @@ -0,0 +1,270 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 March 22, 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 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 tcp and udp providers, 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 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 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 ip provider first appeared in FreeBSD 10.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . Index: share/man/man4/dtrace-proc.4 =================================================================== --- /dev/null +++ share/man/man4/dtrace-proc.4 @@ -0,0 +1,244 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 March 22, 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 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 proc provider probes use native FreeBSD 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 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 proc provider in FreeBSD is not compatible with the proc provider in +Solaris. +In particular, FreeBSD uses the native +.Vt "struct proc" +and +.Vt "struct thread" +types for probe arguments rather than translated types. +Additionally, a number of proc provider probes found in Solaris are not +currently available on FreeBSD. +.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 proc provider first appeared in FreeBSD 7.1. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . Index: share/man/man4/dtrace-sched.4 =================================================================== --- /dev/null +++ share/man/man4/dtrace-sched.4 @@ -0,0 +1,213 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 March 22, 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 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 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 sched provider found in Solaris. +In particular, the probe argument types are native FreeBSD 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 FreeBSD. +.Pp +The +.Fn sched:::lend-pri +and +.Fn sched:::load-change +probes are specific to FreeBSD. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr sched_4bsd 4 , +.Xr sched_ule 4 , +.Xr SDT 9 , +.Xr sleepqueue 9 +.Sh HISTORY +The sched provider first appeared in FreeBSD 8.4 and 9.1. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . Index: share/man/man4/dtrace-tcp.4 =================================================================== --- /dev/null +++ share/man/man4/dtrace-tcp.4 @@ -0,0 +1,378 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 March 22, 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 tcp provider allows users to trace events in the +.Xr tcp 4 +protocol implementation. +This provider is similar to the ip and udp providers, but additionally contains +probes corresponding to protocol events at a level higher than packet reception +and transmission. +All 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 exposts 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 udp 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 ip 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 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 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 tcp providers found in Solaris and Darwin. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace-ip 4 , +.Xr dtrace-udp 4 , +.Xr tcp 4 , +.Xr SDT 9 +.Sh HISTORY +The tcp provider first appeared in FreeBSD 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. Index: share/man/man4/dtrace-udp.4 =================================================================== --- /dev/null +++ share/man/man4/dtrace-udp.4 @@ -0,0 +1,189 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 February 27, 2014 +.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 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 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 udp providers found in Solaris and Darwin. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace-ip 4 , +.Xr dtrace-tcp 4 , +.Xr udp 4 , +.Xr SDT 9 +.Sh HISTORY +The udp provider first appeared in FreeBSD 10.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . Index: share/man/man9/SDT.9 =================================================================== --- share/man/man9/SDT.9 +++ share/man/man9/SDT.9 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2013 Mark Johnston +.\" Copyright (c) 2013-2015 Mark Johnston .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -274,7 +274,13 @@ "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