cddl/contrib/dtracetoolkit/Notes/ALLfbt_notes.txt

   1 **************************************************************************
   2 * The following are notes for any script that uses the "fbt" provider.
   3 * To identify these scripts, check the "STABILITY" section of the script's
   4 * man page, or try grepping for "fbt" on the script.
   5 *
   6 * $Id: ALLfbt_notes.txt 44 2007-09-17 07:47:20Z brendan $
   7 *
   8 * COPYRIGHT: Copyright (c) 2007 Brendan Gregg.
   9 **************************************************************************
  10
  11
  12 What is the "fbt" provider?...
  13
  14 * A DTrace library of probes that instruments raw kernel function calls.
  15 * An "unstable" provider; meaning, scripts written using "fbt" are not
  16   guarenteed to work on future versions of the OS - including after
  17   patching the kernel.
  18
  19 In a perfect world...
  20
  21 * None of the DTraceToolkit scripts would use the "fbt" provider; instead
  22   they would all use stable providers such as "proc", "sched", "io", etc.
  23 * All the DTraceToolkit scripts would run on any system that supports DTrace.
  24
  25 In the real world...
  26
  27 * Not all stable providers exist yet. Many are in development, such as
  28   stable networking providers.
  29 * In the meantime, useful tools such as "tcpsnoop" and "tcptop" can
  30   only be written using the unstable "fbt" provider (and these scripts have
  31   broken several times due to kernel changes since they were first written).
  32 * "fbt" provider based scripts,
  33         - only run on a particular OS (eg, Solaris)
  34         - may only run on a particular version of an OS (eg, Solaris 10 3/05)
  35         - are likely to break for future OS releases (eg, Solaris 10 6/06)
  36 * "fbt" provider based scripts also make the impossible possible, albiet
  37   in a very unstable way, as a temporary solution while stable providers
  38   are still in development.
  39 * Once stable providers exist, "fbt" scripts can be rewritten to use them;
  40   however these new scripts will only run on newer OS builds that support
  41   the stable providers. (in other words, this won't help you if you remain
  42   on Solaris 10 6/06; you'll need to upgrade, or survive with "fbt").
  43 * Only some of the DTraceToolkit scripts use "fbt", and only a portion of
  44   those have encountered stability issues - so this issue is limited.
  45
  46 The "fbt" provider exports raw kernel implementation, which isn't guarenteed
  47 to be stable nor should it ever be (to do so would freeze kernel development
  48 and bug fixes). The only practical solution is the development and
  49 integration of stable providers (although that doesn't help people who keep
  50 running older versions of the OS).
  51
  52 More harm than good?...
  53
  54 Is the inclusion of these "fbt" scripts more harm than good? Consider,
  55
  56 * the good,
  57         - shows what is possible with DTrace
  58         - should help a number of people solve specific performance issues,
  59           on systems where they run
  60         - a customer who really wants these scripts but on an OS version
  61           where they don't work, have at least the source as a starting
  62           point (and in some cases, the fix was trivial)
  63
  64 * the bad,
  65         - teases and frustrates people who find these scripts don't work
  66           on their OS
  67
  68 To minimise this issue, only a small number of "fbt" scripts have been
  69 included, and they have been documented (see their man page) as unstable.
  70
  71 Can I help?...
  72
  73 If you really like an "fbt" based script and would like to keep using it
  74 in a stable way, it may help to raise that with your vendor (Sun for Solaris,
  75 Apple for MacOS). Sun has OpenSolaris forums, such as dtrace-discuss, which
  76 are read by their engineers and the public.
  77