Page MenuHomeFreeBSD
Differential D10006 Diff 29314 cddl/usr.sbin/dwatch/dwatch.1

Changeset View

Standalone View

View Options

cddl/usr.sbin/dwatch/dwatch.1

  • This file was added.
PropertyOld ValueNew Value
svn:eol-stylenullnative
\ No newline at end of property
svn:keywordsnullFreeBSD=%H
\ No newline at end of property
svn:mime-typenulltext/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 June 2, 2017
.Dt DWATCH 1
.Os
.Sh NAME
.Nm dwatch
.Nd watch processes as they trigger a particular DTrace probe
.Sh SYNOPSIS
.Nm
.Op Fl 1defFmnPqRvVwxy
.Op Fl B Ar num
.Op Fl E Ar code
.Op Fl g Ar group
.Op Fl j Ar jail
.Op Fl k Ar name
.Op Fl K Ar num
.Op Fl M Ar name
.Op Fl N Ar count
.Op Fl p Ar pid
.Op Fl r Ar regex
.Op Fl t Ar test
.Op Fl T Ar time
.Op Fl u Ar user
.Op Fl z Ar regex
probe ...
.Nm
.Fl l
.Op Fl fmnPqy
.Op Fl r Ar regex
.Op probe ...
.Nm
.Fl Q
.Op Fl 1qy
.Op Fl r Ar regex
.Sh DESCRIPTION
The
.Nm
utility uses
.Xr dtrace 1
to display process info when DTrace hits a given probe proint.
markjUnsubmitted
Done
Inline Actions

point*

markj: point*
wblockUnsubmitted
Done
Inline Actions

"hits" sounds a little imprecise, but I'm not sure of a good replacement. "executes" or "encounters", maybe.

wblock: "hits" sounds a little imprecise, but I'm not sure of a good replacement. "executes" or…
.Pp
.Nm
automates the process of generating DTrace scripts to coalesce trace output by
date/time,
process info,
and
.Op optionally
probe-specific data.
.Pp
Output format without options is:
.Pp
.Dl date/time uid.gid execname[pid]: psargs
.Pp
For example,
the command
.Ql dwatch BEGIN
produces the output:
.Pp
.Dl INFO Watching 'dtrace:::BEGIN' ...
.Dl 2017 May 29 08:23:20 0.0 dtrace[60671]: dtrace -s /dev/stdin
.Pp
The
.Fl F
option causes
.Nm
to instead coalesce trace output by date/time,
process info,
and function traversal.
.Pp
Output format with
wblockUnsubmitted
Done
Inline Actions

This could benefit with a "the":

Output format with the
wblock: This could benefit with a "the": ```Output format with the```
.Ql Fl F
option is:
.Pp
.Dl date/time uid.gid execname[pid]: [=> |<= ]prov:mod:func:name
.Pp
For example,
the command
.Ql dwatch -F BEGIN
produces the output:
.Pp
.Dl INFO Watching 'dtrace:::BEGIN' ...
.Dl 2017 May 29 21:34:41 0.0 dtrace[86593]: dtrace:::BEGIN
.Pp
The
.Fl R
option causes
.Nm
to display a process tree containing the parent,
grandparent,
and ancestor process info.
.Pp
Output format with
wblockUnsubmitted
Done
Inline Actions

"the", as above.

