cddl/contrib/dtracetoolkit/Docs/History

   1 History - History of the DTraceToolkit
   2
   3 ------------------------------------------------------------------------------
   4 20-Apr-2005     Brendan Gregg   Idea
   5         For a while I had thought that a DTrace toolkit would be a nice
   6         idea, but on this day it became clear. I was explaining DTrace to
   7         an SSE from Sun (Canberra, Australia), who had a need for using
   8         DTrace but didn't have the time to sit down and write all the
   9         tools he was after. It simply made sense to have a DTrace toolkit
  10         that people could download or carry around a copy to use. Some
  11         people would write DTrace tools, others would use the toolkit.
  12 ------------------------------------------------------------------------------
  13 15-May-2005     Brendan Gregg   Version 0.30
  14         I had discussed the idea of a DTrace toolkit with the Sun PAE guys in
  15         Adelaide, Australia. It was making more sense now. It would be much
  16         like the SE Toolkit, not just due to the large number of sample
  17         scripts provided, but also due to the role it would play: few people
  18         wrote SE Toolkit programs, more people used it as a toolkit. While
  19         we would like a majority of Solaris users to write DTrace scripts,
  20         the reality is that many would want to use a prewritten toolkit.
  21         Today I created the toolkit as version 0.30, with 11 main directories,
  22         a dozen scripts, man pages and a structure for documentation.
  23 ------------------------------------------------------------------------------
  24 16-May-2005     Brendan Gregg   OneLiners
  25         I've been using the toolkit for a day now (wow!), and have noticed
  26         a few problems I've been fixing. One of them was the dtrace oneliners.
  27         I have them in two files, Docs/oneliners.txt and the examples in
  28         Docs/Examples/oneliners_examples.txt. The problem is that when I'm
  29         looking for a script, I'm looking in Docs/Commands - a list of the
  30         seperate script files, or I'm doing an ls or find. Ok, so I've now
  31         made each one liner a seperate script. This seems at first pretty
  32         silly since they are oneliners and shouldn't deserve an entire script
  33         each, but I've found having them as seperate scripts makes them far
  34         easier to find and use. The scripts and man page for each script do
  35         point out the fact that it's a one liner.
  36 ------------------------------------------------------------------------------
  37 17-May-2005     Brendan Gregg   Version 0.33
  38         Version 0.33 with 33 scripts. Maybe I should make the version number
  39         equal the script count. :) I just finished dtruss, dapptrace and
  40         dappprof.
  41 ------------------------------------------------------------------------------
  42 08-Jun-2005     Brendan Gregg   Name changes.
  43         I've renamed Docs/Commands to Docs/Contents. I found myself typing
  44         "more Docs/Contents" by mistake a lot. ok, maybe it made more sense
  45         to call it Contents after all. I've also made a symlink to it called
  46         Index.
  47 ------------------------------------------------------------------------------
  48 08-Jun-2005     Brendan Gregg   Version 0.35
  49         Version 0.35 with 35 scripts. Also touched up procsystime and some
  50         man pages. Added the CDDL version 1.0.
  51 ------------------------------------------------------------------------------
  52 09-Jun-2005     Brendan Gregg   Version 0.42
  53         Added 7 more scripts.
  54 ------------------------------------------------------------------------------
  55 14-Jun-2005     Brendan Gregg   Version 0.57
  56         Added heaps of new scripts. Now at 57 scripts.
  57 ------------------------------------------------------------------------------
  58 17-Jun-2005     Brendan Gregg   Version 0.61
  59         Restyled many commands.
  60 ------------------------------------------------------------------------------
  61 28-Jun-2005     Brendan Gregg   Version 0.70
  62         Added several commands including dexplorer. Developed a few useful
  63         variants of classic scripts while writing dexplorer, and have added
  64         them to the toolkit (I kept wanting to run them individually but
  65         not have to run an entire dexplorer).
  66 ------------------------------------------------------------------------------
  67 25-Jul-2005     Brendan Gregg   Version 0.77
  68         Added tcpsnoop.d, tcpsnoop, tcptop.  Because of their addition I have
  69         dropped tcpwbytes.d and tcpwlist.  These are complex scripts, but they
  70         track TCP in an accurate manner. However! also because they are
  71         complex scripts, I expect they will require maintainence for newer
  72         versions of [Open]Solaris, as various probes may change. They will
  73         become much more stable once a network provider has been added to
  74         DTrace (which may be some time away).
  75         Also added iotop, and updated a bunch of scripts. A lot of work went
  76         into this version, although the version change doesn't reflect that
  77         (I'm still keeping the version number == to number of scripts).
  78         Also added rwsnoop, rwtop, and more.
  79 ------------------------------------------------------------------------------
  80 26-Jul-2005     Brendan Gregg   Version 0.82
  81         Many new scripts added, many updates. This is a major release.
  82 ------------------------------------------------------------------------------
  83 17-Sep-2005     Brendan Gregg   Version 0.83
  84         A few scripts have been updated so that they work better.
  85         execsnoop, iosnoop, opensnoop and rwsnoop will be more responsive
  86         (increased switchrate).
  87 ------------------------------------------------------------------------------
  88 22-Sep-2005     Brendan Gregg   Version 0.84
  89         Some updates, fixed some bugs (cputimes, cpudists). Added cpuwalk.d.
  90 ------------------------------------------------------------------------------
  91 15-Nov-2005     Brendan Gregg   Sys Admin Magazine
  92         Ryan Matteson wrote an article on the DTraceToolkit which has been
  93         printed in Sys Admin Magazine, December 2005. It's quite good,
  94         and made it as the feature article - which means it will be available
  95         online for some time. Thanks Matty, and Sys Admin Magazine!
  96         "Observing I/O Behavior with the DTraceToolkit"
  97         http://www.samag.com/documents/sam0512a/
  98 ------------------------------------------------------------------------------
  99 01-Dec-2005     Brendan Gregg   Version 0.88
 100         Many scripts were updated. Added the Apps category. I had planned
 101         to add some key scripts, but they haven't made it out of testing yet.
 102 ------------------------------------------------------------------------------
 103 03-Dec-2005     Brendan Gregg   Version 0.89
 104         Added nfswisard.d, fixed a minor bug with tcp* tools (see
 105         dtrace-discuss mailing list).
 106 ------------------------------------------------------------------------------
 107 12-Jan-2006     Brendan Gregg   Version 0.92
 108         Added a few scripts including rwbytype.d. Fixed several issues.
 109 ------------------------------------------------------------------------------
 110 09-Apr-2006     Brendan Gregg   Solaris Internals 2nd Edition
 111         In the past few months I have been contributing to Solaris Internals
 112         2nd Edition. This book (now two volumes) is really amazing. The 2nd
 113         volume does use the DTraceToolkit where appropriate, and covers loads
 114         of useful topics. While writing and reviewing material for Solaris
 115         Internals, I've had numerous new ideas for DTrace scripts. Not only
 116         that, but a few people have managed to send me well styled, carefully
 117         tested, well considered DTrace scripts for inclusion in the toolkit.
 118 ------------------------------------------------------------------------------
 119 20-Apr-2006     Brendan Gregg   TCP bug fixed
 120         Stefan Parvu sent me a bug for the tcp* scripts: on build 31+ they
 121         error'd on the symbol SS_TCP_FAST_ACCEPT. This symbol was
 122         renamed to SS_DIRECT (I checked the code, they are used in the
 123         same way). Ironically, when I first wrote the scripts I had hardcoded
 124         the value 0x00200000, then rewrote it "properly" by importing
 125         the header files and using the symbol name. Had I been lazy and left
 126         it hardcoded, the bug would never have eventuated. Not to worry,
 127         it has returned to being hardcoded, so that it works on all builds
 128         (until something else changes).
 129 ------------------------------------------------------------------------------
 130 21-Apr-2006     Brendan Gregg   Restyled - again!
 131         I've been writing the "DTraceToolkit Style Guide", to document
 132         the style that these scripts obey. It is quite strict, and sets
 133         the bar fairly high. I've been warned that it may cause very few
 134         people to ever contribute scripts, which is fine. At some point
 135         I'll carefully explain the mentality behind this, but in a nutshell:
 136         Users on critical production servers expect the tools to be
 137         accurate, carefully tested, and cause no undocumented harm.
 138 ------------------------------------------------------------------------------
 139 22-Apr-2006     Brendan Gregg   Docs changes
 140         The "Contrib" file was merged into the "Who" file. In hindsight
 141         it is better to keep this data together than to split it up.
 142 ------------------------------------------------------------------------------
 143 24-Apr-2006     Brendan Gregg   Version 0.96
 144         The toolkit now contains 104 scripts, however I'll keep the version
 145         number < 1.00 until the dust has settled on these new scripts.
 146         There is some special significance with version 1.00, it would
 147         imply that every script had been tested for some time - not that
 148         I've just added a few.
 149         There is a new main directory, FS for file system related scripts.
 150         There are some interesting scripts in there, from or based on
 151         Solaris Internals 2nd ed, vol 2.
 152 ------------------------------------------------------------------------------
 153 30-Sep-2007     Brendan Gregg   Version 0.99
 154         It's been a year and a half since the last release, and a lot has
 155         happneed. Firstly, the DTraceToolkit has featured in the Prentice Hall
 156         book,
 157                 Solaris Performance and Tools
 158                    DTrace and mdb techniques for Solaris 10 and OpenSolaris
 159
 160         written by Richard McDougall, Jim Mauro and myself. It is a companion
 161         book to "Solaris Internals 2nd edition" by Richard McDougall and
 162         Jim Mauro. If you are serious about becomming a DTrace guru,
 163         especially on Solaris, then please study both books. (Yes, I realize
 164         that many people are using the DTraceToolkit because they don't have
 165         the time or don't want to become DTrace gurus; well, so long as
 166         you are using DTrace anyway :). The performance book was a great relief
 167         to write - since we were able to put to print much performance wisdom
 168         and knowledge that was begging to be documented.
 169
 170         Then, in late 2006 I joined an advanced products engineering team
 171         at Sun in San Francisco, a team which includes the three members of
 172         team DTrace. It's been a great opportunity to learn from such
 173         engineers, and to contribute more directly to DTrace. So far my work
 174         has included writing a JavaScript provider, integrated inet_ntoa()
 175         style functions into DTrace, and prototying DTrace IP, TCP and UDP
 176         providers.
 177
 178         Working on the network providers is good news for the DTraceToolkit,
 179         as it will indirectly help the tcp* scripts become more stable. Yes,
 180         those scripts have broken a few more times during the last 18 months,
 181         sorry about that, and it will keep happening until we have stable
 182         network providers. This is why I only ever wrote three tcp* scripts,
 183         and not at least a dozen, which I'd really like to do.
 184
 185         I did leave my pile of old SPARC and x86 development servers behind
 186         in Australia, and brought over a couple of laptops. That has made me
 187         more dependant on Stefan for testing the toolkit - especially on SPARC.
 188
 189         So, it's been about 18 months since the last release, which is
 190         mostly due to having less spare time due to moving countries and
 191         learning a new job.
 192
 193         Michelle from Sun docs has been asking for a newer version of the
 194         DTraceToolkit for the OpenSolaris starter kit, which is why I'm
 195         releasing this version now and not waiting a few more weeks as
 196         I complete bug fixes.
 197
 198         So the good and the bad news for this release, starting with the bad,
 199
 200         Bad: tcpsnoop/tcptop still don't work on some Solaris 10 releases.
 201         I've added versions that should work on Solaris Nevada and OpenSolaris
 202         for releases from around late 2007. They are likely to break again.
 203         The real answer, as always, is for stable nework providers to be
 204         integrated into Solaris.
 205
 206         Many of the exciting new language provider scripts in this release
 207         currently require downloading, patching and compling of the language
 208         interpreter to get working. See the Readme file in each directory
 209         for pointers.
 210
 211         Good: many more scripts to cover the new DTrace language providers
 212         that are available (the DTraceToolkit is now 227 scripts). Many
 213         updates to the Notes directory. Bug fixes. Some new categories
 214         other than for scripts: Code - for simple programs to DTrace (and
 215         for the example files), and Snippits - for useful lumps of DTrace
 216         code to copy-n-paste from. The man pages are also making room
 217         for documenting both stability and supported operating systems for
 218         each script - now that DTrace exists for MacOS X Leopard, the
 219         DTraceToolkit will begin supporting multiple operating systems.
 220
 221         This can be thought of as a developer's release of the DTraceToolkit -
 222         to help people start using DTrace with Perl, Python, Ruby, Php, Java,
 223         JavaScript, Shell and Tcl. I've written about 15 scripts for each
 224         language, to cover the basics and to show the way for deeper analysis.
 225         The scripts are also similar from one language to another, having
 226         devoleped a tried-and-tested group of scripts for analyzing real world
 227         issues - it made sense to repeat these scripts for every language
 228         possible. To see what I mean, try reading,
 229
 230            Examples/j_cputime_example.txt     Examples/py_cputime_example.txt
 231            Examples/js_cputime_example.txt    Examples/rb_cputime_example.txt
 232            Examples/php_cputime_example.txt   Examples/sh_cputime_example.txt
 233            Examples/pl_cputime_example.txt    Examples/tcl_cputime_example.txt
 234
 235         You might notice that the example files are more clearly and carefully
 236         explained. Claire (my wife), wrote close to one hundred of them for
 237         this release while I focused on writing and testing the scripts.
 238         Claire has worked as a SysAdmin and as an IT instructor, and is well
 239         skilled at explaining relavent technical details. And she can spell
 240         much better than I can. :)
 241
 242         The future: I still have many new scripts and some bug fixes in mind,
 243         as well as generally improving the Notes and Examples provided.
 244         Hopefully it won't be too many months before you see another
 245         release. Check here for the lastest installment,
 246
 247         http://www.opensolaris.org/os/community/dtrace/dtracetoolkit
 248 ------------------------------------------------------------------------------
 249