OpenSolaris

1. Project: Chime Visualization Tool for DTrace
   1. Installation
   2. Change Log
      1. Known Issues
   3. Displays
   4. Adding New Displays
      1. New Display Wizard
         1. Adding Drilldown
      2. Command Line
      3. XML Properties
   5. Java DTrace API
      1. jdtrace Example
   6. Blogs
   7. Announcements
   8. Discussions
   9. Leaders
   10. Observers
   11. Articles

Adding Drilldown to an Existing Chime Display

This page continues the walk-through started in the New Display Wizard page and adds drilldown to the "System Calls" display created there. The following assumes that you have gone through those steps to create the display and are now ready to add drilldown.

Once again, it helps to have a picture in your mind of what you want to see. Look at the display just created:

Let's say you want to replace the "Executable" column with a "Function" column, so that someone could, for example, select "Xorg" and get a breakdown of Xorg system calls by function.

Notice that only the "Executable" column is replaced. The "History" and "Calls Per Second" columns are unchanged. When you specify a drilldown option, Chime assumes that you will be replacing all columns associated with the aggregation key of the previous display with one or more new key columns.

First, open the wizard by clicking the toolbar button in the main Chime window (the first button on the left under the File menu):

When the wizard appears, click the Browse ... button in the top right corner of the window after Modify Existing Display, then open "system_calls.xml" (the one you just created) in the file chooser that appears. This will populate the Title and Output fields automatically:

Click Next.

In step 2. Set DTrace Program we can insert the substitution variables required to support drilldown. If you remember, the message in the (disabled) Add Drilldown Support screen referred us back to this step:

Drilldown support requires that your DTrace program use the tuple substitution variable and one or more predicate substitution variables. If you want to add drilldown menu items, first go back to the Set DTrace Program step and use right-click popup menus in the Program tab to insert tuple and predicate placeholders.

Using the recommended right-click popup makes this easier. Highlight the aggregation key "execname" inside the square brackets, right click on it, and select Insert Tuple Variable from the popup menu.

This replaces "execname" with the special substitution variable ??T?? and sets "execname" as the default value for the first element (T0) of the aggregation key.

Next, click after "syscall:::entry" and press Enter to insert a blank row before the open curly brace. Right click in the blank row and select Insert Predicate Variable from the popup menu.

This inserts the special substitution variable ??P0?? as a placeholder for the first predicate and sets the default initial value to no predicate (blank after ??P0).

To specify a non-blank predicate, such as / pid == $pid /, you would add it without the enclosing forward slashes:

??P0 pid == $pid

As before, you can click the Check Compile button to make sure you inserted the substitution variables correctly. Note that the ?? syntax is not understood by the DTrace compiler, so Chime performs substitution before compiling. When your program looks like the one pictured above, click Next.

Steps 3 through 6 are already specified and do not need to be repeated. Skip them by clicking Next until you reach step 7. Add Drilldown Support:

Right click on the root of the empty decision tree labeled "Menu Items" and select Add Menu Item from the popup menu.

This adds an <unspecified> entry preceded by a red "X". Select that entry to open the Columns specifier in the right pane. Enter "Function" as shown above to label the new column header, then click Next.

The "Function" column will replace the "Executable" column to display system call counts by function for one or more selected executables. This screen anticipates what we want. The "Function" column will display the first (and only) element of the new aggregation key, [probefunc], exactly what the wizard already specifies: TupleMember is selected, and Tuple Index is 0. Simply click Next.

Here we must specify the element of the aggregation key displayed in this column. Select "probefunc" from the Tuple Member pulldown. Below that are optional column properties.

Choose "right" in the Alignment pulldown.
Choose "Count" in the Total pulldown.
Enter "function" in the Singular Total Label field. What you type is echoed in the Plural Total Label field, so to finish all you need to do is press the Tab key (tab into the next field) then press the 's' key.
Click Next.

Once all the new columns are specified (in this case there is only one new column; replacing the aggregation key leaves the "History" and "Calls Per Second" columns unchanged), the wizard returns to the Columns table to confirm the intended columns. Click Finish.

Congratulations! You have just added drilldown to your new display. To run it, select "New Displays" from the Trace Group pulldown in the main Chime window, then double-click "System Calls" in the Traces list.

Your new display looks the same as before, but it has a new right-click menu item:

Let's try it out. Right-click "Xorg" and select Xorg by Function from the popup menu. The drilldown display replaces the Executable column with the new Function column and adds "Xorg" to the title bar. (You could also select multiple executables, and they would instead be listed in a subtitle.)

Notice that the new breakdown by function lacks a drilldown item in its popup menu, because we did not specify one (although we could have).

Next, select Display DTrace Program from the right-click popup menu of both displays and compare their programs side by side:

You can see how the placeholders you inserted in your program earlier actually work: "execname" in square brackets is replaced with "probefunc", and the predicate / execname == "Xorg" / is inserted before the open curly brace.

The predicate can grow to support multiple levels of drilldown. For example, the "System Calls" display that comes installed with Chime has multiple levels of drilldown. To see what that looks like, simply open the installed display "syscall.xml" with the wizard (this is a good way to see how almost any feature of an installed display is specified in the wizard whenever you want to do something similar).

In the wizard step 1. Set Title and Output File, click on the Browse ... button in the upper right corner after the Modify Existing Display field. The file chooser initially shows all displays in the "New Displays" group. To see the installed displays, just go up one level in the file system.

Click the first button at the top with the up arrow on the file folder (the actual icon may differ depending on the Look & Feel you specified in the Chime Options menu).

Select "syscall.xml" and click Open. Click Next in the wizard until you get to step 7. Add Drilldown Support.

This is an example of a more complex decision tree with multiple levels of drilldown, and you can run it by selecting "Initial Displays" from the Trace Group pulldown in the main Chime window and double-clicking the installed "System Calls" display in the Traces list.

Try it yourself! Drilldown is a powerful feature that makes your display more dynamic, more able to answer the questions it provokes. Since your display will be more useful, you might also take the time to share it. Chime is designed to make sharing displays easy, and your displays are welcome on the project page.