Differential D10006 Diff 26792 cddl/usr.sbin/dwatch/dwatch.8

Changeset 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.
				Hide informational messages and errors from dtrace(1).
				.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