Wiki code for Adding Drilldown

Hide Line numbers
1: == Adding Drilldown to an Existing Chime Display
2: 
3: This page continues the walk-through started in the [[New Display Wizard>>Project dtrace-chime.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.  
4: 
5: Once again, it helps to have a picture in your mind of what you want to see. Look at the display just created:
6: 
7: ![New "System Calls" Display](../screens_c/wizard_display.gif)  
8: 
9: 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.  
10: 
11: ![Drilldown by Function](../screens_h/syscalls_drilldown.gif)  
12: 
13: 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.  
14: 
15: First, open the wizard by clicking the ![New Display Wizard Icon](../screens_g/New16.gif) toolbar button in the main Chime window (the first button on the left under the **File** menu):  
16: 
17: ![Main Chime Window](../screens_c/wizard_desc_result.gif)  
18: 
19: 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:  
20: 
21: ![Wizard Modify Existing "System Calls" Display](../screens_g/wizard_modify_existing.gif)  
22: 
23: Click **Next**.  
24:   
25: 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**>>../screens_c/wizard_drilldown_disabled.gif]] screen referred us back to this step:
26: 
27: > 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.
28: 
29: 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.  
30: 
31: ![Wizard Drilldown Program Tuple](../screens_d/wizard_drilldown_tuple.gif)  
32: 
33: This replaces "execname" with the special substitution variable {{code}}??T??{{/code}} and sets "execname" as the default value for the first element (T0) of the aggregation key.  
34: 
35: ![Wizard Drilldown Finished Program Tuple](../screens_d/wizard_drilldown_tuple_done.gif)  
36: 
37: Next, click after "syscall:::entry" and press {{code}}Enter{{/code}} 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.  
38: 
39: ![Wizard Drilldown Program Predicate](../screens_d/wizard_drilldown_predicate.gif)  
40: 
41: This inserts the special substitution variable {{code}}??P0??{{/code}} as a placeholder for the first predicate and sets the default initial value to //no predicate// (blank after {{code}}??P0{{/code}}).  
42: 
43: ![Wizard Drilldown Finished Program Predicate](../screens_e/wizard_drilldown_predicate_done.gif)  
44: 
45: To specify a non-blank predicate, such as {{code}}/ pid == $pid /{{/code}}, you would add it without the enclosing forward slashes:
46: 
47: > ??P0 pid == $pid
48: 
49: As before, you can click the **Check Compile** button to make sure you inserted the substitution variables correctly. Note that the {{code}}??{{/code}} 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**.  
50: 
51: 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**:  
52: 
53: ![Wizard Drilldown Add Menu Item](../screens_e/wizard_drilldown_add_menu_item.gif)  
54: 
55: Right click on the root of the empty decision tree labeled "Menu Items" and select **Add Menu Item** from the popup menu.  
56: 
57: ![Wizard Drilldown Specify Columns](../screens_e/wizard_drilldown_columns.gif)  
58: 
59: This adds an {{code}}<unspecified>{{/code}} 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**.  
60: 
61: ![Wizard Drilldown Specify Column Data](../screens_e/wizard_drilldown_col_1a.gif)  
62: 
63: 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**.  
64: 
65: ![Wizard Drilldown Set Column Properties](../screens_e/wizard_drilldown_col_1b.gif)  
66: 
67: 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.  
68: 
69: Choose "right" in the **Alignment** pulldown.  
70: Choose "Count" in the **Total** pulldown.  
71: 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 {{code}}Tab{{/code}} key (tab into the next field) then press the ’s’ key.  
72: Click **Next**.  
73: 
74: ![Wizard Drilldown Confirm Columns](../screens_f/wizard_drilldown_cols_confirm.gif)  
75: 
76: 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**.  
77: 
78: 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.
79: 
80: ![Main Chime Window](../screens_d/new_displays.gif)  
81: 
82: Your new display looks the same as before, but it has a new right-click menu item:  
83: 
84: ![System Calls Initial Display](../screens_f/wizard_drilldown_result_a.gif)  
85: 
86: 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.)  
87: 
88: ![System Calls Drilldown Display](../screens_f/wizard_drilldown_result_b.gif)  
89: 
90: 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).  
91: 
92: Next, select **Display DTrace Program** from the right-click popup menu of both displays and compare their programs side by side:  
93: 
94: ![System Calls Initial Program](../screens_f/wizard_drilldown_prog_a.gif)  
95: 
96: 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.  
97: 
98: ![System Calls Drilldown Program](../screens_f/wizard_drilldown_prog_b.gif)  
99: 
100: 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).  
101: 
102: 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.
103: 
104: ![Wizard Modify Initial Displays](../screens_g/wizard_drilldown_up.gif)  
105: 
106: 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).  
107: 
108: ![Wizard Modify Existing Display](../screens_g/wizard_drilldown_syscalls.gif)  
109: 
110: Select "syscall.xml" and click **Open**. Click **Next** in the wizard until you get to step **7. Add Drilldown Support**.  
111: 
112: ![System Calls Drilldown Menu](../screens_g/wizard_drilldown_syscalls_menu.gif)  
113: 
114: 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.  
115: 
116: 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>>Project dtrace-chime.displays]] it. Chime is designed to make sharing displays easy, and your displays are welcome on the project page.
OpenSolaris

Top Menu

Wiki code for Adding Drilldown

Search

Collectives

Community Group

Project

User Group

Subsites

Project dtrace-chime Pages
