Changeset View
Changeset View
Standalone View
Standalone View
cddl/usr.sbin/dwatch/dwatch.8
- This file was added.
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" Copyright (c) 2014-2017 Devin Teske | |||||
.\" 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 ``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 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 Mar 22, 2017 | |||||
.Dt DWATCH 8 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm dwatch | |||||
.Nd Watch processes as they enter a particular DTrace probe | |||||
.Sh SYNOPSIS | |||||
.Nm | |||||
.Op OPTIONS | |||||
[provider:[module:]]function | profile | |||||
.Nm | |||||
.Fl l | |||||
.Op Fl e Ar name | |||||
.Op pattern | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm | |||||
utility uses | |||||
.Xr dtrace 1 | |||||
to display information when DTrace hits a given probe event name. | |||||
The following options are available: | |||||
.Bl -tag -width "-c count" | |||||
.It Fl c Ar count | |||||
Exit after | |||||
.Ar count | |||||
matching entries | |||||
.Pq Default 0 for disabled . | |||||
.It Fl D Ar code | |||||
DTrace code for event details. | |||||
If `-', read from stdin. | |||||
This allows you to customize what is printed after the date/time and user info. | |||||
By default, | |||||
the name and arguments of the program entering the probe are shown. | |||||
.It Fl d | |||||
Debug. | |||||
Send | |||||
.Xr dtrace 1 | |||||
script to stdout instead of executing. | |||||
.It Fl e Ar name | |||||
Event name for given probe function | |||||
.Pq Default Ql Li entry . | |||||
.It Fl f Ar regex | |||||
Filter. | |||||
Only show blocks matching | |||||
.Xr awk 1 | |||||
regular expression. | |||||
.It Fl g Ar group | |||||
Group filter. | |||||
Only show processes matching | |||||
.Ar group | |||||
name/gid. | |||||
.It Fl h | |||||
Help. | |||||
Display syntax and available profiles then exit. | |||||
.It Fl l | |||||
List available probe points on standard output and exit. | |||||
.It Fl m Ar num | |||||
Maximum number of arguments to display | |||||
.Pq Default 64 . | |||||
.It Fl n Ar num | |||||
Maximum directory depth to display | |||||
.Pq Default 64 . | |||||
.It Fl p | |||||
Disable loading of profiles from DWATCH_PROFILES_PATH. | |||||
Same as setting DWATCH_PROFILES_PATH to NULL. | |||||
.It Fl q | |||||
Quiet. | |||||
Disable informational messages displayed on stderr. | |||||
.It Fl u Ar user | |||||
User filter. | |||||
Only show processes matching | |||||
.Ar user | |||||
name/uid. | |||||
.It Fl v | |||||
Verbose. | |||||
Show parent, | |||||
grandparent, | |||||
and ancestor of process. | |||||
.El | |||||
.Pp | |||||
Either the name of a | |||||
.Xr dwatch 8 | |||||
profile | |||||
.Pq available with Ql Nm Fl h | |||||
or | |||||
.Xr dtrace 1 | |||||
probe | |||||
.Po | |||||
available with | |||||
.Ql Nm Fl l | |||||
or in the format of | |||||
.Ql Li "[provider:[module:]]function" | |||||
.Pc | |||||
must be given as the first/only non-option argument. | |||||
.Pp | |||||
If given an argument consisting of only alpha-numeric, | |||||
underscore, | |||||
and/or hyphen characters, | |||||
.Xr dwatch 8 | |||||
checks for a profile by that name in the colon-separated list of directories in | |||||
.Ev DWATCH_PROFILES_PATH | |||||
.Pq unless given Ql Fl p . | |||||
If no profile is found, | |||||
.Xr dwatch 8 | |||||
tries to expand the probe name using the following | |||||
.Xr dtrace 1 | |||||
command: | |||||
.Pp | |||||
.Bl -tag -width indent+ | |||||
.It "" | |||||
dtrace -ln <probe>:entry | |||||
.El | |||||
.Pp | |||||
For example, if given a probe of | |||||
.Dq Li foo , | |||||
.Xr dwatch 8 | |||||
will execute | |||||
.Ql Li dtrace -ln foo:entry | |||||
and take the first probe available. | |||||
.Pp | |||||
The default event name of | |||||
.Ql Li entry | |||||
can be changed using | |||||
.Ql Fl e Ar name . | |||||
.Pp | |||||
Each time a process enters the given probe, | |||||
the date/time of entry, | |||||
name/id of process, | |||||
and | |||||
.Pq if no profile and not given Ql Fl D Ar code | |||||
the process name and arguments are printed. | |||||
.Pp | |||||
If the probe is | |||||
.Ql Li execve | |||||
the full name and arguments of the forked child process are instead shown. | |||||
.Sh PROFILES | |||||
Profiles customize the data printed during events. | |||||
Profiles are loaded from a colon-separated list of directories in | |||||
.Ev DWATCH_PROFILES_PATH . | |||||
Below is an incomplete list of profiles with basic descriptions: | |||||
.Pp | |||||
.Bl -tag -width "vop_readdir" | |||||
.It chmod | |||||
Print arguments being passed to chmod(2) | |||||
.It fchmod | |||||
Print arguments being passed to fchmod(2) | |||||
.It fchmodat | |||||
Print arguments being passed to fchmodat(2) | |||||
.It kill | |||||
Print arguments being passed to kill(2) | |||||
.It lchmod | |||||
Print arguments being passed to lchmod(2) | |||||
.It nanosleep | |||||
Print arguments being passed to lchmod(2) | |||||
.It vop_create | |||||
Print filesystem paths being created by VOP_CREATE(9) | |||||
.It vop_lookup | |||||
Print filesystem paths being looked-up by VOP_LOOKUP(9) | |||||
.It vop_mkdir | |||||
Print directory paths being created by VOP_MKDIR(9) | |||||
.It vop_mknod | |||||
Print device node paths being created by VOP_MKNOD(9) | |||||
.It vop_readdir | |||||
Print directory paths being read by VOP_READDIR(9) | |||||
.It vop_remove | |||||
Print filesystem paths being removed by VOP_REMOVE(9) | |||||
.It vop_rename | |||||
Print filesystem paths being renamed by VOP_RENAME(9) | |||||
.It vop_rmdir | |||||
Print directory paths being removed by VOP_RMDIR(9) | |||||
.It vop_symlink | |||||
Print symlink paths being created by VOP_SYMLINK(9) | |||||
.El | |||||
.Sh EXAMPLES | |||||
Below are some simple examples of how to use | |||||
.Nm | |||||
to watch system activity: | |||||
.Pp | |||||
.Nm | |||||
.Fl v | |||||
execve | |||||
.Dl Show process tree for each command as it is executed. | |||||
.Pp | |||||
.Nm | |||||
.Fl e Ar on-cpu | |||||
sched:: | |||||
.Dl Watch processes entering system CPU scheduler. | |||||
.Pp | |||||
.Nm | |||||
.Fl D Ar 'printf("%i", arg1)' | |||||
zfs_sync | |||||
.Dl Print argument one being passed to each call to zfs_sync(). | |||||
.Pp | |||||
.Nm | |||||
.Fl p | |||||
vop_create | |||||
.Dl Disable profile causing default information to be displayed. | |||||
.Pp | |||||
.Nm | |||||
.Fl c Ar 1 | |||||
kill | |||||
.Dl Display the first call to Xr kill 2 and exit. | |||||
.Pp | |||||
.Nm | |||||
.Fl d | |||||
fsync | |||||
.Dl "Do not" execute Xr dtrace 1 but display script on stdout and exit. | |||||
.Pp | |||||
.Nm | |||||
.Fl u Ar root | |||||
execve | |||||
.Dl Display only processes belonging to the root super-user. | |||||
.Sh ENVIRONMENT VARIABLES | |||||
The following environment variables affect the execution of | |||||
.Nm : | |||||
.Bl -tag -width "DWATCH_PROFILES_PATH" | |||||
.It Ev DWATCH_PROFILES_PATH | |||||
If DWATCH_PROFILES_PATH is set, | |||||
.Nm | |||||
will search for profiles in the colon-separated list of directories | |||||
instead of the default | |||||
.Ql Li /usr/libexec/dwatch:/usr/local/libexec/dwatch . | |||||
If set to NULL, no profiles will be loaded. | |||||
.El | |||||
.Sh EXIT STATUS | |||||
.Ex -std | |||||
.Sh SEE ALSO | |||||
.Xr dtrace 1 | |||||
.Sh HISTORY | |||||
.Nm | |||||
first appeared in | |||||
.Fx 12.0-CURRENT . | |||||
.Sh AUTHORS | |||||
.An Devin Teske Aq Mt dteske@FreeBSD.org |