Wiki code for New Display Wizard

Hide Line numbers
1: == New Display Wizard  
2: 
3: Chime displays are described in XML (see [[Adding New Displays>>..]]), and a wizard is provided to generate that XML for you.  You can access the wizard from the menu (**File | New Display ...**) or directly from the command line with the {{code}}-W{{/code}} option.  Use the wizard to create new displays or edit existing ones.  
4: 
5: [[image:wizardmenuitem.gif||alt="Wizard Menu Access"]]  
6: 
7: Let’s say you want a display to monitor **system calls per second** made by each executable on the system.  The following walks you through the steps of creating such a display:  
8: 
9: ==== Walk-Through (System Calls Example)  
10: * [[Set Title and Output File>>#Set_Title_and_Output_File]]  
11: * [[Set DTrace Program>>#Set_DTrace_Program]]  
12: * [[Set Cleared Aggregations>>#Set_Cleared_Aggregations]]  
13: * [[Specify Columns>>#Specify_Columns]]  
14: ** [[First Unspecified Column>>#First_Unspecified_Column]]  
15: *** [[Specify Column Data>>#Specify_Column_Data]]  
16: *** [[Set Column Properties>>#Set_Column_Properties]]  
17: ** [[Next Unspecified Column>>#Next_Unspecified_Column]]    
18: ** [[Aggregation Value Column>>#Aggregation_Value_Column]]  
19: * [[Test Run the Display>>#Test_Run_the_Display]]  
20: * [[Provide a Description>>#Provide_a_Description]]  
21: * [[Finish Creating the Display>>#Finish_Creating_the_Display]]  
22: * [[Add Drilldown>>#Add_Drilldown]]
23: 
24: === Set Title and Output File  
25: 
26: When the wizard appears, you will see the default title "Display" highlighted in the **Title** field.  
27: 
28: ![Wizard Initial Screen](screens_a/wizard_title_init.gif)  
29: 
30: Type "System Calls" and press {{code}}Enter{{/code}} to proceed to the next step.  
31:   
32: [[image:wizardtitle.gif||alt="Wizard Set Title Step"]]  
33: 
34: === Set DTrace Program  
35: 
36: Click in the text pane under the **Program String** radio button and enter
37: the following DTrace program:  
38: 
39: [[image:wizardprogram.gif||alt="Wizard Set Program Step"]]  
40: 
41: You can click the **Check Compile** button to make sure you typed the program correctly.  If there is a syntax error, you will see a red ’X’ instead of a green check mark, and there will be a hyperlink to view details about the error.  For help adapting DTrace programs to Chime, click on the **Help** button.  To learn about writing DTrace programs with aggregations displayable in Chime, a good place to start is the [[Aggregations>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidlh7?q=trunc&a=view]] chapter of the //Solaris Dynamic Tracing Guide//.  
42: 
43: Press {{code}}Alt-N{{/code}} (or click the **Next** button) to proceed to the next step:  
44: 
45: === Set Cleared Aggregations  
46: 
47: In this step you specify whether or not you want running totals.  By default, Chime clears all aggregations, resetting their values to zero, each time it gets the latest snapshot of aggregate data.  Since we want to display system calls per second, the default behavior (no running totals) is the right choice.  Simply proceed to the next step.  
48: 
49: Note that if your program included other aggregations, they would show up here, each with its own check box.  For example, if your program included the statement {{code}}@counts[execname] = count();{{/code}} then "counts" would also appear in the  list of individually clearable aggregations.  
50: 
51: [[image:wizardaggs.gif||alt="Wizard Clear Aggregations Step"]]  
52: 
53: === Specify Columns  
54: 
55: Here we list all the columns by name as they will appear in the display’s column header from left to right.  It helps to picture the table you want to display.  In this case, we want a display similar to the "System Calls" display installed with Chime:  
56: 
57: ![System Calls](screens_d/syscalls.gif)  
58: 
59: * An "Executable" column, right aligned  
60: * A "History" column with a sparkline  
61: * A renamed "Calls Per Second" column, left aligned  
62: 
63: The basic idea is to include one column for each element of the aggregation key followed by a column for the aggregation values.  Since we are aggregating {{code}}@[execname] = count();{{/code}} we need one column for the {{code}}execname{{/code}} key followed by one column for the {{code}}count(){{/code}} values.  If we were instead aggregating {{code}}@[execname, probefunc] = count();{{/code}} we would need two key columns, one for {{code}}execname{{/code}} and one for {{code}}probefunc{{/code}}, followed by one value column for {{code}}count(){{/code}}.  In this case, we only need two columns: "Executable" for the {{code}}execname{{/code}} key and "Calls Per Second" for the {{code}}count(){{/code}} values.  However, we insert an additional "History" column to provide a sparkline view of the data in the "Calls Per Second" column over time.  
64: 
65: [[image:wizardcols.gif||alt="Wizard Specify Columns Step"]]  
66: 
67: Type "Executable" and press {{code}}Enter{{/code}} to add a new empty row.  Type "History" and press {{code}}Enter{{/code}} again.  When you finish typing "Calls Per Second" (with or without pressing {{code}}Enter{{/code}}) you can click **Next** to proceed to the next step.  
68: 
69: === First Unspecified Column  
70: ==== Specify Column Data  
71: 
72: Here we specify the first unspecified column, "Executable".  To start, we simply need to indicate whether the column displays an aggregation key (such as {{code}}execname{{/code}} in {{code}}@[execname] = count();{{/code}}) or an aggregation value (such as {{code}}count(){{/code}} in {{code}}@[execname] = count();{{/code}}).  A third type of column, the **Alternate View** (see below) is special: it takes source data from another column (or columns) and presents that data differently.  The "History" column is an example of an alternate view.  
73: 
74: ![Specify Executable Column Data](screens_a/wizard_col_1a.gif)  
75: 
76: In this case our job is easy.  The screen already indicates **Tuple Member** (a member of an aggregation key) with **Tuple Index** 0 (the first element in square brackets).  That corresponds to {{code}}execname{{/code}} in {{code}}@[execname] = count();{{/code}} exactly what we intend.  Simply click **Next**.  
77: 
78: ==== Set Column Properties  
79: 
80: This step allows us to set properties appropriate for a column that displays part of an aggregation key.
81: 
82: ![Specify Executable Column Data](screens_a/wizard_col_1b.gif)  
83: 
84: As before, we could simply click **Next**.  However, a totals row would be nice, and it’s not much trouble.  Choose "Count" from the **Total** pulldown and specify the singular and plural forms of the units label.  Type "executable" in the **Singular Total Label** field.  What you type is echoed in the **Plural Total Label** field, so all you need to do is press {{code}}Tab{{/code}} followed by {{code}}s{{/code}} to complete the plural form.  If, instead of {{code}}@[execname] = count();{{/code}} we were aggregating {{code}}@[execname, probefunc] = count();{{/code}}, then the "Executable" values would repeat within the column, so we would need to choose "Unique Count" rather than "Count" to display the number of unique executables.  
85: 
86: We also want to right-align the executable names so they are easier to associate visually with their {{code}}count(){{/code}} values in the columns to the right.  Choose "right" from the **Alignment** pulldown.  
87: 
88: Now click **Next**.  
89: 
90: === Next Unspecified Column  
91: 
92: Now we repeat steps **4a. Specify Column Data** and **4b. Set Column Properties** for the "History" column.  The green check at the top of the screen indicates that we have successfully specified the previous "Executable" column.  
93: 
94: ![Specify History Column Data](screens_a/wizard_col_2a.gif)  
95: 
96: This time, the screen initially indicates **Tuple Member** with a **Tuple Index** of 1 (auto-incremented from the tuple index of the previous "Executable" column).  This does not correctly indicate the purpose of the "History" column.  Choose "Calls Per Second" from the **Source Columns** pulldown.  This automatically selects the **Alternate View** radio button.  
97: 
98: Click **Next**.  
99: 
100: ![Set History Column Properties](screens_a/wizard_col_2b.gif)  
101: 
102: **Sparkline** is already selected.  The "History" column will present an alternate view (over time) of the {{code}}count(){{/code}} data from the "Calls Per Second" column using a sparkline graph (see Edward Tufte’s [[Sparklines>>http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR&topic_id=1]] page.)  
103: 
104: Click **Next** and proceed to the last unspecified column.  
105: 
106: === Aggregation Value Column  
107: 
108: The last column, "Calls Per Second", displays the values of the {{code}}count(){{/code}} aggregating action.  As before, the initial selection in this screen is **Tuple Member**, which we need to change, since this column does not display part of the aggregation key.  
109: 
110: ![Specify Calls Per Second Column Data](screens_b/wizard_col_3a.gif)  
111: 
112: Select **Aggregation Value** and leave the **Aggregation Name** field empty since the aggregation in our DTrace program is unnamed: {{code}}@[execname] = count();{{/code}} ({{code}}@{{/code}} is the anonymous aggregation).  
113: 
114: Click **Next**.  
115: 
116: Columns that display aggregation values have more properties to specify than columns that display aggregation keys:  
117: 
118: ![Set Calls Per Second Column Properties](screens_b/wizard_col_3b.gif)  
119: 
120: Check **Value Per Second**.  
121: Choose "left" in the **Alignment** pulldown.  
122: Choose "#,==0" in the **Format** pulldown, indicating thousands separators.  
123: 
124: Scroll down ...  
125: 
126: ![Scroll Down Calls Per Second Properties](screens_b/wizard_col_3b_scroll.gif)  
127: 
128: Choose "Sum" from the **Total** pulldown.  
129: 
130: Click **Next**.  
131: 
132: Once all the columns have been specified, we return to step **4. Specify Columns** to confirm the intended list of columns before moving on.  
133: 
134: ![Confirm Columns](screens_b/wizard_cols_confirm.gif)  
135: 
136: The green check marks indicate which columns have been specified (all of them).  Again, the columns are listed in the order they will appear from left to right in the display.  We also see some new indicators: "[0]" after "Executable" is like an array index indicating that the column displays the first member of the aggregation key.  "( Calls Per Second )" indicates that the "History" column presents an alternate view of data from the "Calls Per Second" column.  "@" indicates that the "Calls Per Second" column displays aggregation values from the anonymous aggregation.  If the aggregation had instead been named {{code}}@counts{{/code}} in our DTrace program, we would see "@counts" here instead.  
137: 
138: If you want to make any corrections, you can select any of the listed column names and click the **Specify >** button to redo steps **4a** and **4b** for that column, or click **Specify >>** to redo only step **4b**.  Afterwards you will again return to the column list (above) to confirm your specifications before moving on.   
139: 
140: Click **Next**.  
141: 
142: === Test Run the Display  
143: 
144: Having all the columns specified, we could have clicked **Finish** instead, but why not test the display first to see if does what we intended?  This step lets us do just that:  
145: 
146: ![Test Run the Display](screens_b/wizard_testrun.gif)  
147: 
148: Click the **Run Display** button.  Another window will appear with a display that should look something like this:  
149: 
150: ![Resulting Display](screens_c/wizard_display.gif)  
151: 
152: By default, the display is sorted in ascending order by the aggregation key.  Click on the "Calls Per Second" column header to sort by value descending.  How you set the sort during the test run determines the initial sort of the created display.  We could also change the initial window size, but the default seems like a good size.  
153: 
154: If you find that you need to make some corrections, click on the **Back** button to revisit any of the previous steps.  You can leave the test display running so that it is available for side-by-side comparison when you return to this screen for an updated test run.  
155: 
156: This test display improves on the installed "System Calls" display by adding a totals row and a better initial sort.  You can close it and click **Next** in the wizard to provide a description.  
157: 
158: === Provide a Description  
159: 
160: Whatever text you enter to describe the display appears in the **Description** pane in the main Chime window when the new display is selected in the **Traces** list.  You can use HTML to specify things like bold, italic, underline, font, and numbered or bulleted lists.  
161: 
162: ![Wizard Provide a Description Step](screens_c/wizard_desc.gif)  
163: 
164: Above is a fancifully obtuse description that serves to illustrate the formatting possibilities just listed (although the point about the cyan scale indicator might actually be helpful).  Here is the resulting description as it will appear when the display is selected in the main Chime window:  
165: 
166: ![Resulting Description](screens_c/wizard_desc_result.gif)  
167: 
168: Click **Next**.
169: 
170: === Finish Creating the Display  
171: 
172: The next step adds drilldown support.  It is evidently disabled, and the explanatory paragraph is intended to make clear that our DTrace program is not written in the way required to support drilldown.  
173: 
174: ![Wizard Drilldown Disabled](screens_c/wizard_drilldown_disabled.gif)  
175: 
176: We could use the **Back** button to remedy this, but that’s a long way to back up, so it’s probably easier to finish what we have and reopen it later at step 1, only one step away from our DTrace program.  
177: 
178: Click **Finish**.  You should see the following console output:  
179: 
180: {{{
181:     Wrote /opt/OSOL0chime/displays/new/system~_calls.xml
182:     To run, enter "/opt/OSOL0chime/bin/chime -C /opt/OSOL0chime/displays/new/system~_calls.xml".  
183: }}}
184: 
185: Besides running the display directly from the command line, you can also load newly created displays from the **Trace Group** pulldown of the main Chime window:  
186: 
187: ![Load New Displays](screens_c/load_new_displays.gif)  
188: 
189: New displays are put in {{code}}/opt/OSOL0chime/displays/new{{/code}} by default, where they are accessed by the menu item pictured above.  If this is the first time you have created a new display, congratulations!  You will see the following list with your one new display:  
190: 
191: ![New Displays](screens_d/new_displays.gif)  
192: 
193: You can move the {{code}}.xml{{/code}} descriptions to {{code}}/opt/OSOL0chime/displays{{/code}} or another of its subdirectories later as you find out which new displays are useful.  In that case, if you specified the DTrace program as a file with a relative pathname, you may need to update that pathname relative to the new location.  
194: 
195: === Add Drilldown
196: 
197: Drilldown lets you answer questions about values of interest. For example, for a selected executable you could get a breakdown of its system calls by function. Click [[here>>drilldown]] to continue this walk-through by adding drilldown to your new display.
OpenSolaris

Top Menu

Wiki code for New Display Wizard

Search

Collectives

Community Group

Project

User Group

Subsites

Project dtrace-chime Pages
