diff options
Diffstat (limited to 'cddl/contrib/dtracetoolkit/Notes/ALLfbt_notes.txt')
-rw-r--r-- | cddl/contrib/dtracetoolkit/Notes/ALLfbt_notes.txt | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/cddl/contrib/dtracetoolkit/Notes/ALLfbt_notes.txt b/cddl/contrib/dtracetoolkit/Notes/ALLfbt_notes.txt new file mode 100644 index 0000000..ef5f2b8 --- /dev/null +++ b/cddl/contrib/dtracetoolkit/Notes/ALLfbt_notes.txt @@ -0,0 +1,77 @@ +************************************************************************** +* The following are notes for any script that uses the "fbt" provider. +* To identify these scripts, check the "STABILITY" section of the script's +* man page, or try grepping for "fbt" on the script. +* +* $Id: ALLfbt_notes.txt 44 2007-09-17 07:47:20Z brendan $ +* +* COPYRIGHT: Copyright (c) 2007 Brendan Gregg. +************************************************************************** + + +What is the "fbt" provider?... + +* A DTrace library of probes that instruments raw kernel function calls. +* An "unstable" provider; meaning, scripts written using "fbt" are not + guarenteed to work on future versions of the OS - including after + patching the kernel. + +In a perfect world... + +* None of the DTraceToolkit scripts would use the "fbt" provider; instead + they would all use stable providers such as "proc", "sched", "io", etc. +* All the DTraceToolkit scripts would run on any system that supports DTrace. + +In the real world... + +* Not all stable providers exist yet. Many are in development, such as + stable networking providers. +* In the meantime, useful tools such as "tcpsnoop" and "tcptop" can + only be written using the unstable "fbt" provider (and these scripts have + broken several times due to kernel changes since they were first written). +* "fbt" provider based scripts, + - only run on a particular OS (eg, Solaris) + - may only run on a particular version of an OS (eg, Solaris 10 3/05) + - are likely to break for future OS releases (eg, Solaris 10 6/06) +* "fbt" provider based scripts also make the impossible possible, albiet + in a very unstable way, as a temporary solution while stable providers + are still in development. +* Once stable providers exist, "fbt" scripts can be rewritten to use them; + however these new scripts will only run on newer OS builds that support + the stable providers. (in other words, this won't help you if you remain + on Solaris 10 6/06; you'll need to upgrade, or survive with "fbt"). +* Only some of the DTraceToolkit scripts use "fbt", and only a portion of + those have encountered stability issues - so this issue is limited. + +The "fbt" provider exports raw kernel implementation, which isn't guarenteed +to be stable nor should it ever be (to do so would freeze kernel development +and bug fixes). The only practical solution is the development and +integration of stable providers (although that doesn't help people who keep +running older versions of the OS). + +More harm than good?... + +Is the inclusion of these "fbt" scripts more harm than good? Consider, + +* the good, + - shows what is possible with DTrace + - should help a number of people solve specific performance issues, + on systems where they run + - a customer who really wants these scripts but on an OS version + where they don't work, have at least the source as a starting + point (and in some cases, the fix was trivial) + +* the bad, + - teases and frustrates people who find these scripts don't work + on their OS + +To minimise this issue, only a small number of "fbt" scripts have been +included, and they have been documented (see their man page) as unstable. + +Can I help?... + +If you really like an "fbt" based script and would like to keep using it +in a stable way, it may help to raise that with your vendor (Sun for Solaris, +Apple for MacOS). Sun has OpenSolaris forums, such as dtrace-discuss, which +are read by their engineers and the public. + |