Adding DTrace support to the kernel

Note: as of May 2012, DTrace support is enabled by default in GENERIC, and the steps below are not needed. If you are using a custom kernel config, make sure that all the lines below are present.

1. Enable building of debug symbols

makeoptions DEBUG="-g"       # build kernel with gdb(1) debug symbols

1. For FreeBSD versions earlier than 10.0, add:

options KDTRACE_HOOKS      # all architectures - enable general DTrace hooks
options DDB_CTF            # all architectures - kernel ELF linker loads CTF data

1. For AMD64 (all versions), add:

options KDTRACE_FRAME        # amd64 - ensure frames are compiled in

1. For FreeBSD 9.0 or later, WITH_CTF=1 must be defined in the kernel config:

makeoptions WITH_CTF=1

Note: It will not be picked up from make.conf or src.conf for the kernel build.

1. For FreeBSD 9 or later

make buildkernel KERNCONF=DTRACE

1. For FreeBSD 8-STABLE or earlier

make buildkernel WITH_CTF=1 KERNCONF=DTRACE

1. Install the kernel and reboot

make installkernel KERNCONF=DTRACE
shutdown -r now

Note: You'll need to su to root in order to use DTrace, which may be fixed once we add a more comprehensive fine-grained privilege policy.

1. Load some or all DTrace kernel modules:

kldload dtraceall

1. Confirm that you have piles of available DTrace hooks:

dtrace -l | head

1. Confirm that the kernel was compiled correctly with tracing by running a DTrace one liner.

dtrace -n 'syscall:::entry { @num[execname] = count(); }'

If you see an error stemming from one of the DTrace files in /usr/lib, such as this:

dtrace: invalid probe specifier syscall:::entry { @num[execname] = count(); }: "/usr/lib/dtrace/psinfo.d", line 37: failed to copy type of 'pr_uid': Type information is in parent and unavailable

then you do not have DTrace properly compiled in. Go back and check your work.

1. For userland DTrace support add the following to your make.conf (or src.conf if you want it just for the base system):

STRIP=
CFLAGS+=-fno-omit-frame-pointer

This allows stack traces to work and display even more information.

1. Rebuild and install world with 'WITH_CTF=1' in either make.conf (if you also want to have it for ports) or src.conf:

make buildworld
shutdown -r NOW
boot -s
make installworld
reboot

1. For userland DTrace support add the following to your make.conf:

STRIP=
CFLAGS+=-fno-omit-frame-pointer

This allows stack traces to work and display even more information.

1. Rebuild and install world:

make WITH_CTF=1 buildworld
shutdown -r NOW
boot -s
make installworld

• If you get the following error during buildworld make: don't know how to make /usr/lib/libctf.a. Stop, then your current world is missing CDDL support. Comment out any WITHOUT_CDDL= entries in your make.conf and src.conf. Then do cd /usr/src/cddl/lib/libctf; make obj depend all install. Now you should be able to compile world with DTrace support. (Thanks Rob)
• If D-scripts fail with a message such as syntax error “near uid_t”, then you forgot to compile your kernel with gdb(1) debug symbols enabled. Add makeoptions DEBUG=“-g” to your kernel config and try again.
• If you are setting MODULES_OVERRIDE in your make.conf in order not to build all kernel modules, adding the following entries should give you dtrace support: “MODULES_OVERRIDE += opensolaris dtrace cyclic nfsclient krpc nfs_common nfslock”