wblock: "the", as above.
.Ql Fl R
option is:
.Pp
.Dl date/time uid0.gid0 execname[pid0]: psargs0
.Dl " -+= pid3 uid3.gid3 psargs3"
.Dl " \\\-+= pid2 uid2.gid2 psargs2"
.Dl " \\\-+= pid1 uid1.gid1 psargs1"
.Dl " \\\-+= pid0 uid0.guid0 psargs0"
.Pp
For example,
the command
.Ql dwatch -R BEGIN
produces the output:
.Pp
.Dl INFO Watching 'dtrace:::BEGIN' ...
.Dl 2017 May 29 21:38:54 0.0 dtrace[86899]: dtrace -s /dev/stdin
.Dl " -+= 86855 604.604 -bash"
.Dl " \-+= 86857 604.604 /bin/sh /usr/sbin/dwatch -R BEGIN"
.Dl " \-+= 86897 0.0 sudo dtrace -s /dev/stdin"
.Dl " \-+= 86899 0.0 dtrace -s /dev/stdin"
.Pp
Of particular interest is the ability to filter using regular expressions.
The
.Ql Fl g Ar group ,
.Ql Fl p Ar pid ,
.Ql Fl r Ar regex ,
.Ql Fl u Ar user ,
and
.Ql Fl z Ar regex
options can be combined with
.Ql Fl R
to match on parent process criteria as well as current process info.
.Pp
In contrast,
the
.Ql Fl j Ar jail ,
and
.Ql Fl k Ar name
options apply only to the current process even if
.Ql Fl R
is given.
.Pp
The
.Ql Fl E Ar code
option gives the ability to customize probe-specific data.
For example,
the command:
.Pp
.Dl dwatch -E 'printf("%s", copyinstr(arg0))' chdir
.Pp
displays the path argument sent to
.Xr chdir 2
calls.
.Pp
Profiles can be written for more complex routines or convenience.
To list available profiles use the
.Ql Fl Q
option.
Use the
.Ql Fl M Ar name
option to use a particular profile.
.Pp
For example,
the command
.Ql dwatch -M kill
displays arguments sent to
.Xr kill 2 .
.Pp
Since this uses DTrace, only the root user or users with
.Xr sudo 8
access can run this command.
.Sh OPTIONS
If a
.Ar probe
argument does not contain colon
.Pq Ql Li ":"
and none of
.Ql Fl P ,
.Ql Fl m ,
.Ql Fl f ,
or
.Ql Fl n
are given,
the probe argument is intelligently mapped to its most-likely value.
Use
.Ql Nm Fl l Ar name
to see what probes will match a given name.
.Bl -tag -width "-c count"
.It Fl 1
Print one line per process/profile
.Pq Default; disables Ql Fl R .
.It Fl B Ar num
Maximum number of arguments to display
.Pq Default 64 .
.It Fl d
Debug.
Send
.Xr dtrace 1
script to stdout instead of executing.
.It Fl e
Exit after compiling request but prior to enabling probes.
.It Fl E Ar code
DTrace
.Ar code
for event details.
If `-',
read from stdin.
This allows the customization of what is printed after the date/time
and process info.
By default,
the name and arguments of the program triggering the probe are shown.
.It Fl f
Enable probe matching the specified function name.
.It Fl F
Coalesce trace output by function.
.It Fl g Ar group
Group filter.
Only show processes matching
.Ar group
name/gid.
This can be an
.Xr awk 1
regular expression to match a numerical gid.
.It Fl j Ar jail
Jail filter.
Only show processes matching
.Ar jail
name/jid.
.It Fl k Ar name
Only show processes matching
.Ar name .
Can also be of the format
.Ql Li name*
to indicate
.Dq Li begins with ,
.Ql Li *name
to indicate
.Dq Li ends with ,
or
.Ql Li *name*
to indicate
.Dq Li contains .
.It Fl K Ar num
Maximum directory depth to display
.Pq Default 64 .
.It Fl l
List available probes on standard output and exit.
.It Fl m
Enable probe matching the specified module name.
.It Fl M Ar name
Load profile name from DWATCH_PROFILES_PATH.
.It Fl n
Enable probe matching the specified probe name.
.It Fl N Ar count
Exit after
.Ar count
matching entries
.Pq Default 0 for disabled .
.It Fl p Ar pid
Process id filter.
Only show processes with matching
.Ar pid .
This can be an
.Xr awk 1
regular expression.
.It Fl P
Enable probe matching the specified provider name.
.It Fl q
Quiet.
Hide informational messages and all dtrace(1) errors.
.It Fl Q
List available profiles in DWATCH_PROFILES_PATH and exit.
.It Fl r Ar regex
Filter.
Only show blocks matching
.Xr awk 1
regular expression.
.It Fl R
Show parent,
grandparent,
and ancestor of process.
.It Fl t Ar test
Test clause
.Pq predicate
to limit events
.Pq Default none .
.It Fl T Ar time
Timeout.
Format is
wblockUnsubmitted
Done
Inline Actions
The format is
wblock: ```The format is```
.Ql Li #[smhd]
or just
.Ql Li #
for seconds.
.It Fl u Ar user
User filter.
Only show processes matching
.Ar user
name/uid.
This can be an
.Xr awk 1
regular expression to match a numerical uid.
wblockUnsubmitted
Done
Inline Actions

Not sure whether "uid" should be capitalized.

wblock: Not sure whether "uid" should be capitalized.
.It Fl v
Verbose.
Show all errors from
.Xr dtrace 1 .
.It Fl V
Report dwatch version on standard output and exit.
wblockUnsubmitted
Done
Inline Actions
Report
.Nm
version on standard output and exit.
wblock: ```Report .Nm version on standard output and exit.```
.It Fl w
Permit destructive actions
.Pq copyout*, stop, panic, etc. .
.It Fl x
Trace.
Print
.Ql Li <probe-id>
when a probe is triggered.
.It Fl y
Always treat stdout as console
.Pq enable colors/columns/etc. .
.It Fl z Ar regex
Only show processes matching
.Xr awk 1
regular expression.
.El
.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:
wblockUnsubmitted
Done
Inline Actions

I would suggest just "This" rather than below, because the list starts immediately after that sentence.

wblock: I would suggest just "This" rather than below, because the list starts immediately after that…
.Bl -tag -width "vop_readdir"
.It chmod
Print arguments being passed to chmod(2)
wblockUnsubmitted
Done
Inline Actions

Should this be an .Xr chmod 2 ?

Same question for the rest of these.

wblock: Should this be an `.Xr chmod 2` ? Same question for the rest of these.
.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 nanosleep(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 ENVIRONMENT
These environment variables affect the execution of
.Nm :
.Bl -tag -width "DWATCH_PROFILES_PATH"
.It Ev DWATCH_PROFILES_PATH
If DWATCH_PROFILES_PATH is set,
wblockUnsubmitted
Done
Inline Actions

Use

If
.Ev DWATCH_PROFILES_PATH
is set,
wblock: Use ```If .Ev DWATCH_PROFILES_PATH is set,```
.Nm
will search for profiles in the colon-separated list of directories
wblockUnsubmitted
Done
Inline Actions

s/will search/searches/

And it doesn't really say that the list of directories comes from that variable, so:

If
.Ev DWATCH_PROFILES_PATH
is set,
.Nm
searches for profiles in the colon-separated list of directories in that variable
wblock: s/will search/searches/ And it doesn't really say that the list of directories comes from that…
instead of the default
.Ql Li /usr/libexec/dwatch:/usr/local/libexec/dwatch .
If set to NULL,
no profiles will be loaded.
wblockUnsubmitted
Done
Inline Actions
profiles are not loaded.
wblock: ```profiles are not loaded.```
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Below are some examples of how to use
.Nm
to watch system activity:
.Pp
.Nm
wblockUnsubmitted
Done
Inline Actions

Examples usually do not use the synopsis markup, but indent them to make them stand out. Here is one from gpart.8:

We create a 472-block (236 kB) boot partition at offset 40, which is
the size of the partition table (34 blocks or 17 kB) rounded up to the
nearest 4 kB boundary.
.Bd -literal -offset indent
/sbin/gpart add -b 40 -s 472 -t freebsd-boot ada0
/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
.Ed
.Pp
wblock: Examples usually do not use the synopsis markup, but indent them to make them stand out. Here…
.Ar on-cpu
.Dl Watch processes entering system CPU scheduler.
.Pp
.Nm
.Fl 1
.Fl Q
.Dl List available profiles, one line per profile.
.Pp
.Nm
.Fl d
fsync
.Dl "Do not" execute Xr dtrace 1 but display script on stdout and exit.
.Pp
.Nm
.Fl e
.Ar test_probe
.Dl Compile and test but do not execute code generatd with given probe.
markjUnsubmitted
Done
Inline Actions

*generated

markj: *generated
.Pp
.Nm
.Fl E Ar 'printf("%i", arg1)'
zfs_sync
.Dl Print argument one being passed to each call of zfs_sync().
.Pp
.Nm
.Fl f
.Ar read
.Dl Watch all functions named Ql Li read .
.Pp
.Nm
.Fl F
.Ar ":"
.Dl Watch all function traversal.
.Pp
.Nm
.Fl F
.Ar syscall
.Dl Watch syscall function traversal.
.Pp
.Nm
.Fl g Ar wheel
execve
.Dl Display only processes belonging to wheel super-group.
.Pp
.Nm
.Fl g Ar '1|65534'
.Ar execve
.Dl Display only processes belonging to groups \
So Li daemon Sc \
or \
So Li nobody Sc .
.Pp
.Nm
.Fl j Ar 0
execve
.Dl Ignore jails, displaying only base system processes.
.Pp
.Nm
.Fl j Ar myjail
execve
.Dl Display only processes running inside the jail named Ql Li myjail .
.Pp
.Nm
.Fl k Ar 'ruby*'
.Fl F
.Ar syscall
.Dl Watch syscall function traversal by ruby processes.
.Pp
.Nm
.Fl k Ar '*daemon*'
.Fl F
.Ar syscall
.Dl Watch syscall function traversal by processes containing Ql Li daemon
.Dl in their name.
.Pp
.Nm
.Fl l
.Fl f
.Dl Display a list of unique functions available.
.Pp
.Nm
.Fl l
.Fl f Ar '*read'
.Dl List available probes for functions ending in Ql Li read .
.Pp
.Nm
.Fl l
.Fl r Ar 'read$'
.Dl List available probes ending in Dq Li read .
.Pp
.Nm
.Fl l
.Fl P
.Dl Display a list of unique providers.
.Pp
.Nm
.Fl M Ar vop_remove
.Dl Watch paths being removed by Xr VOP_REMOVE 9 .
.Pp
.Nm
.Fl M Ar kill
.Dl Watch signals being passed to Xr kill 2 .
.Pp
.Nm
.Fl n Ar read
.Dl Watch the name \
So Li read Sc \
instead of the function \
So Li read Sc . \
The dwatch selection algorithm will commonly favor the function named \
So Li read Sc \
when not given a type \
Po using So Fl P Sc , So Fl m Sc , So Fl f Sc , or So Fl n Sc Pc \
because there are more probes matching the function named \
So Li read Sc \
than probes matching \
So Li read Sc \
for any other type.
.Pp
.Nm
.Fl N Ar 1
kill
.Dl Display the first process to call Xr kill 2 and then exit.
.Pp
.Nm
.Fl p Ar 1234
execve
.Dl Watch processes forked by pid 1234.
.Pp
.Nm
.Fl p Ar '1234|5678' execve
.Dl Watch processes forked by either pid 1234 or pid 5678.
.Pp
.Nm
.Fl P
.Ar random
.Dl Watch the provider \
So Li random Sc \
instead of the function \
So Li random Sc . \
The dwatch selection algorithm will commonly favor the function named \
So Li random Sc \
when not given a type \
Po using So Fl P Sc , So Fl m Sc , So Fl f Sc , or So Fl n Sc Pc \
because there are more probes matching the function named \
So Li random Sc \
than probes matching the provider named \
So Li random Sc .
.Pp
.Nm
.Fl Q
.Fl r Ar vop
.Dl Display available profiles matching Ql Li vop .
.Pp
.Nm
.Fl r Ar /lib/
.Fl M Ar vop_lookup
.Dl Watch Xr VOP_LOOKUP 9 paths containing So Li /lib/ Sc .
.Pp
.Nm
.Fl R
execve
.Dl Show process tree for each command as it is executed.
.Pp
.Nm
.Fl R Fl p Ar 1234
execve
.Dl Watch processes forked by pid 1234 or children thereof .
.Pp
.Nm
.Fl t Ar 'arg2<10'
.Fl E Ar 'printf("%d",arg2)'
write
.Dl Display processes calling Xr write 2 with Do nbytes Dc less than 10 .
.Pp
.Nm
.Fl T Ar 5m
.Ar statfs
.Dl Watch So Li statfs Sc for 5 minutes and exit.
.Pp
.Nm
.Fl u Ar root
execve
.Dl Display only processes belonging to the root super-user.
.Pp
.Nm
.Fl u Ar '1|65534'
.Ar execve
.Dl Display only processes belonging to users \
So Li daemon Sc \
or \
So Li nobody Sc .
.Pp
.Nm
.Fl V
.Dl Print version and exit.
.Pp
.Nm
.Fl y
.Fl N Ar 100
preempt | less
.Fl R
.Dl View the first 100 scheduler preemptions.
.Pp
.Nm
.Fl z Ar '(mk|rm)dir'
execve
.Dl Display processes matching either Do Li mkdir Dc or Do Li rmdir Dc .
.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