1History - History of the DTraceToolkit 2 3------------------------------------------------------------------------------ 420-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------------------------------------------------------------------------------ 1315-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------------------------------------------------------------------------------ 2416-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------------------------------------------------------------------------------ 3717-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------------------------------------------------------------------------------ 4208-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------------------------------------------------------------------------------ 4808-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------------------------------------------------------------------------------ 5209-Jun-2005 Brendan Gregg Version 0.42 53 Added 7 more scripts. 54------------------------------------------------------------------------------ 5514-Jun-2005 Brendan Gregg Version 0.57 56 Added heaps of new scripts. Now at 57 scripts. 57------------------------------------------------------------------------------ 5817-Jun-2005 Brendan Gregg Version 0.61 59 Restyled many commands. 60------------------------------------------------------------------------------ 6128-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------------------------------------------------------------------------------ 6725-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------------------------------------------------------------------------------ 8026-Jul-2005 Brendan Gregg Version 0.82 81 Many new scripts added, many updates. This is a major release. 82------------------------------------------------------------------------------ 8317-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------------------------------------------------------------------------------ 8822-Sep-2005 Brendan Gregg Version 0.84 89 Some updates, fixed some bugs (cputimes, cpudists). Added cpuwalk.d. 90------------------------------------------------------------------------------ 9115-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------------------------------------------------------------------------------ 9901-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------------------------------------------------------------------------------ 10303-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------------------------------------------------------------------------------ 10712-Jan-2006 Brendan Gregg Version 0.92 108 Added a few scripts including rwbytype.d. Fixed several issues. 109------------------------------------------------------------------------------ 11009-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------------------------------------------------------------------------------ 11920-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------------------------------------------------------------------------------ 13021-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------------------------------------------------------------------------------ 13922-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------------------------------------------------------------------------------ 14324-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------------------------------------------------------------------------------ 15330-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 250