Date: Sat, 18 Apr 2015 22:19:03 +0100 From: Steven Hartland <steven@multiplay.co.uk> To: Mark Johnston <markj@FreeBSD.org>, src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r281705 - in head: cddl/contrib/opensolaris/cmd/dtrace share/man/man4 share/man/man9 Message-ID: <5532CA47.2030600@freebsd.org> In-Reply-To: <201504182100.t3IL0aPM062013@svn.freebsd.org> References: <201504182100.t3IL0aPM062013@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Thank you for doing this! On 18/04/2015 22:00, Mark Johnston wrote: > Author: markj > Date: Sat Apr 18 21:00:36 2015 > New Revision: 281705 > URL: https://svnweb.freebsd.org/changeset/base/281705 > > Log: > Add manual pages for the io, ip, proc, sched, tcp and udp DTrace providers. > 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 > > Added: > head/share/man/man4/dtrace-io.4 (contents, props changed) > head/share/man/man4/dtrace-ip.4 (contents, props changed) > head/share/man/man4/dtrace-proc.4 (contents, props changed) > head/share/man/man4/dtrace-sched.4 (contents, props changed) > head/share/man/man4/dtrace-tcp.4 (contents, props changed) > head/share/man/man4/dtrace-udp.4 (contents, props changed) > Modified: > head/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 > head/share/man/man4/Makefile > head/share/man/man9/SDT.9 > > Modified: head/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 > ============================================================================== > --- head/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 Sat Apr 18 20:55:55 2015 (r281704) > +++ head/cddl/contrib/opensolaris/cmd/dtrace/dtrace.1 Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 argument > .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 > > Modified: head/share/man/man4/Makefile > ============================================================================== > --- head/share/man/man4/Makefile Sat Apr 18 20:55:55 2015 (r281704) > +++ head/share/man/man4/Makefile Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 > > Added: head/share/man/man4/dtrace-io.4 > ============================================================================== > --- /dev/null 00:00:00 1970 (empty, because file is newly added) > +++ head/share/man/man4/dtrace-io.4 Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 . > > Added: head/share/man/man4/dtrace-ip.4 > ============================================================================== > --- /dev/null 00:00:00 1970 (empty, because file is newly added) > +++ head/share/man/man4/dtrace-ip.4 Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 . > > Added: head/share/man/man4/dtrace-proc.4 > ============================================================================== > --- /dev/null 00:00:00 1970 (empty, because file is newly added) > +++ head/share/man/man4/dtrace-proc.4 Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 . > > Added: head/share/man/man4/dtrace-sched.4 > ============================================================================== > --- /dev/null 00:00:00 1970 (empty, because file is newly added) > +++ head/share/man/man4/dtrace-sched.4 Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 . > > Added: head/share/man/man4/dtrace-tcp.4 > ============================================================================== > --- /dev/null 00:00:00 1970 (empty, because file is newly added) > +++ head/share/man/man4/dtrace-tcp.4 Sat Apr 18 21:00:36 2015 (r281705) > @@ -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 > > *** DIFF OUTPUT TRUNCATED AT 1000 LINES *** >
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5532CA47.2030600>