This chapter is from the book
This chapter is from the book
This chapter is from the book
Custom Instruments
Some of the instruments included in Instruments consist of code specially written for the task. Most involve no code at all. They are made from editable templates. You can examine these instruments yourself—which may be the only way to get authoritative details on what an instrument does—and you can create instruments of your own.
Let's see what a scripted instrument looks like. Create a trace document from the File Activity template, select the Reads / Writes instrument, and then Instrument > Edit 'Reads/Writes' Instrument... (or simply double-click the instrument's label). An editing sheet (see Figure 26.9) will appear, with fields for the instrument's name, category, and description, and a long scrolling list of probes, handlers for events the instrument is meant to capture.
)
Figure 26.9 The Edit Instrument sheet for the Reads / Writes instrument. The sheet is dominated by an editable list of events the instrument is to capture. The portion that specifies how to record entries to the system write function is shown here.
Figure 26.9 shows the event list scrolled to the condition called Write, in the domain System Call, for the symbol write. It is to trigger when write is entered. Next comes the text of a script to be executed when the probe is triggered. Instruments uses the DTrace kernel facility, which has its own scripting language; for instance, this event might put the time at which the event occurred into an instance variable of the probe, so that a write-exit probe could calculate the duration of the call and record it. In this case, the scripting text is blank.
Then comes a series of items specifying what information is to be kept, for the trace graph or for the Detail view. In the case of Reads / Writes, this is
- The name of the executable
- The name of the function
- The first argument (the file descriptor), which is an integer to be labeled FD
- The third argument (the size of the write), which is an integer to be labeled Byte
- A string, to be labeled Path, calculated from an expression in the Instruments scripting language: A path, derived from the file descriptor within the executable.
Integer-valued records are included in the configuration inspector's list of Statistics to Graph, and are eligible to display in the instrument's trace. This accounts for the odd presence of Thread ID (which is automatically captured in every case) in the list of available plots. By default, the Stack Depth statistic is selected.
The customization sheet is a front end for the scripting language for the kernel-provided DTrace service; only kernel-level code is capable of detecting call events in every process. The section "Creating Custom Instruments with DTrace," in the Instruments User Guide, offers enough of an introduction to the language to get you started on your own instruments.
To make your own instrument, start with Instrument > Build New Instrument... (
B). An instrument-editing sheet will drop from the front trace document, and you can proceed from there.
If you become a DTrace expert, you might find it more convenient, or more flexible, to write your scripts directly, without going through the customization sheet. Select File > DTrace Script Export... to save a script covering every instrument in the current document, and File > DTrace Data Import... to load a custom script in. You can export DTrace scripts only from documents that contain DTrace instruments exclusively.
The stack trace in the Extended Detail view provides another way to create a custom instrument. Select one of the function frames in the listing and then Trace Call Duration from the stack trace's Action (
) menu. Instruments will add a custom instrument to the current document that triggers on entry and exit, to record how long it took to execute the function.