svn commit: r190837 - in stable/7/sys: . contrib/pf dev/ath/ath_hal dev/cxgb kern

[Robert Watson]

On Wed, 8 Apr 2009, Robert Watson wrote:

>>>> While the probes I've added could be used to do this very easily, that's 
>>>> not the thrust of the work I'm currently doing.  A useful starting point 
>>>> for someone interested in this problem would be a dtrace script like the 
>>>> following:
>>>> 
>>>> vfs:namecache:enter:done
>>> 
>>> Also useful: the same script, but using "vfs:namecache:lookup:hit".
>>> 
>> Perhaps we should start to put such scripts somewhere to src/tools.
>
> This sort of script isn't really worth putting in a library, as it's 
> composed only of the most basic language constructs and a single probe. 
> I'd rather reserve a tools tree for things that reflect a significant 
> investment in time to write, rather than things that can be written in 
> thirty seconds given a rudimentary knowledge of the D scripting language. 
> Otherwise we'll be buried in scripts that have little utility and unable to 
> find scripts that are useful.
>
> Something we do need to do is begin to formally document the sets of probes 
> we're adding, because these sorts of trivial scripts become a lot more 
> obvious it you know the probes exist and what they do :-).  I'm not sure 
> what the conventions for said man pages should be - perhaps vfs_probes(4) or 
> vfs_dtrace(4) or the like, broken into a parts that include a summary of the 
> goal of the provider, a list of the specific probes, etc?

Scott has suggested that these sorts of example scripts are particularly 
helpful when just getting started with DTrace, so perhaps the thing to do is 
this: I've collected a set of such scripts on our wiki here:

   http://wiki.freebsd.org/DTrace/Examples

They illustrate some of the facilities of the D language, what you can do with 
some of the probes we have in the tree already, etc.  It would be fairly 
straight forward to take this Wiki page and convert it into a new section of 
the FreeBSD Handbook's DTrace chapter, basically just adding a bit more 
annotation and explanation of the scripts.

Most of the scripts on the Wiki page don't yet work in FreeBSD 7-STABLE, as 
they rely on probes I've added shortly before or since the code freeze for 7.2 
began, FYI, but hopefully will start working in 7.x starting a bit after the 
code freeze is relaxed.

Also notice that these DTrace scripts really only help you when analyzing the 
behavior of the FreeBSD kernel, as we don't yet have proper tracing support 
for userspace events (i.e., the "pid" provider).

Finally, the best reference I've found for DTrace so far is really the Solaris 
Dynamic Tracing Guide, which includes an introduction to the language, review 
of the providers available on Solaris, and example scripts that use them.  As 
with all programming languages, learning by doing is best, of course...

Robert N M Watson
Computer Laboratory
University of Cambridge