--- wikisrc/tutorials/how_to_enable_and_run_dtrace.mdwn 2014/09/10 14:04:44 1.8 +++ wikisrc/tutorials/how_to_enable_and_run_dtrace.mdwn 2018/07/22 17:18:06 1.26 @@ -1,4 +1,5 @@ -DTrace is a Dynamic Tracing framework developed by Sun and ported to NetBSD. It enables extensive instrumentation of the kernel and user space. See the [DTrace Community Page](http://dtrace.org) for more information. Also see [DTrace Introduction](http://dtrace.org/guide/preface.html). +DTrace is a Dynamic Tracing framework developed by Sun and ported to NetBSD. It enables extensive instrumentation of the kernel and user space. See the [DTrace Community Page](http://dtrace.org) for more information. +Also see [DTrace Introduction](http://dtrace.org/guide/preface.html), Brendan Gregg's [DTrace one liners](http://www.brendangregg.com/DTrace/dtrace_oneliners.txt) and his notes for [DTrace on FreeBSD](https://wiki.freebsd.org/DTrace/). # Current status @@ -7,60 +8,57 @@ DTrace is a Dynamic Tracing framework de DTrace is a work-in-progress effort and it is for x86 systems and some arm boards. * i386 and amd64 -* evbarm - * BEAGLEBONE and SHEEVAPLUG +* earm* (evbarm and armv4 based ports) ## Supported providers -* SDT: Statically Defined Tracing +* DTrace: What to do when a script BEGINs, ENDs, ERRORs * FBT: Function Boundary Tracing - -You can currently run a hello world DScript. +* IO: Disk I/O +* Lockstat: Kernel Lock Statistics +* Proc: Process and thread related events +* Profile: Time based interrupt event source for Profiling +* SDT: Statically Defined Tracing +* Syscall: System Calls +* Syscall Linux (32bit & 64 bit): System calls via the Linux binary emulation layer +* VFS: Filesystem operations (confined to namecache events at time of writing - 8.99.22) ## TODO for netbsd-7 -* Rename provider modules to `dtrace_*.kmod`: `dtrace_fbt.kmod`, &c. * Measure effect of `options KDTRACE_HOOKS` on system performance. * Determine whether the profile module works and list it here. -* Put a dtrace target in /dev/MAKEDEV. * Integrate [[riz|users/riz]]'s syscall provider patch. -## TODO for netbsd-6 - -Need to identify changes to pull up to netbsd-6 and pull them up. -Candidates: - -* Profile provider. - # How to use ## Building DTrace You need the following options in your kernel: - options INSECURE - options KDTRACE_HOOKS # DTrace support + options KDTRACE_HOOKS # kernel DTrace hooks options MODULAR - -You also need to build distribution with the options MKDTRACE=yes. +Optionally: -## Running hello world + options INSECURE # permit modules to loaded from user space once system has gone multiuser and securelevel has been raised. -Load the solaris and dtrace modules, and the SDT (Statically Defined Tracing) and FBT (Function Boundary Tracing) modules: - - modload solaris - modload dtrace - modload sdt - modload fbt - +A Distribution needs to be built with the options `MKDTRACE=yes` and `MKCTF=yes`, this is taken care of automatically and doesn't need to be specified manually. The list of platforms it is applied to automatically is set in `src/share/mk/bsd.own.mk` -Make the dtrace device node: +Set the system to load the solaris and dtrace related modules in `/etc/modules.conf`, for a list of available modules, see `/stand/$MACHINE/$VERSION/modules/` + +For example, add the following to `/etc/modules.conf` (the file may not exist already on a system): - mkdir /dev/dtrace - mknod /dev/dtrace/dtrace c dtrace 0 +- `solaris` +- `dtrace` +- `dtrace_fbt` +- `dtrace_lockstat` +- `dtrace_profile` +- `dtrace_sdt` +- `dtrace_syscall` +- `dtrace_syscall_linux` + +A `dtrace` device node is created automatically in `/dev/dtrace` when the modules are loaded into place. - List the dtrace probes dtrace -l @@ -83,12 +81,11 @@ List the dtrace probes . 29140 proc lwp_start 29141 proc lwp_exit - - +## Running hello world -Put the following into the file hello.d +Put the following into the file hello.d: BEGIN { @@ -106,27 +103,48 @@ Run the hello world script: 0 1 :BEGIN Hello world -A more complex example that traces the execution of a sleep operation in the kernel: +## A more complex example + +The following script traces the execution of a sleep operation +in the kernel. Put it in sleep.d: #pragma D option flowindent - - fbt::syscall:entry + + syscall::nanosleep:entry /execname == "sleep" && guard++ == 0/ { self->traceme = 1; - printf("fd: %d", arg0); } - + fbt::: /self->traceme/ {} - - fbt::syscall:return + + syscall::nanosleep:return /self->traceme/ { self->traceme = 0; exit(0); } - -Start the script running (dtrace -s ) and then execute a sleep 2 in another shell. +Start the script running: + + dtrace -s sleep.d + +This will take a while as the script instruments every function in the +kernel. When it's ready, it will print a message like "dtrace: script +'sleep.d' matched 59268 probes". Then execute a "sleep 2" in another +shell. + +## Tools included in base + +Starting with NetBSD-8, on builds where `MKDTRACE=yes` is set, scripts from +[Brendan Gregg's DTrace toolkit](https://github.com/opendtrace/toolkit/) are installed in base as standard. + +At present, the following scripts are installed in `/usr/sbin`: + +- `dtruss` - An implementation of the truss utility in DTrace which traces the system calls +made by a process +- `execsnoop` - snoop on execution of processes as they occur +- `opensnoop` - snoop on openning of files as they occur +- `procsystime` - print process system call time details.