====== 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.

  - Enable building of debug symbols

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

  - For %%FreeBSD%% versions **earlier than 10.0**, add:

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

  - For **AMD64** (all versions), add:

<code>
options KDTRACE_FRAME        # amd64 - ensure frames are compiled in
</code>

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

<code>
makeoptions WITH_CTF=1
</code>

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

===== Rebuild and install the kernel =====

  - For %%FreeBSD%% 9 or later

<code>
make buildkernel KERNCONF=DTRACE
</code>

  - For %%FreeBSD%% 8-STABLE or earlier

<code>
make buildkernel WITH_CTF=1 KERNCONF=DTRACE
</code>

  - Install the kernel and reboot

<code>
make installkernel KERNCONF=DTRACE
shutdown -r now
</code>

===== Getting Started =====

**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.

  - Load some or all DTrace kernel modules:

<code>
kldload dtraceall
</code>

  - Confirm that you have piles of available DTrace hooks:

<code>
dtrace -l | head
</code>

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

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

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

<code>
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
</code>

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

===== Userland DTrace =====

==== FreeBSD 9.0 or later ====

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

<code>
STRIP=
CFLAGS+=-fno-omit-frame-pointer
</code>

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

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

<code>
make buildworld
shutdown -r NOW
boot -s
make installworld
reboot
</code>

==== FreeBSD 8-STABLE or earlier ====

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

<code>
STRIP=
CFLAGS+=-fno-omit-frame-pointer
</code>

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

  - Rebuild and install world:

<code>
make WITH_CTF=1 buildworld
shutdown -r NOW
boot -s
make installworld
</code>

===== Hints =====

  * 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**"

----

{{tag>Dtrace Historical}}