DWATCH(1)

💅 DWATCH — the manual page, but make it make sense

okay so bestie, welcome to dwatch(1) from the General Commands Manual section. this is the whole thing, translated. grab a boba, we're going in 🧋✨

---

✨ NAME ✨

dwatch — watch processes the literal moment they trigger a particular DTrace probe 👀🔥

---

🌸 SYNOPSIS 🌸

like, the shapes this command can take:

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 💖

okay so dwatch is basically a glow-up wrapper around dtrace(1) — it shows you process info the second a given DTrace probe point fires. so iconic of it. ✨

🚨 real talk: only the root user, or users with sudo(8) (ports/security/sudo) access, can run this. it's giving VIP list, no cap.

what dwatch actually does is automate the whole tedious process of generating DTrace scripts that coalesce trace output by date/time, process info, and — if you want — probe-specific data. it's the automation bestie you didn't know you needed 🫶

the output format without any 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 makes dwatch coalesce trace output by date/time, process info, and probe traversal instead. slay 💅

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 makes dwatch show a whole process tree — parent, grandparent, and ancestor process info. it's giving family tree reveal 😭💀

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

now the part that's actually the main character: filtering with regular expressions 🔍 the -g group, -p pid, -r regex, -u user, and -z regex options can all be combined with -R so you match on parent process criteria as well as current process info. so you can be like "show me the tree, but only where the ancestor matches this regex." obsessed.

in contrast (important!!), the -j jail and -k name options apply only to the current process even if -R is given. read that again. no, it does not cascade. 🙈

the -E code option gives you 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. cute and useful, we love her 💜

profiles can be written for more complex routines and/or convenience. to list available profiles use the -Q option. to use a particular profile, use the -X profile option.

for example, the command dwatch -X kill displays arguments sent to kill(2). periodt.

---

🎀 OPTIONS 🎀

okay so first, some housekeeping before the option list because it's important:

if a probe argument does not contain a colon (":") and none of -P, -m, -f, or -n are given, the probe argument gets intelligently mapped to its most-likely value. use dwatch -l name to see what probes will match a given name. it's like autocomplete but for probes ✨

multiple probes must be given as a single (quoted) argument, separated by comma and/or whitespace. any/all arguments following said probes get passed to dtrace(1) unmodified — no touchy, no changes.

now the full menu:

• -1 — print one line per process/profile. this is the default, and it disables -R.
• -B num — maximum number of arguments to display (default 64).
• -d — debug mode. send the dtrace(1) script to stdout instead of executing it. very "let me see the receipts" of you.
• -e — exit after compiling the request but before enabling probes.
• -E code — DTrace code for event details. if it's -, read from stdin. this lets you customize what gets printed after the date/time and process info. by default, the name and arguments of the program 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 the group name/gid. this can be an awk(1) regular expression to match a numerical gid. fancy fr fr.
• -j jail — jail filter. only show processes matching the 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. it's giving wildcard energy 🌈
• -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 it's -, the path /dev/stdout is used.
• -O cmd — execute cmd for each event. this can be any valid sh(1) command. the environment variables $TAG and $DETAILS are set for the given cmd. very "run my little script" of it 🫶
• -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. blissful silence 😌
• -Q — list available profiles in DWATCH_PROFILES_PATH and exit.
• -r regex — filter. only show blocks matching the awk(1) regular expression.
• -R — show parent, grandparent, and ancestor of process. family reunion edition 🌳
• -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). the opposite of -q, we love range 💅
• -V — report dwatch version on standard output and exit.
• -w — permit destructive actions (copyout*, stop, panic, etc.).

⚠️ bestie. -w literally permits destructive actions. panic is in that list. panic. i'm not saying don't, i'm saying know what you're doing, okay?? 😭💀

• -x — trace. print <probe-id> when a probe is triggered.
• -y — always treat stdout as console (enable colors/columns/etc.). giving main character display energy 🎨
• -z regex — only show processes matching the 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 (so yes, there are more, don't come for me):

• 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)

look at all those vop_* children. a whole squad 🧚✨

---

💜 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. (iconic "i don't need profiles today" behavior 🙈)

---

⭐ EXIT STATUS ⭐

dwatch exits 0 on success, and >0 if an error occurs. classic. clean. no notes.

🎀 EXAMPLES 🎀

Okay bestie, this is the part where the manpage just shows you the moves. Every single command stays exactly as written — no cap.

Watch processes entering the system CPU scheduler.

dwatch on-cpu

List available profiles, one line per profile.

dwatch -1 -Q

Do not execute dtrace(1) — just display the script on stdout and exit.

dwatch -d fsync

Compile and test, but do not execute the code generated with the 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 the wheel super-group.

dwatch -g wheel execve

Display only processes belonging to groups daemon or nobody.

dwatch -g '1|65534' execve

Ignore jails — display 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) (ports/shells/bash) 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 selection 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) — the other icon you'll be hanging out with 💫

🦋 HISTORY 🦋

dwatch first appeared in FreeBSD 11.2. Periodt.

👑 AUTHORS 👑

The author is Devin Teske <dteske@FreeBSD.org> 💖

Source/version: Debian. Date: April 18, 2025. That's the cute little footer energy, bestie — mwah! 💋✨