Feel free to comment on CommandsListDraftComments. You might also want to see SampleProgram created with this proposed API.
Known limitations:
- does not support claiming annonymous state
- is not 100% event loop friendly - you have to frequently schedule ::dtrace::process on your own
Commands
::dtrace::open ?-option value -option value...? ?instrument?
Returns: handle. Opens DTrace. If everything went OK, then handle gets returned. If instrument is 0, then no instrumentation will be possible. This can be useful if all you want to do is just check whether your scripts compile well. You may also pass some options for initial configuration. See the ::dtrace::configure call below for the options.
Side note: the name 'open' is derived from the fact, that it internally opens /dev/dtrace/ devices.
::dtrace::close handle
Closes DTrace. Tidies up. If you forget to do it, it will be fired automatically on Tcl exit. Calling this explicitly when your program is running may come handy if you want to release resources - this is the only way to free claimed memory.
::dtrace::configure handle
::dtrace::configure handle option
::dtrace::configure handle option value ?option value ...?
If no options are supplied, the command returns a list containing alternating option names and values. If option is supplied but no value then the command returns the current value of the given option. If one or more pairs of option and value are supplied, the command sets each of the named options to the corresponding value; in this case the return value is an empty string.
For binary options you can use the values 1 and 0. For complete options list consider http://dev.lrem.net/tcldtrace/wiki/LibDtrace#Options - note that you can use every option of the underlaying libdtrace api, just prepend it with a '-'.
List of basic options (these get returned in the alternating list by the first type of invocation):
| name | type | explanation |
| -flowindent | 1/0 | Makes libdtrace handle flow indenting. |
| -quiet | 1/0 | Sets quiet mode. |
| -bufsize | integer | Sets the buffer size. |
| -libdir | string | Set path for DTrace libraries. |
| -foldpdesc | 1/0 | Whether probe descriptions should be folded into a string (on 1), or given as an alternating list (on 0). See CommandsList#Callbacks. This is TclDTrace specific and defaults to 1. |
| -arch | string | SPECIFIC TO MAC OSX. The target architecture, possible values i386/x86_64/ppc/ppc64. This should be given during initial configuration (see ::dtrace::open). |
Libdtrace options may also be changed from within the scripts using #pragma directive. Lear more: http://docs.sun.com/app/docs/doc/817-6223/chp-opt?l=en&q=pragma&a=view
::dtrace::grab handle pid
Grabs the process identified by pid. If it's a first call to ::dtrace::grab, then the $target macro will be set to pid. You should run ::dtrace::go quickly, as it's the command to continue the grabbed processes.
::dtrace::launch handle cmd
This creates a grabbed process by executing cmd and grabbing it immediately. Unlike a call to Tcl's exec and then ::dtrace::grab, this does not create race conditions. Like in ::dtrace::grab, process is continued on ::dtrace::go.
::dtrace::compile handle program ?argument0 argument1 ...?
Returns compiled program. It should be in the same form that you give to dtrace(1) -n (that is: [[[provider:] module:] function:] name [[predicate] action] according to the man page, note that provider, module, function and name can be left blank to match all strings, and globbing can be used with '*' to match any part of a string). You can pass additional string argument to the program. Returns a handle to the compiled program if successful.
::dtrace::exec compiled_program
Executes the compiled_program (enables instrumentation points). This might be called multiple times, all the programs get running (generating data for processing) after ::dtrace::go. Returns an alternating name/value list of program info:
| name | type | explanation |
| aggregates | int | the number of aggregates associated with this program |
| recgens | int | the number of record generating probes associated with this program |
| matches | int | the number of probes matched by this program |
| speculations | int | the number of speculations specified by this program |
::dtrace::info compiled_program
Returns an alternating name/value list of program info for the compiled_program (this is the same as previous call, but it doesn't enable the instrumentation - can be used for handles with instrument set to 0):
| name | type | explanation |
| aggregates | int | the number of aggregates associated with this program |
| recgens | int | the number of record generating probes associated with this |
| matches | int | the number of probes matched by this program |
| speculations | int | the number of speculations specified by this program |
::dtrace::go handle ?callback {proc ?arg?} ...?
Enables tracing. This is more or less equal to actually running the executed programs - without it you will not get any data from them. Furthermore this command continues the grabbed processes.
It also registers callbacks. For each callback you need to specify a list containing the callback proc name and possible additional argument. Learn more about callbacks at CommandsList#Callbacks. Possible callbacks names are:
- probe_desc
- probe_output
- drop
- error
- proc
::dtrace::stop handle
Stops things ticking.
::dtrace::process handle ?sleep?
If sleep is set to 1 sleeps a while. Wakes up if something interesting happens. Note this is not necessary to use this kind of sleeping - event loop will do. But, at the moment manually, you need to schedule ::dtrace::process frequently to avoid dropping (buffer holds around 60K records), or even DTrace aborting (after 30secs without a call to dtrace_work). This should change in future versions.
This command triggers processing data accumulated in the buffer. For each record a relevant callback is called.
::dtrace::aggregations handle
Returns a list containing alternating tuple - value pairs. Tuples are what is found in script between [ and ]. In this list, each tuple is represented by a simple list, whose members are the tuple members, divided by ',' i D code. Values are simple numerics. ::dtrace::aggregations output can (and should) be interpreted as a dict (see http://www.tcl.tk/man/tcl8.5/TclCmd/dict.htm)
::dtrace::list compiled_program list_callback arg
For each of the probes matched by the compiled_program runs the list_callback.
Callbacks
list_callback probe arg
This simply gives us a probe description. If -foldpdesc is set to 1, this is a single string. It's format is [[[provider:] module:] function:] name [[predicate] action] according to the man page, note that provider, module, function and name can be left blank to match all strings, and globbing can be used with '*' to match any part of a string. If -foldpdesc is set to 0, this is an alternating list containing:
| name | type | explanation |
| id | int | the numerical probe id |
| provider | string | the provider |
| module | string | the module |
| function | string | the function |
| name | string | the name |
probe_desc probe cpu id arg
This is called for each firing probe.
Meaning of the arguments:
| name | explanation |
| probe | the probe description string (see list_callback) |
| cpu | on which cpu did the probe fire |
| id | the probe id number |
| arg | extra argument, empty string if none |
probe_output probe cpu id arg type data
This is called for each probe that did some output. That may be just a trace, printfed string or a stack. At this moment the output is given directly as the string given by libdtrace, it's your thing to parse it.
Meaning of the arguments:
| name | explanation |
| probe | the probe description string (see list_callback) |
| cpu | on which cpu did the probe fire |
| id | the probe id number |
| arg | extra argument, empty string if none |
| type | the output type (see LibDtrace#Bufferedoutput), without the 'DTRACEACT_' prefix |
| data | the actual output data |
Some most interesting output types are:
| name | explanation |
| USTACK | result of ustack() |
| JSTACK | result of jstack() |
| STACK | result of stack() |
| PRINTF | result of printf() |
drop cpu kind count message arg
Meaning of the arguments:
| name | explanation |
| cpu | on which cpu did the drop occur |
| kind | what kind of drop it is (see below) |
| messge | message preconstructed for you by libdtrace |
| arg | extra argument, empty string if none |
Kind is a string meaning:
| value | meaning |
| AGGREGATION | drop to aggregation buffer |
| DYNAMIC | dynamic drop |
| DYNRINSE | dyn drop due to rinsing |
| DYNDIRTY | dyn drop due to dirty |
| SPEC | speculative drop |
| SPECBUSY | spec drop due to busy |
| SPECUNAVAIL | spec drop due to unavail |
| STKSTROVERFLOW | stack string tab overflow |
| DBLERROR | error in ERROR probe |
error probe cpu message arg
Meaning of the arguments:
| name | explanation |
| probe | the probe description string (see list_callback) |
| cpu | on which cpu did the probe fire |
| message | message preconstructed for you by libdtrace |
| arg | extra argument, empty string if none |
proc pid message arg
Meaning of the arguments:
| name | explanation |
| pid | pid of the process the message is about |
| messge | message preconstructed for you by libdtrace |
| arg | extra argument, empty string if none |
