Getting started with DTrace in FreeBSD-current (a.k.a. 8)

It's been a few weeks now since I committed DTrace support to current.

I did this without a headsup message to this list to give the early
adopters a chance to try it before exposing it to the world at large.

Those who follow the committers mailing list will have seen a lot
of commits to get all the changes into the tree.

As of now, the code is in the tree to build the tools required for
DTrace support and the DTrace kernel modules.

For the uninitiated, DTrace uses Compact C Type Format (CTF) data in
executables (both userspace and kernel modules). This CTF data is added
to the binaries by the build tools 'ctfconvert' and 'ctfmerge'.
ctfconvert parses DWARF debug ELF sections created by the compiler and
ctfmerge merges CTF ELF sections from objects into either executables
or shared libraries. 

To start using DTrace to trace stuff in the kernel (userland tracing
isn't supported yet), here's what you need to do:
 
1.  Grab the latest current sources for the entire src tree.
2.  Do a 'make buildworld' of those sources on either a -current system
    or a releng7 system.
3.  Add 'options KDTRACE_HOOKS' and 'options DDB_CTF' to your kernel
    config file (on i386 or amd64; users of other arches can go watch
    a movie instead).
4.  Do a 'make WITH_CTF=1 buildkernel && make installkernel'
5.  Reboot
6.  Do a 'make installworld && mergemaster -Ui'
7.  Reboot.
8.  Do a 'kldload dtraceall'
9.  Do a 'dtrace -l' to see that there are *lots* of probes available.
10. Read the DTrace wiki documentation:

    <http://wikis.sun.com/display/DTrace/Documentation>
11. Go wild!

There have been a few early adopters who have tried this with some
success, apparently. :-)

One FAQ to note: If you see an error when you run 'dtrace' reporting
that it doesn't know the type of uid_t, that means that you haven't
got CTF data in your kernel.

You can run 'ctfdump /boot/kernel/kernel' to look at the ELF CTF data
segment contents. You can run 'objdump -h /boot/kernel/kernel' to
see if you have an ELF CTF segment at all.

There are a few keen FreeBSD users who want to see DTrace appear
both in FreeBSD 7 and FreeBSD 6. I have done ports to both these
FreeBSD branches, but I need to follow project rules and have the
code settle in current first. Now is your call to do that, please!

Note that releng6 is at the end of it's development cycle, and is
mostly in support mode, but there are a number of companies with
products based on it which would like to see DTrace committed
to the RELENG_6 branch ASAP. The DTrace port to releng6 is ABI
compatible with a special kernel option called BREAK_SYSENT_ABI
for the one thing that would break. The option name should be
obvious. It only affect syscall tracing, and even if used, only
affects syscalls loaded dynamically by kernel modules. If you have
control over all your kernel module builds, then you won't have
a problem.

I'd like to thank Yahoo for funding the fast track of the ports to
FreeBSD-7 and FreeBSD-6. And a big thankyou to Sun Microsystems
for open-sourcing a fantastic feature from Solaris via OpenSolaris.

--
John Birrell