FreeBSD Manual Pages
DWATCH(1) FreeBSD General Commands Manual DWATCH(1) NAME dwatch -- watch processes as they trigger a particular DTrace probe SYNOPSIS dwatch [-1defFmnPqRvVwxy] [-B num] [-E code] [-g group] [-j jail] [-k name] [-K num] [-N count] [-o file] [-O cmd] [-p pid] [-r regex] [-t test] [-T time] [-u user] [-X profile] [-z regex] [--] [probe[,...]] [args ...] dwatch -l [-fmnPqy] [-r regex] [probe ...] dwatch -Q [-1qy] [-r regex] DESCRIPTION The dwatch utility uses dtrace(1) to display process info when a given DTrace probe point is triggered. Only the root user or users with sudo(8) access can run this command. dwatch automates the process of generating DTrace scripts to coalesce trace output by date/time, process info, and [optionally] probe-specific data. Output format without options is: date/time uid.gid execname[pid]: psargs For example, the command `dwatch BEGIN' produces: INFO Watching 'dtrace:::BEGIN' ... 2017 May 29 08:23:20 0.0 dtrace[60671]: dtrace -s /dev/stdin The -F option causes dwatch to instead coalesce trace output by date/time, process info, and probe traversal. Output format with the `-F' option is: date/time uid.gid execname[pid]: {->,<-, |} prov:mod:func:name ... For example, the command `dwatch -F BEGIN' produces: INFO Watching 'dtrace:::BEGIN' ... 2017 May 29 21:34:41 0.0 dtrace[86593]: | dtrace:::BEGIN ... The -R option causes dwatch to display a process tree containing the par- ent, grandparent, and ancestor process info. Output format with the `-R' option is: date/time uid0.gid0 execname[pid0]: psargs0 -+= pid3 uid3.gid3 psargs3 \-+= pid2 uid2.gid2 psargs2 \-+= pid1 uid1.gid1 psargs1 \-+= pid0 uid0.guid0 psargs0 For example, the command `dwatch -R BEGIN' produces: INFO Watching 'dtrace:::BEGIN' ... 2017 May 29 21:38:54 0.0 dtrace[86899]: dtrace -s /dev/stdin -+= 86855 604.604 -bash \-+= 86857 604.604 /bin/sh /usr/sbin/dwatch -R BEGIN \-+= 86897 0.0 sudo dtrace -s /dev/stdin \-+= 86899 0.0 dtrace -s /dev/stdin Of particular interest is the ability to filter using regular expres- sions. The `-g group', `-p pid', `-r regex', `-u user', and `-z regex' options can be combined with `-R' to match on parent process criteria as well as current process info. In contrast, the `-j jail', and `-k name' options apply only to the cur- rent process even if `-R' is given. The `-E code' option gives the ability to customize probe-specific data. For example, the command: dwatch -E 'printf("%s", copyinstr(arg0))' chdir displays the path argument sent to chdir(2) calls. Profiles can be written for more complex routines and/or convenience. To list available profiles use the `-Q' option. Use the `-X profile' option to use a particular profile. For example, the command `dwatch -X kill' displays arguments sent to kill(2). OPTIONS If a probe argument does not contain colon (":") and none of `-P', `-m', `-f', or `-n' are given, the probe argument is intelligently mapped to its most-likely value. Use `dwatch -l name' to see what probes will match a given name. Multiple probes must be given as a single (quoted) argument, separated by comma and/or whitespace. Any/all arguments following said probes will be passed to dtrace(1) unmodified. -1 Print one line per process/profile (Default; disables `-R'). -B num Maximum number of arguments to display (Default 64). -d Debug. Send dtrace(1) script to stdout instead of executing. -e Exit after compiling request but prior to enabling probes. -E code DTrace code for event details. If `-', read from stdin. This allows customization of what is printed after date/time and process info. By default, the name and arguments of the pro- gram triggering the probe are shown. Can be specified multiple times. -f Enable probes matching the specified function names. -F Coalesce trace output by probe. -g group Group filter. Only show processes matching group name/gid. This can be an awk(1) regular expression to match a numerical gid. -j jail Jail filter. Only show processes matching jail name/jid. -k name Only show processes matching name. Can also be of the format `name*' to indicate "begins with", `*name' to indicate "ends with", or `*name*' to indicate "contains". Can be specified multiple times. -K num Maximum directory depth to display (Default 64). -l List available probes on standard output and exit. -m Enable probes matching the specified module names. -X profile Load profile from DWATCH_PROFILES_PATH. -n Enable probes matching the specified probe names. -N count Exit after count matching entries (Default 0 for disabled). -o file Set output file. If `-', the path `/dev/stdout' is used. -O cmd Execute cmd for each event. This can be any valid sh(1) com- mand. The environment variables `$TAG' and `$DETAILS' are set for the given cmd. -p pid Process id filter. Only show processes with matching pid. This can be an awk(1) regular expression. -P Enable probe matching the specified provider name. -q Quiet. Hide informational messages and all dtrace(1) errors. -Q List available profiles in DWATCH_PROFILES_PATH and exit. -r regex Filter. Only show blocks matching awk(1) regular expression. -R Show parent, grandparent, and ancestor of process. -t test Test clause (predicate) to limit events (Default none). Can be specified multiple times. -T time Timeout. The format is `#[smhd]' or just `#' for seconds. -u user User filter. Only show processes matching user name/uid. This can be an awk(1) regular expression to match a numerical UID. -v Verbose. Show all errors from dtrace(1). -V Report dwatch version on standard output and exit. -w Permit destructive actions (copyout*, stop, panic, etc.). -x Trace. Print `<probe-id>' when a probe is triggered. -y Always treat stdout as console (enable colors/columns/etc.). -z regex Only show processes matching awk(1) regular expression. PROFILES Profiles customize the data printed during events. Profiles are loaded from a colon-separated list of directories in DWATCH_PROFILES_PATH. This is an incomplete list of profiles with basic descriptions: chmod Print mode and path from chmod(2), lchmod(2), fchmodat(2) errno Print non-zero errno results from system calls io Print disk I/O details provided by dtrace_io(4) ip Print IPv4 and IPv6 details provided by dtrace_ip(4) kill Print signal and pid from kill(2) nanosleep Print requested time from nanosleep(2) open Print path from open(2), openat(2) proc Print process execution details provided by dtrace_proc(4) proc-signal Print process signal details provided by dtrace_proc(4) rw Print buffer contents from read(2), write(2) sched Print CPU scheduling details provided by dtrace_sched(4) tcp Print TCP address/port details provided by dtrace_tcp(4) tcp-io Print TCP I/O details provided by dtrace_tcp(4) udp Print UDP I/O details provided by dtrace_udp(4) vop_create Print filesystem paths being created by VOP_CREATE(9) vop_lookup Print filesystem paths being looked-up by VOP_LOOKUP(9) vop_mkdir Print directory paths being created by VOP_MKDIR(9) vop_mknod Print device node paths being created by VOP_MKNOD(9) vop_readdir Print directory paths being read by VOP_READDIR(9) vop_remove Print filesystem paths being removed by VOP_REMOVE(9) vop_rename Print filesystem paths being renamed by VOP_RENAME(9) vop_rmdir Print directory paths being removed by VOP_RMDIR(9) vop_symlink Print symlink paths being created by VOP_SYMLINK(9) ENVIRONMENT These environment variables affect the execution of dwatch: DWATCH_PROFILES_PATH If DWATCH_PROFILES_PATH is set, dwatch searches for profiles in the colon-separated list of directories in that variable instead of the default `/usr/libexec/dwatch:/usr/local/libexec/dwatch'. If set to NULL, profiles are not loaded. EXIT STATUS The dwatch utility exits 0 on success, and >0 if an error occurs. EXAMPLES Watch processes entering system CPU scheduler. dwatch on-cpu List available profiles, one line per profile. dwatch -1 -Q Do not execute dtrace(1) but display script on stdout and exit. dwatch -d fsync Compile and test but do not execute code generated with given probe. dwatch -e test_probe Print argument one being passed to each call of zfs_sync(). dwatch -E 'printf("%i", arg1)' zfs_sync Watch all functions named `read'. dwatch -f read Watch all probe traversal. dwatch -F : Watch syscall probe traversal. dwatch -F syscall Display only processes belonging to wheel super-group. dwatch -g wheel execve Display only processes belonging to groups `daemon' or `nobody'. dwatch -g '1|65534' execve Ignore jails, displaying only base system processes. dwatch -j 0 execve Display only processes running inside the jail named `myjail'. dwatch -j myjail execve Watch syscall traversal by ruby processes. dwatch -k 'ruby*' -F syscall Watch syscall traversal by processes containing `daemon' in their name. dwatch -k '*daemon*' -F syscall Watch signals being passed to kill(2). dwatch -X kill Watch signals being passed between bash(1) and vi(1). dwatch -k bash -k vi -X kill Display a list of unique functions available. dwatch -l -f List available probes for functions ending in `read'. dwatch -l -f '*read' List available probes ending in "read". dwatch -l -r 'read$' Display a list of unique providers. dwatch -l -P Watch paths being removed by VOP_REMOVE(9). dwatch -X vop_remove Watch the name `read' instead of the function `read'. The dwatch selec- tion algorithm will commonly favor the function named `read' when not given a type (using `-P', `-m', `-f', or `-n') because there are more probes matching the function named `read' than probes matching `read' for any other type. dwatch -n read Display the first process to call kill(2) and then exit. dwatch -N 1 kill Watch processes forked by pid 1234. dwatch -p 1234 execve Watch processes forked by either pid 1234 or pid 5678. dwatch -p '1234|5678' execve Watch the provider `random' instead of the function `random'. The dwatch selection algorithm will commonly favor the function named `random' when not given a type (using `-P', `-m', `-f', or `-n') because there are more probes matching the function named `random' than probes matching the provider named `random'. dwatch -P random Display available profiles matching `vop'. dwatch -Q -r vop Watch VOP_LOOKUP(9) paths containing `/lib/'. dwatch -r /lib/ -X vop_lookup Show process tree for each command as it is executed. dwatch -R execve Watch processes forked by pid 1234 or children thereof. dwatch -R -p 1234 execve Display processes calling write(2) with "nbytes" less than 10. dwatch -t 'arg2<10' -E 'printf("%d",arg2)' write Display write(2) buffer when "execname" is not `dtrace' and "nbytes" is less than 10. dwatch -X write -t 'execname != "dtrace" && this->nbytes < 10' Watch `statfs' for 5 minutes and exit. dwatch -T 5m statfs Display only processes belonging to the root super-user. dwatch -u root execve Display only processes belonging to users `daemon' or `nobody'. dwatch -u '1|65534' execve Print version and exit. dwatch -V View the first 100 scheduler preemptions. dwatch -y -N 100 preempt | less -R Display processes matching either "mkdir" or "rmdir". dwatch -z '(mk|rm)dir' execve Run a command and watch network activity only while that command runs. dwatch -X tcp -- -c "nc -zvw10 google.com 22" Watch open(2) and openat(2) calls only while pid 1234 is active. dwatch -X open -- -p 1234 Watch probe traversal for a given command. Note that "-c true" is passed to dtrace(1) since it appears after the dwatch probe argument. dwatch -F 'pid$target:::entry' -c true SEE ALSO dtrace(1) HISTORY dwatch first appeared in FreeBSD 11.2. AUTHORS Devin Teske <dteske@FreeBSD.org> FreeBSD 13.0 February 9, 2018 FreeBSD 13.0
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PROFILES | ENVIRONMENT | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dwatch&sektion=1&manpath=FreeBSD+13.2-RELEASE+and+Ports>