Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DWATCH(1)		  BSD 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>

BSD			       February	9, 2018				   BSD

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PROFILES | ENVIRONMENT | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dwatch&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help