Wiki code for XML Properties

Hide Line numbers
1: == XML Properties
2: 
3: Each Chime display is described in XML as a set of properties recognized by Chime. Chime provides a [[wizard>>Project dtrace-chime.wizard]] as well as [[command line options>>Project dtrace-chime.cmdgen]] to generate the XML for you, but this page is included in case you need to specify something not supported by the wizard, and also to provide documentation for developers.
4: 
5: === Contents
6: * [[Display Description Files>>#Display_Description_Files]]
7: * [[Property Documentation Format>>#Property_Documentation_Format]]
8: * [[Display Description>>#Display_Description]]
9: ** [[version>>#Version]]
10: ** [[title>>#Title]]
11: ** [[longDescription>>#Long_Description]]
12: ** [[subtitles>>#Subtitles]]
13: ** [[columns>>#Columns]]
14: ** [[uniqueKey>>#Unique_Key]]
15: ** [[displayKey>>#Display_Key]]
16: ** [[initialSort>>#Initial_Sort]]
17: ** [[demarcated>>#Demarcated]]
18: ** [[tandemRanges>>#Tandem_Ranges]]
19: ** [[stackInstanceLimit>>#Stack_Instance_Limit]]
20: ** [[dataKey>>#Data_Key]]
21: ** [[size>>#Size]]
22: ** [[programString>>#Program_String]]
23: ** [[programFileName>>#Program_File_Name]]
24: ** [[substitutions>>#Substitutions]]
25: ** [[predicates>>#Predicates]]
26: ** [[options>>#Options]]
27: ** [[clearedAggregations>>#Cleared_Aggregations]]
28: ** [[movingAverageCount>>#Moving_Average_Count]]
29: ** [[macroArgs>>#Macro_Arguments]]
30: ** [[promptMacroArgs>>#Prompt_Macro_Arguments]]
31: ** [[target>>#Target]]
32: ** [[promptTarget>>#Prompt_Target]]
33: ** [[menuItems>>#Menu_Items]]
34: * [[Column Description>>#Column_Description]]
35: ** [[name>>#Name]]
36: ** [[tupleIndex>>#Tuple_Index]]
37: ** [[tupleMember>>#Tuple_Member]]
38: ** [[tupleConversion>>#Tuple_Conversion]]
39: ** [[valueType>>#Value_Type]]
40: ** [[displayFormat>>#Display_Format]]
41: ** [[sourceColumnName>>#Source_Column_Name]]
42: ** [[dataKey>>#Column_Data_Key]]
43: ** [[renderingType>>#Rendering_Type]]
44: ** [[aggregationName>>#Aggregation_Name]]
45: ** [[minimumValueRange>>#Minimum_Value_Range]]
46: ** [[valuePerSecond>>#Value_Per_Second]]
47: ** [[unitsDescription>>#Units_Description]]
48: ** [[displayTranslation>>#Display_Translation]]
49: ** [[numericString>>#Numeric_String]]
50: ** [[renderingHint>>#Rendering_Hint]]
51: ** [[alignmentHint>>#Alignment_Hint]]
52: ** [[plottable>>#Plottable]]
53: ** [[plottableName>>#Plottable_Name]]
54: ** [[hidden>>#Hidden]]
55: ** [[totallerDescription>>#Column_Totaller_Description]]
56: * [[Menu Item Description>>#Menu_Item_Description]]
57: ** [[singleSelectionNameFormat>>#Single_Selection_Name_Format]]
58: ** [[multiSelectionName>>#Multi_Selection_Name]]
59: ** [[newColumns>>#New_Columns]]
60: ** [[uniqueKey>>#New_Unique_Key]]
61: ** [[displayKey>>#New_Display_Key]]
62: ** [[initialSort>>#New_Initial_Sort]]
63: ** [[newWindowSize>>#New_Window_Size]]
64: ** [[menuItems>>#Nested_Menu_Items]]
65: * [[Totaller Description>>#Totaller_Description]]
66: ** [[totalType>>#Total_Type]]
67: ** [[displayFormat>>#Total_Display_Format]]
68: ** [[unitsDescription>>#Total_Units_Description]]
69: ** [[columnTestDescription>>#Column_Test_Description]]
70: * [[A Simple Display Example>>#A_Simple_Display_Example]]
71: 
72: === Display Description Files
73: 
74: To add a new display, you can copy and modify an existing {{code}}.xml{{/code}} description from the {{code}}display~_descriptions{{/code}} directory.  A description looks like this:  
75: 
76: {{code}}<?xml version="1.0" encoding="UTF-8"?>{{/code}}  
77: {{code}}<java version="1.5.0-beta3" class="java.beans.XMLDecoder">{{/code}}  
78: {{code}} <object class="org.opensolaris.chime.DisplayDescription">{{/code}}  
79: {{code}}  ... //display properties// ...{{/code}}  
80: {{code}} </object>{{/code}}  
81: {{code}}</java>{{/code}}  
82: 
83: The display properties may be specified in any order.  
84: 
85: === Property Documentation Format
86: 
87: Each property is documented in the following format:  
88: 
89: **name:** The case- and whitespace-sensitive spelling of the property exactly as it appears in the XML description.  For example, if the property name is "title", it is specified in the XML description as {{code}}<void property="title">{{/code}}.  
90: **type:** The data type of the property, either a Java primitive or the fully qualified name of a Java class.  For example, if the type is "int", the value 2 would appear in the XML description as {{code}}<int>2</int>{{/code}}.  
91: **range:** The range of valid values for the property.  For example, {{code}}range{{/code}} may a include a list of strings that Chime recognizes as valid values of a property of type {{code}}java.lang.String{{/code}}, along with a short description of how each listed value affects the display.  
92: **property of:** A link back to the object that contains the property; the object is one of [[Display Description>>#Display_Description]], [[Column Description>>#Column_Description]], [[Menu Item Description>>#Menu_Item_Description]], or [[Totaller Description>>#Totaller_Description]].    
93: **description:** A complete description of the property.  
94: **required:** //yes// if the property is required (if a related property provides an alternative, it will appear in parentheses); //no// if the property is not required or is not required in all cases (those cases will be detailed in parentheses)  
95: **default:** If the property is not required, the value used by default when the property is omitted.  
96: **recommended:** A tip about how to use the property, for example "Ignore" if the property is advanced or seldom specified.  
97: **since:** The version of Chime (listed in the [[Change Log>>Project dtrace-chime.changelog]]) that added the property (assumed to be the initial release of Chime if omitted).  
98: **example:** An example XML block that specifies the property. 
99: 
100: === Display Description
101: 
102: A display description specifies all the properties of the display, including **two or more columns** (see [[Column Description>>#Column_Description]]~) and **zero or more menu items** (see [[Menu Item Description>>#Menu_Item_Description]]~).  Every display has [[columns>>#Columns]].  A display with [[menuItems>>#Menu_Items]] supports drilldown: the ability to launch a new display that aggregates the selected values by a new attribute.  For example, a "System Calls" display aggregated by {{code}}execname{{/code}} might allow you to select "Xorg" and aggregate its system calls by function name.  The {{code}}menuItems{{/code}} property must be specified in order to support drilldown; however it has nothing to do with support for plotting data over time in a line graph.  The "Plot Over Time" menu item is enabled automatically if at least one column sets the [[plottable>>#Plottable]] property  to {{code}}true{{/code}}.  
103: 
104: The following documents each of the Chime display properties:   
105: 
106: ==== Version
107: 
108: **name:** version  
109: **type:** int  
110: **property of:** [[Display Description>>#Display_Description]]  
111: **description:** Version of the display description.  If omitted, all versions of Chime will attempt to load the display, with possibly unexpected results.  All of the display descriptions included with Chime include the version property in case a future version of Chime needs to remove, rename, or change the meaning of any property (adding a property does not require a new version).  
112: **required:** no  
113: **default:** none  
114: **recommended:** Copy the version property from any of the display descriptions included with Chime.  
115: **example:**  
116: 
117: {{{
118:     <void property="version">
119:      <int>2</int>
120:     </void>
121: }}}
122: 
123: ==== Title
124: 
125: **name:** title  
126: **type:** java.lang.String  
127: **property of:** [[Display Description>>#Display_Description]]  
128: **description:** Title appearing in the title bar of the display window as well as the button to launch that display from the main Chime window.  
129: **required:** yes  
130: **example:**  
131: 
132: {{{
133:     <void property="title">
134:      <string>System Calls</string>
135:     </void>
136: }}}
137: 
138: ![Title example] (../title.gif)  
139: 
140: ==== Long Description
141: 
142: **name:** longDescription  
143: **type:** java.lang.String  
144: **property of:** [[Display Description>>#Display_Description]]  
145: **description:** Text appearing in the **Description** pane of the main Chime window when the display is selected in the **Traces** list. Supports all HTML tags supported by JTextPane with HTMLEditorKit; however, the angle brackets need to be escaped using **&lt;** for **<** and **&gt;** for **>**. (Note that the [[wizard>>Project dtrace-chime.wizard]], in step **6. Provide a Description**, escapes angle brackets automatically.)    
146: **required:** no  
147: **default:** "No Description Available" appears in the **Description** pane.  
148: **recommended:** Tell what you can about the display to help people anticipate what they will get if they run your display and understand what they are looking at when your display is running. Documenting the display facilitates [[sharing>>Project dtrace-chime.displays]] it with others.  
149: **since:** 1.4.10 (16 Aug 2006)  
150: **example:**  
151: 
152: {{{
153:     <void property="longDescription">
154:      <string>&lt;html&gt;Displays &lt;b&gt;three&lt;/b&gt; columns:
155:          &lt;ol&gt;&lt;li&gt;Executable&lt;/li&gt;&lt;li&gt;History&lt;/li&gt;
156:          &lt;li&gt;Calls Per Second&lt;/li&gt;&lt;/ol&gt;The
157:          lt;i&gt;cyan&lt;/i&gt; &lt;u&gt;line&lt;/u&gt; in the &lt;font
158:          face=&quot;Courier&quot;&gt;History&lt;/font&gt; column indicates the
159:          relative magnitude of the sparkline (the vertical scale determined by
160:          its maximum value).&lt;/html&gt;
161:      </string>
162:     </void>
163: }}}
164: 
165: [[image:Project dtrace-chime.screens_c@wizarddescresult.gif||alt="Long Description Property"]]
166: 
167: ==== Subtitles
168: 
169: **name:** subtitles  
170: **type:** org.opensolaris.chime.util.NameValuePair[]  
171: **property of:** [[Display Description>>#Display_Description]]  
172: **description:** One or more titles stacked vertically in a label at the top of the display, just below the window’s title bar.  Chime uses the {{code}}subtitles{{/code}} property internally only for derivative displays launched by menu actions, and only when multiple rows are selected as predicates for the new display.  If only a single row is selected, its [[Display Key>>#Display_Key]] is simply incorporated into the [[title>>#Title]] property appearing in the title bar.  For example, if the key column of the "System Calls" display is "Executable", and you select a single row whose Executable value is "Xorg", then the title of the new display for that row is "Xorg System Calls".  However, if multiple rows are selected, for example "Xorg" and "gnome-terminal", then the new display is labeled with the subtitle "Executable: Xorg, gnome-terminal".  
173: **required:** no  
174: **default:** none  
175: **recommended:** Ignore, unless the described display uses a predicate that
176: is too complicated to convey in the {{code}}title{{/code}} property and the display will
177: not make sense without a label for the predicate.  
178: 
179: ![Subtitles example] (../subtitles.gif)  
180: 
181: ==== Columns
182: 
183: **name:** columns  
184: **type:** org.opensolaris.chime.ColumnDescription[]  
185: **property of:** [[Display Description>>#Display_Description]]  
186: **description:** Column descriptions used to generate the columns at the corresponding indices {{code}}0 .. (n - 1){{/code}} in the table data model.  Each column description includes the name that appears in the displayed column header and properties that dictate how the column is populated, formatted, etc.  See [[Column Description>>#Column_Description]] for more detail.  
187: **required:** yes  
188: **example:** (2 columns: "Executable" and "Count")  
189: 
190: {{{
191:     <void property="columns">
192:      <array class="org.opensolaris.chime.ColumnDescription" length="2">
193:       <void index="0">
194:        <object class="org.opensolaris.chime.ColumnDescription">
195:         <void property="name">
196:          <string>Executable</string>
197:         </void>
198:         //... remaining properties omitted ...//
199:        </object>
200:       </void>
201:       <void index="1">
202:        <object class="org.opensolaris.chime.ColumnDescription">
203:         <void property="name">
204:          <string>Count</string>
205:         </void>
206:         //... remaining properties omitted ...//
207:        </object>
208:       </void>
209:      </array>
210:     </void>
211: }}}
212: 
213: ==== Unique Key
214: 
215: **name:** uniqueKey  
216: **type:** java.lang.String[]  
217: **property of:** [[Display Description>>#Display_Description]]  
218: **description:** Names of the columns whose values in combination are unique, never repeated across multiple table rows.  Each name in the unique key must exactly match the [[name>>#Name]] property of a [[Column Description>>#Column_Description]] included in the [[columns>>#Columns]] property.  Column name matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).  
219: **required:** no  
220: **default:** The unique key defaults to the names of the columns that specify a non-negative [[tupleIndex>>#Tuple_Index]] value, in order by tuple index.  
221: **recommended:** Ignore. As of version 1.4.36, the unique key is generated automatically even in special cases like distributions generated by the DTrace {{code}}quantize(){{/code}} and {{code}}lquantize(){{/code}} actions.  
222: 
223: ==== Display Key
224: 
225: **name:** displayKey  
226: **type:** java.lang.String[]  
227: **property of:** [[Display Description>>#Display_Description]]  
228: **description:** Names of the columns used to display the [[uniqueKey>>#Unique_Key]] column values, if the displayed columns differ from those of the {{code}}uniqueKey{{/code}}.  For example, if the unique key is ["User ID"], and if the column named in the unique key is hidden (see the [[hidden>>#Hidden]] column property), and its value is converted from an integer into a String value displayed in the "User" column, then the display key should be ["User"].  The display key, if specified, is used instead of the unique key whenever a menu action on a selected row launches another display, such as when choosing the "Plot Over Time" menu item or a drilldown menu item like "<selected pid> by Function", and a string derived from the key values is used to label the new display.  The name of each column must exactly match the [[name>>#Name]] property of a [[Column Description>>#Column_Description]] included in the [[columns>>#Columns]] property.  Column name matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).  
229: **required:** no    
230: **default:** Chime uses the [[uniqueKey>>#Unique_Key]], except that when a column in the unique key is [[hidden>>#Hidden]], Chime finds the column whose [[sourceColumnName>>#Source_Column_Name]] property references the hidden column to display in its place.  
231: **recommended:** Ignore. As of version 1.4.36, the display key is generated automatically.  
232: 
233: ==== Initial Sort
234: 
235: **name:** initialSort  
236: **type:** org.opensolaris.chime.util.TableSortCriteria[]  
237: **property of:** [[Display Description>>#Display_Description]]  
238: **description:** The names of the columns used to sort the table when it is first displayed, including whether to sort each column in ascending or descending order.  If the table is sorted by multiple columns, then the specified columns after the first are used as tie-breakers when the values in the previous specified columns are equal.  The name of each column must exactly match the [[name>>#Name]] property of a [[Column Description>>#Column_Description]] included in the [[columns>>#Columns]] property.  Column name matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).  After the column name, each element of the sort criteria must also specify whether or not the sort on that column is ascending ({{code}}true{{/code}} or {{code}}false{{/code}}).  
239: **required:** no  
240: **default:** Chime sorts in ascending order by the columns named in the [[displayKey>>#Display_Key]], or by the columns named in the [[uniqueKey>>#Unique_Key]] if the display key is unspecified.  If neither the display key nor the unique key is specified //explicitly//, Chime leaves the data in the order given by DTrace; no sort markers appear in the header.  
241: **recommended:** Consider sorting in descending order by the aggregated numeric value associated with each tuple.  
242: **example:** (sort by Calls Per Second descending) 
243: 
244: {{{
245:     <void property="initialSort">
246:      <array class="org.opensolaris.chime.util.TableSortCriteria" length="1">
247:       <void index="0">
248:        <object class="org.opensolaris.chime.util.TableSortCriteria">
249:         <string>Calls Per Second</string>
250:         <boolean>false</boolean>
251:        </object>
252:       </void>
253:      </array>
254:     </void>
255: }}}
256: 
257: ![Initial Sort example] (../initsort.gif)  
258: 
259: ==== Demarcated
260: 
261: **name:** demarcated  
262: **type:** boolean  
263: **property of:** [[Display Description>>#Display_Description]]  
264: **description:** Indicates that a black line should separate groups of table rows having the same unique key values in all but the last column of the unique key.  (See the [[uniqueKey>>#Unique_Key]] property.)  For example, if the unique key is ["Executable Name", "Nanoseconds"] then a horizontal black line appears every time there is a change in the "Executable Name" value (even if that column is hidden from the display; see the [[hidden>>#Hidden]] column property.  In this case, the "Executable Name" column is hidden behind the "Executable" column, which displays a non-repeating view of the "Executable Name" column; see {{code}}GROUP{{/code}} under the [[valueType>>#Value_Type]] property).  
265: **required:** no  
266: **default:** false  
267: **recommended:** If your D program uses the {{code}}quantize(){{/code}} or {{code}}lquantize(){{/code}} actions, set the {{code}}demarcated{{/code}} property to {{code}}true{{/code}} to group the resulting value distributions.  You will also need to specify the {{code}}BUCKET{{/code}} and {{code}}BUCKET~_FREQUENCY{{/code}} value types for the columns that display the bucket range and the distributions values, respectively.  (See the [[valueType>>#Value_Type]] property.)    
268: **example:**  
269: 
270: {{{
271:     <void property="demarcated">
272:      <boolean>true</boolean>
273:     </void>
274: }}}
275: 
276: ![Demarcated example] (../demarcated.gif)  
277: 
278: ==== Tandem Ranges
279: 
280: **name:** tandemRanges  
281: **type:** java.lang.String~[~]~[~]  
282: **property of:** [[Display Description>>#Display_Description]]  
283: **description:** Groups of column names identifying columns with numeric values that need to remain visually comparable on the same scale when rendered as bar graphs.  Normally, columns rendered as bar graphs start with an initial range set by the [[minimumValueRange>>#Minimum_Value_Range]] column property (see the [[columns>>#Columns]] property), and rescale independently as needed whenever a value would otherwise exceed that range.  Columns grouped by this property rescale in tandem, even if one of the columns never exceeds its initial range; if any column in the group exceeds the shared range, all of them rescale together.  Multiple groups of columns can be specified to rescale independently of each other.  For example, if the tandem ranges are [["Reads Per Second", "Writes Per Second"], ["Total Read Time", "Total Write Time"]], then "Reads Per Second" and "Writes Per Second" rescale together independently; similarly, if "Total Read Time" grows beyond its current range, not only is it rescaled, but "Total Write Time" is rescaled along with it (even if there have been no writes since tracing began); however, that rescaling has no effect on the "Reads Per Second" column or the "Writes Per Second" column.  
284: **required:** no  
285: **default:** none  
286: **example:**  
287: 
288: {{{
289:     <void property="tandemRanges">
290:      <array class="[[Ljava.lang.String;" length="2">
291:       <void index="0">
292:        <array class="java.lang.String" length="2">
293:         <void index="0">
294:          <string>Reads Per Second</string>
295:         </void>
296:         <void index="1">
297:          <string>Writes Per Second</string>
298:         </void>
299:        </array>
300:       </void>
301:       <void index="1">
302:        <array class="java.lang.String" length="2">
303:         <void index="0">
304:          <string>Total Read Time</string>
305:         </void>
306:         <void index="1">
307:          <string>Total Write Time</string>
308:         </void>
309:        </array>
310:       </void>
311:      </array>
312:     </void>
313: }}}
314: 
315: ==== Stack Instance Limit
316: 
317: **name:** stackInstanceLimit  
318: **type:** int  
319: **property of:** [Display Description>>#Display_Description]]  
320: **description:** Limits the number of unique instances generated by the {{code}}stack(){{/code}}, {{code}}ustack(){{/code}}, and {{code}}jstack(){{/code}} actions, aborting the display with {{code}}org.opensolaris.chime.TooManyInstancesException{{/code}} if that limit is exceeded.  Multiple occurrences of the same stack trace count as one instance.  This property is intended to prevent unlimited table growth and memory consumption resulting from user stack replication caused by program relocation (stack frames with the same string value are considered distinct by DTrace if their address differs).  
321: **required:** no  
322: **default:** 2,000  
323: **recommended:** Ignore.  
324: 
325: ==== Data Key
326: 
327: **name:** dataKey  
328: **type:** java.lang.String  
329: **property of:** [[Display Description>>#Display_Description]]  
330: **description:** Multiple displays that share the same data key use the same instance factory to obtain stack values, improving memory usage since columns across multiple displays are populated with instances from the same shared pool.  By default, the [[title>>#Title]] property serves as the {{code}}dataKey{{/code}}.  Children of a display launched by choosing a drilldown action on any row selection inherit the data key of the display that launched them.  
331: **required:** no  
332: **default:** same as the {{code}}title{{/code}} property  
333: **recommended:** Ignore.  
334: 
335: ==== Size
336: 
337: **name:** size  
338: **type:** java.awt.Dimension  
339: **property of:** [[Display Description>>#Display_Description]]  
340: **description:** Initial size of the window containing the display.  
341: **required:** no  
342: **default:** 400x300 (pixels wide by pixels high)  
343: **recommended:** 400 pixels wide by 300 pixels high seems like a good starting point for a display with two or three displayed columns.  Displays with value distributions resulting from the {{code}}quantize(){{/code}} and {{code}}lquantize(){{/code}} actions work better with a height around 700 pixels.  Displays with many columns require a wider display window.  
344: **example:**  
345: 
346: {{{
347:     <void property="size">
348:      <object class="java.awt.Dimension">
349:       <int>400</int>
350:       <int>300</int>
351:      </object>
352:     </void>
353: }}}
354: 
355: ==== Program String
356: 
357: **name:** programString  
358: **type:** java.lang.String  
359: **property of:** [[Display Description>>#Display_Description]]  
360: **description:** The full contents (text) of the D program compiled by DTrace to enable probes and generate data for the display.  
361: **required:** yes (unless the [[programFileName>>#Program_File_Name]] property is specified instead)  
362: **example:**  
363: 
364: {{{
365:     <void property="programString">
366:      <string>syscall:::entry { @[execname] = count(); }</string>
367:     </void>
368: }}}
369: 
370: ==== Program File Name
371: 
372: **name:** programFileName  
373: **type:** java.lang.String  
374: **property of:** [[Display Description>>#Display_Description]]  
375: **description:** The name of the file containing the D program compiled by DTrace to enable probes and generate data for the display.  Chime will look for the named file in the {{code}}display_descriptions{{/code}} directory (or the directory specified by the {{code}}-d{{/code}} option).  If the displays are loaded from a subdirectory, Chime will look for the named file first in that subdirectory, and failing that, it will search its parent directories until it reaches {{code}}display_descriptions{{/code}} (or the directory specified by the {{code}}-d{{/code}} option).  
376: **required:** yes (unless the [[programString>>#Program_String]] property is specified instead)  
377: **example:**  
378: 
379: {{{
380:     <void property="programFileName">
381:      <string>intrstat.d</string>
382:     </void>
383: }}}
384: 
385: ==== Substitutions
386: 
387: **name:** substitutions  
388: **type:** org.opensolaris.chime.util.NameValuePair[]  
389: **property of:** [[Display Description>>#Display_Description]]  
390: **description:** Supports improved D program reusability by specifying program placeholders and values to substitute for those placeholders.  Substitutions are similar to [[macro arguments>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view]] in D, except that substitutions are performed //before// the program is compiled and behind the scenes without prompting the user.  (See the [[macroArgs>>#Macro_Arguments]] property if you want values that you can fill in at the time of launching a display.)  Chime expects placeholders to be surrounded by double question marks, for example:  
391: 
392: {{{
393:     ??PROBE??
394:     ??P0??
395:     {
396:             @a[??T??] = ??ACTION??(??ARGS??);
397:     }
398:     
399:     ??P0
400:     ??T0 execname
401:     ??ACTION count
402:     ??ARGS
403: }}}
404: 
405: Default placeholder values may be listed at the end of the program by repeating the placeholder tag preceded by a //single// pair of question marks.  A placeholder with a default value listed in this way need not be specified in the {{code}}substitutions{{/code}} property of the display description.  The predicates ({{code}}P0{{/code}}, {{code}}P1{{/code}}, {{code}}P2{{/code}}, ...) and the aggregation tuple ({{code}}T{{/code}}) are special placeholder tags that should not be specified in the {{code}}substitions{{/code}} property.  Instead, use the [[predicates>>#Predicates]] property for predicates and the [[tupleMember>>#Tuple_Member]] column property for tuple members.  ({{code}}T0{{/code}}, {{code}}T1{{/code}}, {{code}}T2{{/code}}, ...) are also special tags for listing default tuple member values at the end of the program.  Each allows the {{code}}tupleMember{{/code}} property of its corresponding column description to be omitted (if specified, the value overrides the default listed in the program).  If the default value of a placeholder is blank, the substitution value is the empty string (different from not listing a default).  In the example above, listing {{code}}??P0{{/code}} without a subsequent value makes it unnecessary to specify the {{code}}predicates{{/code}} property; the default value of //no predicate// is already given in the program.  
406: 
407: A program like the one above is specified using the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property.  Note that in order to support drilldown with the [[menuItems>>#Menu_Items]] property, your D program must use the special substitution placeholders for predicates ({{code}}P0{{/code}}, {{code}}P1{{/code}}, {{code}}P2{{/code}}, etc.) and aggregation tuple ({{code}}T{{/code}}) described above.  Other tags (such as {{code}}PROBE{{/code}}, {{code}}ACTION{{/code}}, and {{code}}ARGS{{/code}} in the example above) are completely up to you and may be spelled however you like (these are the tags you specify in the {{code}}substitutions{{/code}} property).  
408:   
409: The //name// of each {{code}}NameValuePair{{/code}} specified in this property must omit the surrounding question marks and is used to match a placeholder tag in your D program.  Matching is case-sensitive.  The //value// of each pair may be any {{code}}Object{{/code}}, and its {{code}}toString(){{/code}} value overwrites the matched placeholder.  
410: **required:** no (unless the specified D program uses placeholders other than predicates and aggregation tuple without listing default values)  
411: **default:** none  
412: **example:** (specifies the probe {{code}}syscall:::entry{{/code}} for the only substitution placeholder without a default value in the example above)  
413: 
414: {{{
415:     <void property="substitutions">
416:      <array class="org.opensolaris.chime.util.NameValuePair" length="1">
417:       <void index="0">
418:        <object class="org.opensolaris.chime.util.NameValuePair">
419:         <string>PROBE</string>
420:         <object class="org.opensolaris.os.dtrace.ProbeDescription">
421:          <string>syscall</string>
422:          <string></string>
423:          <string></string>
424:          <string>entry</string>
425:         </object>
426:        </object>
427:       </void>
428:      </array>
429:     </void>
430: }}}
431: 
432: ==== Predicates
433: 
434: **name:** predicates  
435: **type:** java.lang.String[]  
436: **property of:** [[Display Description>>#Display_Description]]  
437: **description:** Supports improved D program reusability by replacing predicate placeholders {{code}}??P0??{{/code}}, {{code}}??P1??{{/code}}, {{code}}??P2??{{/code}}, etc. with predicate strings specified at the array indices corresponding to the integers after the initial ’**P**’ of the placeholder tag.  Predicate substitution is handled separately from the [[substitutions>>#Substitutions]] property because the specified predicates may need to be modified at runtime when you request a new display for one or more selected rows aggregated by a new key (this property, along with the [[tupleMember>>#Tuple_Member]] column preoprty, supports drilldown [[menuItems>>#Menu_Items]]~).   Note that some characters in the predicate need to be escaped because they are otherwise parsed as special XML characters.  For example, the structure pointer operator {{code}}->{{/code}} needs to written {{code}}-&gt;{{/code}} and the bitwise AND operator {{code}}&{{/code}} needs to written as {{code}}&amp;{{/code}}.  The specified predicate strings must omit the surrounding forward slashes ( {{code}}/{{/code}} ); these are added by Chime.    
438: **required:** no (unless the D program specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property uses a predicate placeholder ({{code}}??P0??{{/code}}, {{code}}??P1??{{/code}}, {{code}}??P2??{{/code}}, ...) without listing a default
439: value)  
440: **default:** none  
441: **example:** (replaces {{code}}??P0??{{/code}} with the predicate {{code}}/args[0]->b~_flags & B~_READ/{{/code}} and {{code}}??P1??{{/code}} with the predicate {{code}}/args[0]->b~_flags & B~_WRITE/{{/code}} ) 
442: 
443: {{{
444:     <void property="predicates">
445:      <array class="java.lang.String" length="2">
446:       <void index="0">
447:        <string>args[0]-&gt;b~_flags &amp; B~_READ</string>
448:       </void>
449:       <void index="1">
450:        <string>args[0]-&gt;b~_flags &amp; B~_WRITE</string>
451:       </void>
452:      </array>
453:     </void>
454: }}}
455: 
456: ==== Options
457: 
458: **name:** options  
459: **type:** org.opensolaris.dtracex.Option[]  
460: **property of:** [[Display Description>>#Display_Description]]  
461: **description:** Specifies [[DTrace options>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidlis?a=view]] to use with the program specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property.  Note that the {{code}}aggrate{{/code}} option sets the initial value of the "Interval in seconds" control in the lower left corner of the display.  
462: **required:** no  
463: **default:** Chime uses the following default options:
464: ** {{code}}bufsize{{/code}} 256 KB
465: ** {{code}}aggsize{{/code}} 256 KB
466: ** {{code}}aggrate{{/code}} 1 second
467: **example:** ( {{code}}aggrate 4m, bufsize 4m, dynvarsize 1m{{/code}} )  
468: 
469: {{{
470:     <void property="options">
471:      <array class="org.opensolaris.os.dtrace.Option" length="3">
472:       <void index="0">
473:        <object class="org.opensolaris.os.dtrace.Option">
474:         <string>bufsize</string>
475:         <string>4m</string>
476:        </object>
477:       </void>
478:       <void index="1">
479:        <object class="org.opensolaris.os.dtrace.Option">
480:         <string>aggsize</string>
481:         <string>4m</string>
482:        </object>
483:       </void>
484:       <void index="2">
485:        <object class="org.opensolaris.os.dtrace.Option">
486:         <string>dynvarsize</string>
487:         <string>1m</string>
488:        </object>
489:       </void>
490:      </array>
491:     </void>
492: }}}
493: 
494: ==== Cleared Aggregations
495: 
496: **name:** clearedAggregations  
497: **type:** java.lang.String[]  
498: **property of:** [[Display Description>>#Display_Description]]  
499: **description:** Names the aggregations whose values should be reset to zero each time Chime gets the latest aggregate to update the display.  The aggregation names are exactly as they appear in the D program specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property minus the initial {{code}}@{{/code}}.  For example, if your program contains the line {{code}}@counts[execname] = count();{{/code}} use the name "counts".  If the aggregation is unnamed ( {{code}}@[execname] = counts();{{/code}} ) use the empty string ( {{code}}<string></string>{{/code}} ).  Clear an aggregation if you want values per time interval; do not clear an aggregation if you want running totals instead.  Chime clears all aggregations by default if the {{code}}clearedAggregations{{/code}} property is omitted.  Specify an empty array to display only running totals.  
500: **required:** no  
501: **default:** Chime clears all aggregations by default.  
502: **recommended:** If you want to display some columns as values per time interval and other columns as running totals, specify only the names of the aggregations from which you intend to get values per time interval.  You cannot get both running totals and values per time interval from the same aggregation, so if you want to display the same data both ways, you will need two different aggregations.  If you want values per second, then in addition to clearing the aggregation, you also need to set the [[valuePerSecond>>#Value_Per_Second]] column property to {{code}}true{{/code}} (see [[columns>>#Columns]]~), otherwise you get the total accumulated since the last interval instead of a per-second average.  
503: **example:**  (displays only running totals)  
504: 
505: {{{
506:     <void property="clearedAggregations">
507:      <array class="java.lang.String" length="0"/>
508:     </void>
509: }}}
510: 
511: ==== Moving Average Count
512: 
513: **name:** movingAverageCount  
514: **type:** int  
515: **property of:** [[Display Description>>#Display_Description]]  
516: **description:** Specifies that displayed values should be "smoothed" by averaging them with the previous (n-1) values, when //n// is the set size specified by movingAverageCount.  
517: **required:** no  
518: **default:** 0  
519: **recommended:** Unless you want some kind of smoothing on by default, ignore this property, since it can be changed by the user at runtime by means of a right-click menu item.  
520: **example:**  (average with the three previous values)  
521: 
522: {{{
523:     <void property="movingAverageCount">
524:      <int>4</int>
525:     </void>
526: }}}
527: 
528: ==== Macro Arguments
529: 
530: **name:** macroArgs  
531: **type:** org.opensolaris.dtracex.MacroArgument[]  
532: **property of:** [[Display Description>>#Display_Description]]  
533: **description:** Specifies [[macro arguments>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view]] to the D program specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property.  Macro argument variables in your D program are integers preceded by the {{code}}${{/code}} character (or {{code}}$${{/code}} if you want the macro argument to be interpreted as a string token).  They are replaced in the native DTrace library when the program is compiled, unlike Chime substitutions made prior to compilation (see the [[substitutions>>#Substitutions]] property).  The macro argument specified at array index 0 replaces {{code}}$1{{/code}} or {{code}}$$1{{/code}}, the macro argument specified at array index 1 replaces {{code}}$2{{/code}} or {{code}}$$2{{/code}}, and so on.  Each macro argument specifies a user-visible name that should clarify what kind of argument value is expected.  For example, "Process ID" could be used to label {{code}}$1{{/code}} in {{code}}/ pid == $1 /{{/code}}.  After the name, each macro argument specifies a default argument value (also a string), which may be {{code}}null{{/code}}.  If at least one macro argument has a {{code}}null{{/code}} value, or if the [[promptMacroArgs>>#Prompt_Macro_Arguments]] property is {{code}}true{{/code}}, Chime will prompt you for macro argument values before starting the display.  At that time you can overwrite any specified defaults.     
534: 
535: **required:** no (unless your D program contains macro variables)   
536: **default:** none   
537: **recommended:** Use macro arguments instead of substitutions if you want the placeholders to remain visible to the user through the "Display DTrace Program" menu action.  
538: **example:** ( prompts for {{code}}execname == $$1{{/code}} and {{code}}fbt:$$2::entry{{/code}} without providing default values )  
539: 
540: {{{
541:     <void property="macroArgs">
542:      <array class="org.opensolaris.dtracex.MacroArgument" length="2">
543:       <void index="0">
544:        <object class="org.opensolaris.dtracex.MacroArgument">
545:         <string>Executable</string>
546:         <null/>
547:        </object>
548:       </void>
549:       <void index="1">
550:        <object class="org.opensolaris.dtracex.MacroArgument">
551:         <string>Module</string>
552:         <null/>
553:        </object>
554:       </void>
555:      </array>
556:     </void>
557: }}}
558: 
559: ![Macro Arguments Prompt] (../screens_a/macroargs.gif)  
560: 
561: //The program started after you enter "java" and "genunix"//  
562: 
563: ![Program with Macro Arguments] (../screens_a/program.gif)  
564: 
565: ==== Prompt Macro Arguments
566: 
567: **name:** promptMacroArgs  
568: **type:** boolean  
569: **property of:** [[Display Description>>#Display_Description]]  
570: **description:** Indicates whether Chime should prompt the user for macro argument values even if a default value is specified for every named macro variable (see the [[macroArgs>>#Macro_Arguments]] property) in your D program.  If at least one  {{code}}macroArgs{{/code}} element does not specify a default value, Chime will display a prompt regardless of the value of this property.  
571: **required:** no  
572: **default:** false  
573: **example:**  
574: 
575: {{{
576:     <void property="promptMacroArgs">
577:      <boolean>true</boolean>
578:     </void>
579: }}}
580: 
581: ==== Target
582: 
583: **name:** target  
584: **type:** java.lang.String  
585: **property of:** [[Display Description>>#Display_Description]]  
586: **description:** A [[target process>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view]] specified either as a command string to execute or as the process ID of an existing process.  If a command string is specified, Chime will execute the command but suspend the created process until probes are enabled so that the process can be traced from the very start of its execution (same as the {{code}}dtrace(1M) -c{{/code}} option).  If a process ID is specified, Chime will grab the specified process and cache its symbol tables (same as the {{code}}dtrace(1M) -p{{/code}} option).  In either case, the {{code}}pid{{/code}} of the target process replaces the {{code}}$target{{/code}} macro variable in your D program.  
587: **required:** no  
588: **default:** none  
589: **recommended:** Set the [[promptTarget>>#Prompt_Target]] property to {{code}}true{{/code}} if you want the user to supply the target command or {{code}}pid{{/code}}.  In that case, specify the {{code}}target{{/code}} property only if you want to provide a default value for the prompt.  
590: **example:** (traces the {{code}}date{{/code}} command)  
591: 
592: {{{
593:     <void property="target">
594:      <string>date</string>
595:     </void>
596: }}}
597: 
598: ==== Prompt Target
599: 
600: **name:** promptTarget  
601: **type:** boolean  
602: **property of:** [[Display Description>>#Display_Description]]  
603: **description:** Indicates whether Chime should prompt the user for the value of the {{code}}$target{{/code}} macro variable in your D program.  If {{code}}true{{/code}}, Chime will prompt the user even if a default value is already specified by the [[target>>#Target]] property.  The prompt requests either a command to execute or the {{code}}pid{{/code}} of an existing process.  
604: **required:** no (unless your D program contains the {{code}}$target{{/code}} macro variable and the {{code}}target{{/code}} property does not specify its value)  
605: **default:** false  
606: **example:**  
607: 
608: {{{
609:     <void property="promptTarget">
610:      <boolean>true</boolean>
611:     </void>
612: }}}
613: 
614: ![Target Process Prompt] (../screens_a/prompt_target.gif)  
615: 
616: ==== Menu Items
617: 
618: **name:** menuItems  
619: **type:** org.opensolaris.chime.MenuItemDescription[]  
620: **property of:** [[Display Description>>#Display_Description]]  
621: **description:** Menu item descriptions used to generate drilldown actions.  A drilldown action launches a new display that aggregates the selected values by a new attribute, extending the predicates of the previous display to limit tracing to selected key values.  The new display aggregates by a new tuple, replacing the key columns but retaining the value columns of the previous display.  For example, the "System Calls" display aggregated by {{code}}execname{{/code}} shows a high number of system calls made by {{code}}Xorg{{/code}}:  
622: 
623: ![System Calls by Executable] (../screens_a/syscalls.gif)  
624: 
625: When you invoke "Xorg by Function" on the selected row (by right-click popup menu), a new display appears that replaces the "Executable" column of the previous display with a new "Function" column.  The D program used by the new display aggregates by {{code}}probefunc{{/code}} instead of {{code}}execname{{/code}} and adds the predicate {{code}}/execname == "Xorg"/{{/code}}:  
626: 
627: ![Xorg System Calls by Function] (../screens_b/xorgcalls.gif)  
628: 
629: Here the "Xorg" count of the previous display is broken down by function.  
630: 
631: A column from the original display is dropped from the drilldown display for any of the following reasons:
632: 1. its [[tupleIndex>>#Tuple_Index]] is non-negative
633: 1. its [[name>>#Name]] is part of the [[uniqueKey>>#Unique_Key]] or [[displayKey>>#Display_Key]]
634: 1. its [[sourceColumnName>>#Source_Column_Name]] is part of the {{code}}uniqueKey{{/code}} or {{code}}displayKey{{/code}}
635: 
636: Each menu item in the {{code}}menuItems{{/code}} property specifies many properties of its own.  For example, new columns must be described just as they were in the [[columns>>#Columns]] property of the previous display.  See [[Menu Item Description>>#Menu_Item_Description]] for a complete list of menu item properties.  
637: 
638: Menu items may be nested: each specified menu item may itself contain zero or more menu items.  Each level of nesting supports another level of drilldown.  For example, the "read" value in the "Xorg System Calls" above might be broken down by user stack.  Nested menu items are only available in the display launched by the containing menu item.  
639: **required:** no  
640: **default:** none  
641: **recommended:** This is a somewhat daunting property to specify by hand.  You may want to get the display working without drilldown support first, then add drilldown menu items one level at a time.  Remember that drilldown only works if your program uses the following special substitution variables: {{code}}??T??{{/code}} for the tuple, and {{code}}??P0??{{/code}}, {{code}}??P1??{{/code}}, etc. for one or more predicates (see the [[substitutions>>#Substitutions]], [[tupleMember>>#Tuple_Member]], and [[predicates>>#Predicates]] properties).  For an example of nested menu items, see the installed {{code}}syscall.xml{{/code}} file in the {{code}}display~_descriptions{{/code}} directory.  
642: **example:** (Creates a drilldown menu that launches a new display for the selected row or rows, replacing the key columns of the previous display with a new "Function" column, but retaining the value columns of the previous display.  The menu item is labeled "By Function" if multiple rows are selected, or "<selected-key> by Function" if a single row is selected.)   
643: 
644: {{{
645:     <void property="menuItems">
646:      <array class="org.opensolaris.chime.MenuItemDescription" length="1">
647:       <void index="0">
648:        <object class="org.opensolaris.chime.MenuItemDescription">
649:         <void property="newColumns">
650:          <array class="org.opensolaris.chime.ColumnDescription" length="1">
651:           <void index="0">
652:            <object class="org.opensolaris.chime.ColumnDescription">
653:             <void property="tupleMember">
654:              <string>probefunc</string>
655:             </void>
656:             <void property="name">
657:              <string>Function</string>
658:             </void>
659:             <void property="tupleIndex">
660:              <int>0</int>
661:             </void>
662:            </object>
663:           </void>
664:          </array>
665:         </void>
666:         <void property="singleSelectionNameFormat">
667:          <string>{0} by Function</string>
668:         </void>
669:         <void property="multiSelectionName">
670:          <string>By Function</string>
671:         </void>
672:        </object>
673:       </void>
674:      </array>
675:     </void>
676: }}}
677: 
678: === Column Description
679: 
680: A column description specifies all the properties of a single column.  See the [[columns>>#Columns]] display property and the [[newColumns>>#New_Columns]] menu item property; both specify column descriptions.    
681: 
682: ==== Name
683: 
684: **name:** name  
685: **type:** java.lang.String  
686: **property of:** [[Column Description>>#Column_Description]]  
687: **description:** The name of the column appearing in the displayed column header.  
688: **required:** yes  
689: **example:**  
690: 
691: {{{
692:     <void property="name">
693:      <string>Executable</string>
694:     </void>
695: }}}
696: 
697: ==== Tuple Index
698: 
699: **name:** tupleIndex  
700: **type:** int  
701: **property of:** [[Column Description>>#Column_Description]]  
702: **description:** The zero-based index of the tuple member in the D program specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property whose values are displayed in this column.  For example, if you are aggregating {{code}}@[pid, probefunc] = count();{{/code}} then the column displaying the {{code}}pid{{/code}} values might be named "Process ID", and the column displaying the {{code}}probefunc{{/code}} values might be named "Function".  
703: **required:** no (unless the column displays part of the aggregation key; that is, one of the tuple members found in square brackets in your D program)  
704: **example:** (a column that displays the values of the first tuple member)  
705: 
706: {{{
707:     <void property="tupleIndex">
708:      <int>0</int>
709:     </void>
710: }}}
711: 
712: ==== Tuple Member
713: 
714: **name:** tupleMember  
715: **type:** java.lang.String  
716: **property of:** [[Column Description>>#Column_Description]]  
717: **description:** A program variable name used to fill in the tuple member whose values are displayed by this column.  The {{code}}tupleMember{{/code}} values of one or more columns collectively replace the {{code}}??T??{{/code}} substitution variable in your D program (see the [[substitutions>>#Substitutions]] property); each {{code}}tupleMember{{/code}} fills in the tuple position specified by the column’s [[tupleIndex>>#Tuple_Index]] property.  For example, if the {{code}}tupleMember{{/code}} is {{code}}probefunc{{/code}} and the {{code}}tupleIndex{{/code}} is 1, then {{code}}@[??T??]{{/code}} is replaced by {{code}}@[< ... > , probefunc]{{/code}} (the first tuple member {{code}}< ... >{{/code}} needs to be filled in by another column specifying a {{code}}tupleMember{{/code}} at {{code}}tupleIndex{{/code}} 0).  The tuple member must be spelled exactly as it will appear in your D program, except that some characters need to be escaped to prevent them from being parsed as special XML characters.  For example, {{code}}args[1]->dev_pathname{{/code}} needs to be specified as  
718: 
719: > {{code}}<string>args[1]-&gt;dev~_pathname</string>{{/code}}  
720: 
721: Your D program (specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property) can supply default tuple members for the {{code}}??T??{{/code}} substitution variable.  For example  
722: 
723: {{{
724:     ??PROBE??
725:     ??P0??
726:     {
727:             @a[??T??] = ??ACTION??(??ARGS??);
728:     }
729:     
730:     ??P0
731:     ??T0 execname
732:     ??ACTION count
733:     ??ARGS
734: }}}
735: 
736: In the example above, {{code}}execname{{/code}} is the default value for the tuple member at index 0, so you may omit the {{code}}tupleMember{{/code}} property if {{code}}tupleIndex{{/code}} is 0 (accepting the default value {{code}}execname{{/code}}).  
737: **required:** no (unless your D program uses the {{code}}??T??{{/code}} substitution variable without providing a default for the tuple member at the position specified by the {{code}}tupleIndex{{/code}} property)  
738: **default:** none (unless a default is specified in your D program after {{code}}??T0{{/code}} for the first tuple member, or after {{code}}??T1{{/code}} for the second tuple member, etc.)  
739: **example:** (replaces the {{code}}??T??{{/code}} substitution variable with a tuple whose member at the index specified by the {{code}}tupleIndex{{/code}} property is {{code}}execname{{/code}})  
740: 
741: {{{
742:     <void property="tupleMember">
743:      <string>execname</string>
744:     </void>
745: }}}
746: 
747: ==== Tuple Conversion
748: 
749: **name:** tupleConversion  
750: **type:** org.opensolaris.chime.TupleConversionDescription  
751: **property of:** [[Column Description>>#Column_Description]]  
752: **description:** A conversion of DTrace tuple values into a form more suitable for display.  For example, you may want to display a {{code}}uid{{/code}} tuple member as a username.  The conversion may be a call into native code, or it may be a request to combine several tuple members into a single display value that can be performed in Java without resorting to native code.  If all you want is a simple formatting change of a single tuple member, specify that with the [[displayFormat>>#Display_Format]] (or less commonly, the [[displayTranslation>>#Display_Translation]]~) property instead.  Note that if you want to support drilldown (see the [[menuItems>>#Menu_Items]] property), you will also need a [[hidden>>#Hidden]] column for the unconverted DTrace values, since the converted display values are unusable when forming new program predicates.  The converted column (the one that specifies this property) should form part of the [[displayKey>>#Display_Key]], while the [[uniqueKey>>#Unique_Key]] uses the hidden column with the unconverted DTrace values.  
753: 
754: A tuple conversion is described with the following properties:
755: 
756: * conversionName (java.lang.String)
757: * tupleIndexes (int[])
758: * unconvertedIndex (int)
759: * cachingEnabled (boolean)
760: 
761: The {{code}}conversionName{{/code}} must match an available conversion listed by name below.  Each name is followed by the arguments that the named conversion expects (arguments must be specified by the {{code}}tupleIndexes{{/code}} property in the order given below):   
762: 
763: * ADDR~_TO~_KERNEL~_FUNCTION
764: ** arguments (1)
765: *** 32- or 64-bit integer address
766: ** result: function name (string)
767: * ADDR~_TO~_USER~_FUNCTION
768: ** arguments (2)
769: *** process ID (pid)
770: *** 32- or 64-bit integer address
771: ** result: function name (string)
772: * DEVPATH~_TO~_cNdNsN
773: ** arguments (1)
774: *** device path (string) in the long form such as /devices/pci&#64;0,0/pci1022,7460&#64;6/pci-ide&#64;b/ide&#64;0/cmdk&#64;0,0:a
775: ** result: device in the form c0d0s0 (string)
776: * FD~_TO~_PATH
777: ** arguments (2)
778: *** process ID (pid)
779: *** file descriptor
780: ** result: filename (string); int in the failure case (see also the {{code}}FD~_TO~_PATH{{/code}} [[displayTranslation>>#Display_Translation]] property)
781: * UID~_TO~_USERNAME
782: ** arguments (1)
783: *** user ID (uid)
784: ** result: username (string)
785: * NAME~_TO~_NTH
786: ** arguments (2)
787: *** string S
788: *** instance I (int)
789: ** result: combined form S#I (string)
790: 
791: The {{code}}tupleIndexes{{/code}} property indentifies the tuple members expected as arguments by the conversion.  The indexes are zero-based and correspond to the order that the tuple members are listed in your D program in square brackets.  Similarly, the {{code}}unconvertedIndex{{/code}} identifies the unconverted tuple member that should be displayed in case the conversion fails for any reason.  
792: 
793: The {{code}}cachingEnabled{{/code}} property, when {{code}}true{{/code}}, avoids expensive conversions by caching the results of previous conversions.  You should use the default value of {{code}}false{{/code}} if it is possible for the result of a conversion to vary for the same tuple values across a single Chime session.  
794: **required:** no  
795: **default:** none  
796: **example:** (converts a {{code}}uid{{/code}} in the first tuple position into a username, caching the results of previous conversions)  
797: 
798:           <void property="tupleConversion">
799:            <object class="org.opensolaris.chime.TupleConversionDescription">
800:             <void property="conversionName">
801:              <string>UID~_TO~_USERNAME</string>
802:             </void>
803:             <void property="tupleIndexes">
804:              <array class="int" length="1">
805:               <void index="0">
806:                <int>0</int>
807:               </void>
808:              </array>
809:             </void>
810:             <void property="unconvertedIndex">
811:              <int>0</int>
812:             </void>
813:             <void property="cachingEnabled">
814:              <boolean>true</boolean>
815:             </void>
816:            </object>
817:           </void>
818: 
819: ==== Value Type
820: 
821: **name:** valueType  
822: **type:** java.lang.String  
823: **range:**  
824: * NONE
825: * STACK
826: * BUCKET
827: * BUCKET~_FREQUENCY
828: * TIME~_PERCENT
829: * GROUP
830: **property of:** [[Column Description>>#Column_Description]]  
831: **description:** The value type tells Chime how to populate the column in many special cases.  For example, a tuple member generated by the DTrace {{code}}stack(){{/code}}, {{code}}ustack(){{/code}}, or {{code}}jstack(){{/code}} action will not display correctly unless you specify the {{code}}STACK{{/code}} value type.  This tells Chime to replace stack traces with tags that can reasonably fit in a table:  
832: 
833: ![Stack Value Type] (../screens_b/stack.gif)  
834: 
835: You can select the values of interest and display the tagged stack traces with the "View Selected Stack Traces" menu action:  
836: 
837: ![Selected Stack Traces] (../screens_b/stacktrace.gif)  
838: 
839: If you leave the stack trace viewer open, it updates automatically as the row selection in the source table changes.  
840: 
841: The {{code}}BUCKET{{/code}} and {{code}}BUCKET~_FREQUENCY{{/code}} value types are needed to display distributions generated by the DTrace {{code}}quantize(){{/code}} and {{code}}lquantize(){{/code}} actions.  The column that displays the bucket range ("Nanoseconds") needs to specify the {{code}}BUCKET{{/code}} value type, and the column that displays the distribution values ("Count") needs to specify the {{code}}BUCKET~_FREQUENCY{{/code}} value type:
842: 
843: ![Distribution Value Type] (../demarcated.gif)  
844: 
845: The {{code}}TIME_PERCENT{{/code}} value type is used to display the sum of elapsed time (the difference between two timestamps passed to the DTrace {{code}}sum(){{/code}} action) as a percentage of the last time interval (set by the "Interval in seconds" control in the lower left corner of the display).  The default format "{{code}}===0.==%{{/code}}" (resulting in values with no comma and zero to two decimal places such as 0.01%) can be overridden with the [[displayFormat>>#Display_Format]] property.  
846: 
847: The {{code}}GROUP{{/code}} value type is used to display a non-repeating view of another column specified by the [[sourceColumnName>>#Source_Column_Name]] property by echoing its values with the exception that a blank is used whenever a source value repeats the value in the row directly above it.  This makes it easier to scan tables visually for groups such as distributions.  In fact, the "Executable" column of the "Write Time Buckets" display pictured above uses the {{code}}GROUP{{/code}} value type to make each executable name appear only once for each distribution.  That grouping is reinforced by a black line separating each executable (see the [[demarcated>>#Demarcated]] property).  Note that the [[columns>>#Columns]] property must include an extra column with the redundant source executable data.  The name of the source column must differ from that of the column with the {{code}}GROUP{{/code}} value type so that the grouped column can distinctly reference it with the {{code}}sourceColumnName{{/code}} property.  The {{code}}sourceColumnName{{/code}} must match the [[name>>#Name]] property of the source column exactly.  Matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).  Since the source column is redundant, it is best to hide it from the display (as in the example pictured above) with the [[hidden>>#Hidden]] property.  
848: **required:** no (unless the data displayed by the column fits one of the special cases indicated by the range of value types)  
849: **default:** NONE  
850: **example:** (a column with the header "Executable" that displays non-repeating executables from a hidden source column named "Executable Name")  
851: 
852:      <object class="org.opensolaris.chime.ColumnDescription">
853:       <void property="name">
854:        <string>Executable</string>
855:       </void>
856:       <void property="valueType">
857:        <string>GROUP</string>
858:       </void>
859:       <void property="sourceColumnName">
860:        <string>Executable Name</string>
861:       </void>
862:      </object>
863: 
864: ==== Display Format
865: 
866: **name:** displayFormat  
867: **type:** java.lang.String  
868: **property of:** [[Column Description>>#Column_Description]]  
869: **description:** A display format string interpreted as a [[MessageFormat>>http://java.sun.com/j2se/1.5.0/docs/api/java/text/MessageFormat.html]] if the [[tupleIndex>>#Tuple_Index]] property is specified (i.e. if the column displays a tuple member) and interpreted as a [[DecimalFormat>>http://java.sun.com/j2se/1.5.0/docs/api/java/text/DecimalFormat.html]] otherwise (the {{code}}MessageFormat{{/code}} and {{code}}DecimalFormat{{/code}} links provide detailed format specifications).  For example, a display aggregated by CPU might specify a {{code}}displayFormat{{/code}} of "{{code}}cpu{0, number, integer}{{/code}}" to display a value of "1" as "cpu1".  
870: **required:** no  
871: **default:** none  
872: **example:** (displays an integer value with commas separating thousands, e.g. 1,000 instead of 1000)  
873: 
874:       <void property="displayFormat">
875:        <string>#,==0</string>
876:       </void>
877: 
878: ==== Source Column Name
879: 
880: **name:** sourceColumnName  
881: **type:** java.lang.String  
882: **property of:** [[Column Description>>#Column_Description]]  
883: **description:** Used by columns that present an alternate view of the data in another column (often [[hidden>>#Hidden]]~).  The {{code}}sourceColumnName{{/code}} must match the [[name>>#Name]] of the source column exactly.  Matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).  
884: **required:** no  
885: **default:** none  
886: **recommended:** Ignore unless directed otherwise by another property description.  (See also [[valueType>>#Value_Type]] {{code}}GROUP{{/code}} and [[renderingType>>#Rendering_Type]] {{code}}SPARKLINE{{/code}}.)  
887: **example:** See the {{code}}GROUP{{/code}} [[valueType>>#Value_Type]] example.  
888: 
889: ==== Column Data Key
890: 
891: **name:** dataKey  
892: **type:** java.lang.String  
893: **property of:** [[Column Description>>#Column_Description]]  
894: **description:** Overrides the display [[dataKey>>#Data_Key]] if specified (for this column only).  
895: **required:** no  
896: **default:** Use the {{code}}dataKey{{/code}} of the display.  
897: **recommended:** Ignore.  
898: 
899: ==== Rendering Type
900: 
901: **name:** renderingType  
902: **type:** java.lang.String  
903: **range:**  
904: * VALUE
905: * SPARKLINE
906: * BAR~_GRAPH
907: **property of:** [[Column Description>>#Column_Description]]  
908: **description:** The rendering type tells Chime how to render aggregation values resulting from DTrace aggregating actions such as {{code}}count(){{/code}} and {{code}}sum(){{/code}}.  This property does not apply to aggregation keys (columns that display tuple members).  For example, you can suppress bar graphs in Chime and display text-only numbers by specifying the {{code}}VALUE{{/code}} rendering type.  For background on the {{code}}SPARKLINE{{/code}} rendering type, see Edward Tufte’s [[sparklines discussion>>http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR&topic_id=1&topic=]] (Chime’s renderer, adequate for tables, does not support sparklines embedded in text components).  
909: **required:** no  
910: **default:** BAR~_GRAPH  
911: **example:** (A "History" column that presents an alternate view of data rendered as a bar graph in the "System Calls Per Second" column)
912: 
913:      <object class="org.opensolaris.chime.ColumnDescription">
914:       <void property="name">
915:        <string>History</string>
916:       </void>
917:       <void property="renderingType">
918:        <string>SPARKLINE</string>
919:       </void>
920:       <void property="aggregationName">
921:        <string>a</string>
922:       </void>
923:       <void property="plottable">
924:        <boolean>true</boolean>
925:       </void>
926:       <void property="plottableName">
927:        <string>System Calls Per Second</string>
928:       </void>
929:       <void property="sourceColumnName">
930:        <string>System Calls Per Second</string>
931:       </void>
932:      </object>
933: 
934: ![Sparkline View of System Calls] (../screens_a/syscalls.gif)  
935: 
936: ==== Aggregation Name
937: 
938: **name:** aggregationName  
939: **type:** java.lang.String  
940: **property of:** [[Column Description>>#Column_Description]]  
941: **description:** The name of the aggregation whose values are displayed in this column.  Chime assumes that all aggregations in your D program (specified by the [[programString>>#Program_String]] or [[programFileName>>#Program_File_Name]] property) share the same tuple, so this property does not apply to columns that display aggregation tuple members, only to columns that display values resulting from aggregating DTrace actions such as {{code}}count(){{/code}} or {{code}}sum(){{/code}}.  Chime can display data from multiple aggregations (assumed to have the same tuple) as long as you are careful to specify which aggregation supplies data to each column.  The specified name must be spelled exactly as it appears in your D program after (and not including) the {{code}}@{{/code}} aggregation symbol.  See the [[Aggregations>>http://docs.sun.com/app/docs/doc/817-6223/6mlkidlha?a=view]] chapter of the //Solaris Dynamic Tracing Guide// for details about aggregation naming.  
942: **required:** no  
943: **default:** "" (empty string identifying the anonymous aggregation)  
944: **example:** (specifies the aggregation in the D program statement {{code}}@a[execname] = count();{{/code}} )
945: 
946:       <void property="aggregationName">
947:        <string>a</string>
948:       </void>
949: 
950: ==== Minimum Value Range
951: 
952: **name:** minimumValueRange  
953: **type:** long  
954: **property of:** [[Column Description>>#Column_Description]]  
955: **description:** Used with the {{code}}BAR~_GRAPH{{/code}} [[renderingType>>#Rendering_Type]] to specify the initial range represented by the right edge of the cell containing the bar.  
956: **required:** no  
957: **default:** 1000  
958: **recommended:** The default is good for many values generated by the DTrace {{code}}count(){{/code}} action.  You can specify a much higher initial range for large values such as total bytes or total nanoseconds.  It’s just a matter of slightly better initial display behavior, since the range rescales automatically as needed (growing but never shrinking).  
959: **example:**  
960: 
961:       <void property="minimumValueRange">
962:        <string>1000000</string>
963:       </void>
964: 
965: ==== Value Per Second
966: 
967: **name:** valuePerSecond  
968: **type:** boolean  
969: **property of:** [[Column Description>>#Column_Description]]  
970: **description:** Indicates that the aggregation value displayed by this column should be displayed as a per-second averge.  This property only applies to the values of aggregating DTrace actions such as {{code}}count(){{/code}} and {{code}}sum(){{/code}}; it does not apply to aggregation keys (columns that display tuple members).  If {{code}}valuePerSecond{{/code}} is {{code}}true{{/code}}, Chime will divide each value by the number of seconds since the last interval.  Note that a per-second average only makes sense if the source aggregation (see [[aggregationName>>#Aggregation_Name]]~) is cleared at each interval (see the [[clearedAggregations>>#Cleared_Aggregations]] property).  If {{code}}valuePerSecond{{/code}} is {{code}}false{{/code}}, Chime displays either a total since the last interval, or a running total, depending on whether or not the source aggregation is cleared.  
971: **required:** no  
972: **default:** false  
973: **example:**  
974: 
975:       <void property="valuePerSecond">
976:        <boolean>true</boolean>
977:       </void>
978: 
979: ==== Units Description
980: 
981: **name:** unitsDescription  
982: **type:** org.opensolaris.chime.util.DisplayUnits$Description  
983: **property of:** [[Column Description>>#Column_Description]]  
984: **description:** Specifies that values in this column should be displayed as a number of units.  This involves a unit conversion resulting in a floating point number and also the appending of a unit label.  For example, 1536 bytes might be displayed as "1.5 KB".  A unit conversion is described by the following properties:  
985: * unitMultiple (int)
986: ** default: 1024
987: * unitLabels (java.lang.String[])
988: ** default: { null, "K", "M", "G", "T", "P", "E", "Z", "Y" }
989: * zeroLabeled (boolean)
990: ** default: false
991: * space (boolean)
992: ** default: true
993: * fixedUnitIndex (int)
994: ** default: -1
995: Chime will divide each value by the {{code}}unitMultiple{{/code}} until it obtains a value less than {{code}}unitMultiple{{/code}}.  Each time it divides, it increments an index into the {{code}}unitLabels{{/code}} array (starting at zero).  Typically the value //zero// does not need (and stands out better without) a unit label; the {{code}}zeroLabeled{{/code}} property is there in case that assumption is wrong.  Setting the {{code}}space{{/code}} property to {{code}}false{{/code}} results in something like "1.5K" instead of "1.5 K".  The {{code}}fixedUnitIndex{{/code}}, if non-negative, specifies that all values in the column should share the same unit label.  In that case, Chime will divide by the {{code}}unitMultiple{{/code}} as needed to achieve conversion to the unit specified by the zero-based index.  Assuming default units, a {{code}}fixedUnitIndex{{/code}} of 3 indicates that all values in the column should be converted to Gigavalues.  
996: **required:** no  
997: **default:** Chime does not perform unit conversions or add unit labels.  
998: **recommended:** If the column header specified by the [[name>>#Name]] property is something like "Bytes Read", then you can use the default labels "K", "M", "G", etc.  However, if the column header does not answer the question "Kilo-//what//" or "Mega-//what//", then you need to specify labels such as "KB", "MB", "GB", etc.  Also, the unit conversion results in a floating point number, so you can use the [[displayFormat>>#Display_Format]] property to specify the desired number of decimal places, etc.  
999: **example:** (Indicates that you want unit labels and accept all the defaults)  
1000: 
1001:       <void property="unitsDescription">
1002:        <object class="org.opensolaris.chime.util.DisplayUnits$Description">
1003:        </object>
1004:       </void>
1005: 
1006: ==== Display Translation
1007: 
1008: **name:** displayTranslation  
1009: **type:** java.lang.String  
1010: **range:**  
1011: * FD~_TO~_PATH
1012: **property of:** [[Column Description>>#Column_Description]]  
1013: **description:** A named function in Chime to convert a value for display.  The name must match one of the values in the //range// (above).  Currently, Chime supports only a single translation: {{code}}FD~_TO~_PATH{{/code}}.  This translation post-processes the {{code}}FD~_TO~_PATH{{/code}} [[tupleConversion>>#Tuple_Conversion]], and is always specified in conjunction with that conversion.  It handles the case where the conversion from file descriptor to pathname fails.  It does so by converting the {{code}}int{{/code}} file descriptor to a string of the form "FD 3".  This final translation is necessary to ensure that all the values in the column are comparable with each other, otherwise sorting the column with mixed string and integer data would throw an exception.  
1014: **required:** no  
1015: **default:** none  
1016: **example:**  
1017: 
1018:       <void property="tupleConversion">
1019:        <string>FD~_TO~_PATH</string>
1020:       </void>
1021:       <void property="displayTranslation">
1022:        <string>FD~_TO~_PATH</string>
1023:       </void>
1024: 
1025: ==== Numeric String
1026: 
1027: **name:** name  
1028: **type:** boolean  
1029: **property of:** [[Column Description>>#Column_Description]]  
1030: **description:** Indicates that Chime should respect the numeric values of consecutive digit substrings when sorting the string values of this column.  For example, if {{code}}numericString{{/code}} is {{code}}true{{/code}}, the values "c0d12s1" and "c0d2s1" will sort in the following ascending order:  
1031: 
1032: > c0d2s1  
1033: > c0d12s1  
1034: 
1035: rather than alphanumerically:
1036: 
1037: > c0d12s1  
1038: > c0d2s1  
1039: 
1040: (since "d1" comes ahead of "d2" alphanumerically)  
1041: **required:** no  
1042: **default:** false  
1043: **example:**  
1044: 
1045:       <void property="numericString">
1046:        <boolean>true</boolean>
1047:       </void>
1048: 
1049: ==== Rendering Hint
1050: 
1051: **name:** renderingHint  
1052: **type:** java.io.Serializable  
1053: **property of:** [[Column Description>>#Column_Description]]  
1054: **description:** A rendering hint of any type recognized by the column’s table cell renderer (determined by the [[renderingType>>#Rendering_Type]] property).  For example the renderer used with the default {{code}}BAR~_GRAPH{{/code}} rendering type recognizes the folowing hints:  
1055: * java.awt.Color (bar)
1056: * org.opensolaris.chime.util.ColorGradient
1057: ** java.awt.Color (bar at cell’s left edge)
1058: ** java.awt.Color (bar at cell’s right edge)
1059: * org.opensolaris.chime.util.Pair
1060: ** Color or ColorGradient (bar)
1061: ** Color (text)
1062: This lets you choose the color of the column’s bar graphs.  (Someday it might be neat to support a hint that makes the color vary across rows.)  The {{code}}SPARKLINE{{/code}} value type also recognizes the same hints, applying the color to the "spark".  You should not normally specify this hint for sparklines, however, since Chime automatically borrows the rendering hint from the sparkline’s source column (see [[sourceColumnName>>#Source_Column_Name]]~).  
1063: **required:** no  
1064: **default:** Chime paints bar graphs with a blue gradient (light blue on the left to medium blue on the right).  
1065: **recommended:** Colors are helpful for distinguishing column types when you have many value columns, but make sure you maintain adequate text contrast.  Using a darker color on the right works well with the default text color (background white).  If you’d rather avoid contrast issues, use the [[alignmentHint>>#Alignment_Hint]] property to put the text to the left of the bar graph with no overlap.  
1066: **example:** (paints bar graphs with a red gradient, light red on the left, darker red on the right; the fourth [[Color>>http://java.sun.com/j2se/1.5.0/docs/api/java/awt/Color.html]] parameter after red, green, and blue is optional and controls transparency, one way to adjust lightness against a white background)    
1067: 
1068:       <void property="renderingHint">
1069:        <object class="org.opensolaris.chime.util.ColorGradient">
1070:         <object class="java.awt.Color">
1071:          <int>204</int> <!~--0xCC~-->
1072:          <int>17</int>  <!~--0x11~-->
1073:          <int>0</int>   <!~--0x00~-->
1074:          <int>85</int>  <!~--0x55~-->
1075:         </object>
1076:         <object class="java.awt.Color">
1077:          <int>204</int> <!~--0xCC~-->
1078:          <int>17</int>  <!~--0x11~-->
1079:          <int>0</int>   <!~--0x00~-->
1080:          <int>255</int> <!~--0xFF~-->
1081:         </object>
1082:        </object>
1083:       </void>
1084: 
1085: ==== Alignment Hint
1086: 
1087: **name:** alignmentHint  
1088: **type:** java.lang.String  
1089: **range:**  
1090: * left
1091: * right
1092: * center
1093: **property of:** [[Column Description>>#Column_Description]]  
1094: **description:** A named alignment preference that overrides the default alignment of text within a table cell.  The name must match one of the values in the //range// (above).  In the case of the {{code}}BAR~_GRAPH{{/code}} [[valueType>>#Value_Type]],  the {{code}}left{{/code}} alignment hint value has the side effect of separating the text from the bar graph, avoiding contrast issues caused by overlap.  
1095: **required:** no  
1096: **default:** Chime left-aligns string values and right-aligns numeric values.  
1097: **example:**  
1098: 
1099:       <void property="alignmentHint">
1100:        <string>left</string>
1101:       </void>
1102: 
1103: ==== Plottable
1104: 
1105: **name:** plottable  
1106: **type:** boolean  
1107: **property of:** [[Column Description>>#Column_Description]]  
1108: **description:** Indicates whether the column supports the "Plot Over Time" menu action.  If {{code}}true{{/code}}, you can plot selected values of this column over time in another window displaying a line graph.  
1109: **required:** no  
1110: **default:** false  
1111: **recommended:** Set this property to {{code}}true{{/code}} in every column that displays data generated by an aggregating DTrace action such as {{code}}count(){{/code}} or {{code}}sum(){{/code}}.  If you have a column with the {{code}}SPARKLINE{{/code}} [[renderingType>>#Rendering_Type]] providing an alternate view of data in a column with the {{code}}BAR~_GRAPH{{/code}} rendering type, make only the sparkline column plottable.  
1112: **example:**
1113: 
1114:       <void property="plottable">
1115:        <boolean>true</boolean>
1116:       </void>
1117: 
1118: ![Plottable Column Data] (../screens_b/intrstat_time2.gif)  
1119: 
1120: ==== Plottable Name
1121: 
1122: **name:** plottableName  
1123: **type:** java.lang.String  
1124: **property of:** [[Column Description>>#Column_Description]]  
1125: **description:** Specifies a label for the data in this column when it appears in a line graph display plotting the data over time.  This property applies only to [[plottable>>#Plottable]] data and is used to label the Y-axis.    
1126: **required:** no  
1127: **default:** The [[name>>#Name]] of the column is used to label the Y-axis of a plot over time.  
1128: **recommended:** If the column uses the {{code}}SPARKLINE{{/code}} [[renderingType>>#Rendering_Type]] to present an alternate view of data in another column specified by the [[sourceColumnName>>#Source_Column_Name]] property, use the name of the source column as the {{code}}plottableName{{/code}}.  
1129: **example:** See the example under the [[renderingType>>#Rendering_Type]] property.  
1130: 
1131: ==== Hidden
1132: 
1133: **name:** hidden  
1134: **type:** boolean  
1135: **property of:** [[Column Description>>#Column_Description]]  
1136: **description:** Indicates whether or not the column should be hidden from the display.  If {{code}}true{{/code}}, the column is not visible, but its data remains available to use in new predicates (see the [[menuItems>>#Menu_Items]] property).  
1137: **required:** no  
1138: **default:** false  
1139: **recommended:** Typically you hide a column when data from DTrace needs to be converted for display (see the [[tupleConversion>>#Tuple_Conversion]] and [[displayKey>>#Display_Key]] properties), but you still need the original DTrace data in the hidden column to form predicates for use in new displays that aggregate data matching the selected rows by another attribute.  
1140: **example:**  
1141: 
1142:       <void property="hidden">
1143:        <boolean>true</boolean>
1144:       </void>
1145: 
1146: ==== Column Totaller Description
1147: 
1148: **name:** totallerDescription  
1149: **type:** org.opensolaris.chime.TotallerDescription  
1150: **property of:** [[Column Description>>#Column_Description]]  
1151: **description:** Describes how to display a column total.  If at least one column specifies a {{code}}columnTotallerDescription{{/code}}, a total row is added to the display at the bottom of the table.  If the display includes a total row, any column that does not specify a {{code}}columnTotallerDescription{{/code}} simply gets a blank total.  See [[Totaller Description>>#Totaller_Description]] for more detail.  
1152: **required:** no  
1153: **default:** none (Chime does not display a total row)  
1154: **example:** (Displays the total number of devices in the "Devices" column)  
1155: 
1156:       <void property="totallerDescription">
1157:        <object class="org.opensolaris.chime.TotallerDescription">
1158:         <void property="totalType">
1159:          <string>COUNT</string>
1160:         </void>
1161:         <void property="displayFormat">
1162:          <string>{0, number, integer} {0, choice,
1163:              0#devices|1#device|2#devices}</string>
1164:         </void>
1165:        </object>
1166:       </void>
1167: 
1168: ![Total Row Example] (../screens_c/intrstat.gif)  
1169: 
1170: === Menu Item Description
1171: 
1172: A menu item description specifies all the properties of a single drilldown menu item.  Drilldown is a feature of Chime that lets you add predicates to the running DTrace program in order to limit the data in a new display to values matching the selected rows of the previous display, and at the same time change the aggregation tuple to get a breakdown by another attribute.  See the [[menuItems>>#Menu_Items]] property, which specifies zero or more menu item descriptions.  
1173: 
1174: ==== Single Selection Name Format
1175: 
1176: **name:** singleSelectionNameFormat  
1177: **type:** java.lang.String  
1178: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1179: **description:** A format string used to include the key values of the selected row in the menu item name.  The format is specified by the [[MessageFormat>>http://java.sun.com/j2se/1.5.0/docs/api/java/text/MessageFormat.html]] class, and must use a single placeholder that expects a string argument (not a number), for example: "{0} by Function" where "{0}" is the placeholder for the selected Executable name.  If the [[displayKey>>#Display_Key]] includes more than a single column, Chime generates a string that combines the values of all the key columns in the selected row, for example "java, Process ID 725, FD 9" could replace "{0}" in a display with key columns named "Executable", "Process ID", and "File" (string values are considered self-explanatory, while numeric key values have the column name prepended for clarity).  If more than a single row is selected, it is impractical to include the selected keys in the menu item name, so the [[multiSelectionName>>#Multi_Selection_Name]] property is used instead to name the drilldown menu item.  
1180: **required:** yes  
1181: **example:**  
1182: 
1183:       <void property="singleSelectionNameFormat">
1184:        <string>{0} by Function</string>
1185:       </void>
1186: 
1187: ==== Multi Selection Name
1188: 
1189: **name:** multiSelectionName  
1190: **type:** java.lang.String  
1191: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1192: **description:** Specifies the name of the drilldown menu item when multiple rows are selected.  If a single row is selected, the [[singleSelectionNameFormat>>#Single_Selection_Name_Format]] property is used instead.  
1193: **required:** no  
1194: **default:** If you neglect to specify a {{code}}multiSelectionName{{/code}} for the menu item, Chime uses the {{code}}singleSelectionNameFormat{{/code}} with an empty string argument instead.  
1195: **example:**  
1196: 
1197:       <void property="singleSelectionNameFormat">
1198:        <string>by Function</string>
1199:       </void>
1200: 
1201: ==== New Columns
1202: 
1203: **name:** newColumns  
1204: **type:** org.opensolaris.chime.ColumnDescription[]  
1205: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1206: **description:** Specifies the columns needed to display the tuple members of the new aggregation key in exactly the same way columns are specified in the [[columns>>#Columns]] property, except that only key columns are specified for a menu item (value columns are retained as-is in the new display).  The new columns include all the columns named in the new [[uniqueKey>>#New_Unique_Key]] and [[displayKey>>#New_Display_Key]], and they replace all the columns included in the existing [[uniqueKey>>#Unique_Key]] and [[displayKey>>#Display_Key]].  
1207: **required:** yes  
1208: **example:** (Drilldown action specifies the new key as a single column for a display aggregated by function)  
1209: 
1210:         <void property="newColumns">
1211:          <array class="org.opensolaris.chime.ColumnDescription" length="1">
1212:           <void index="0">
1213:            <object class="org.opensolaris.chime.ColumnDescription">
1214:             <void property="tupleMember">
1215:              <string>probefunc</string>
1216:             </void>
1217:             <void property="name">
1218:              <string>Function</string>
1219:             </void>
1220:             <void property="tupleIndex">
1221:              <int>0</int>
1222:             </void>
1223:            </object>
1224:           </void>
1225:          </array>
1226:         </void>
1227: 
1228: ==== New Unique Key
1229: 
1230: **name:** uniqueKey  
1231: **type:** java.lang.String[]  
1232: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1233: **description:** Same as the [[uniqueKey>>#Unique_Key]] display property, except that it specifies the unique key of the new display launched by the menu item.  
1234: **required:** no  
1235: **default:** Chime uses the names of the new columns that specify a non-negative [[tupleIndex>>#Tuple_Index]] value, in order by tuple index.  
1236: **recommended:** Ignore.  Chime sets this property for you using the {{code}}tupleIndex{{/code}} property of the new columns.  
1237: 
1238: ==== New Display Key
1239: 
1240: **name:** newDisplayKey  
1241: **type:** java.lang.String[]  
1242: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1243: **description:** Same as the [[displayKey>>#Display_Key]] display property, except that it specifies the display key of the new display launched by the menu item.  
1244: **required:** no, unless a new column with a non-negative [[tupleIndex>>#Tuple_Index]] is [[hidden>>#Hidden]] so that its value can be displayed differently in another new column.  
1245: **default:** Chime uses the new unique key if a new display key is omitted.  
1246: 
1247: ==== New Initial Sort
1248: 
1249: **name:** initialSort  
1250: **type:** java.lang.String  
1251: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1252: **description:** Same as the [[initialSort>>#Initial_Sort]] display property, except that it specifies the initial sort of the new display launched by the menu item.  The new sort can use any of the new key columns and any of the value columns retained from the previous display.  The new display may use a different initial sort than the previous display.  
1253: **required:** no  
1254: **default:** If the initial sort of the previous display does not involve any key columns, it is retained in the new display.  Otherwise, the default is the same as the {{code}}initialSort{{/code}} display property default.  
1255: 
1256: ==== New Window Size
1257: 
1258: **name:** newWindowSize  
1259: **type:** java.awt.Dimension  
1260: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1261: **description:** Same as the [[size>>#Size]] display property, except that it specifies the size of the new display window launched by the menu item.  
1262: **required:** no  
1263: **default:** Chime uses the {{code}}size{{/code}} specified for the previous display (not the current window size if the previous display was resized).  
1264: **example:** (Specifies a new window 400 pixels wide by 300 pixels high.)  
1265: 
1266: {{{
1267:     <void property="newWindowSize">
1268:      <object class="java.awt.Dimension">
1269:       <int>400</int>
1270:       <int>300</int>
1271:      </object>
1272:     </void>
1273: }}}
1274: 
1275: ==== Nested Menu Items
1276: 
1277: **name:** menuItems  
1278: **type:** org.opensolaris.chime.MenuItemDescription[]  
1279: **property of:** [[Menu Item Description>>#Menu_Item_Description]]  
1280: **description:**  Same as the [[menuItems>>#Menu_Items]] display property, except that it specifies the drilldown menu items of the new display launched by the menu item.  
1281: **required:** no  
1282: **default:** The new display has no drilldown menu items, even if the previous display does have them.  
1283: 
1284: === Totaller Description
1285: 
1286: ==== Total Type
1287: 
1288: **name:** totalType  
1289: **type:** java.lang.String  
1290: **range:**  
1291: * SUM
1292: * COUNT
1293: * UNIQUE~_COUNT
1294: **property of:** [[Totaller Description>>#Totaller_Description]]  
1295: **description:** A named total type specifying the function used to total the values of a column.  The name must match one of the recognized values in the //range// (above).  
1296: **required:** no  
1297: **default:** Chime does not display a total for the column.  
1298: **recommended:** Use {{code}}SUM{{/code}} for values generated by DTrace aggregating actions such as {{code}}count(){{/code}} or {{code}}sum(){{/code}}.  Use {{code}}UNIQUE~_COUNT{{/code}} for tuple members.  If you don’t need to display the number of //different// non-blank tuple member values, {{code}}COUNT{{/code}} is more efficent: it simply displays the number of //non-blank// values.  
1299: **example:**  
1300: 
1301:         <void property="totalType">
1302:          <string>SUM</string>
1303:         </void>
1304: 
1305: ==== Total Display Format
1306: 
1307: **name:** displayFormat  
1308: **type:** java.lang.String  
1309: **property of:** [[Totaller Description>>#Totaller_Description]]  
1310: **description:** Same as the [[displayFormat>>#Display_Format]] column property, except that it applies to the column total, which is always numeric.  The single format placeholder for a column total must always specify a //number//.  
1311: **required:** no  
1312: **default:** If the [[totalType>>#Total_Type]] is {{code}}SUM{{/code}}, Chime displays the column total using the same {{code}}displayFormat{{/code}} specified for column values.  Otherwise, Chime displays an unformatted number.  
1313: **recommended:** You don’t need to specify a number format for aggregation value totals, since the number format automatically matches that of the column values.  For tuple member counts, you should specify a //choice// [[MessageFormat>>http://java.sun.com/j2se/1.5.0/docs/api/java/text/MessageFormat.html]] that labels the total in way that is consistent with the column header and that includes both the singular and plural form; see the //example// below.  
1314: **example:** (Counts the number of different values in the "CPU" column)  
1315: 
1316:         <void property="totalType">
1317:          <string>UNIQUE_COUNT</string>
1318:         </void>
1319:         <void property="displayFormat">
1320:          <string>{0, number, integer} {0, choice, 0#cpus|1#cpu|2#cpus}</string>
1321:         </void>
1322: 
1323: ==== Total Units Description
1324: 
1325: **name:** unitsDescription  
1326: **type:** org.opensolaris.chime.util.DisplayUnits$Description  
1327: **property of:** [[Totaller Description>>#Totaller_Description]]  
1328: **description:** Same as the [[unitsDescription>>#Units_Description]] column property, except that it applies to the column total.  This property applies only to the {{code}}SUM{{/code}} [[totalType>>#Total_Type]].  
1329: **required:** no  
1330: **default:** Chime displays the column total using the same {{code}}unitsDescription{{/code}} specified for column values.  
1331: **recommended:** Ignore.  Chime automatically applies the unit labels of the column to the column total.  
1332: 
1333: ==== Column Test Description
1334: 
1335: **name:** columnTestDescription  
1336: **type:** org.opensolaris.chime.ColumnTestDescription  
1337: **property of:** [[Totaller Description>>#Totaller_Description]]  
1338: **description:** Specifies a column test that may supply multiple arguments to the [[displayFormat>>#Total_Display_Format]] (allowing a display format with multiple placeholders), and additionally supplying one or more alternate display formats that may be used depending on a condition tested by a named test implementation on a named column.  This property currently applies only when the [[totalType>>#Total_Type]] is {{code}}UNIQUE~_COUNT{{/code}} and the totalled column has the [[valueType>>#Value_Type]] {{code}}GROUP{{/code}}; it is described with the following properties:  
1339: * columnName (java.lang.String)
1340: * testType (java.lang.String)
1341: ** NON~_BLANK
1342: * conditionalDisplayFormats (java.lang.String[])
1343: The //columnName// property names the column to be tested.  The specified name must exactly match the [[name>>#Name]] of a column specified in the [[columns>>#Columns]] display property.  The {{code}}totalType{{/code}} property names the test implementation.  The test name must match one of the recognized values in the range listed under {{code}}testType{{/code}} (above).  The {{code}}conditionalDisplayFormats{{/code}} property specifies the alternate format or formats usable depending on the number of values in the column that pass or fail the test.  In the case of the {{code}}NON~_BLANK{{/code}} test type, a single alternate format is supported, used only when all values in the specified column pass the test; otherwise, the {{code}}NON~_BLANK{{/code}} test supplies two arguments to the specified [[displayFormat>>#Total_Display_Format]]: first, the number of values passing the test, and second, the total number of values.  
1344: **required:** no  
1345: **default:** A single argument to a single display format is enough (//please...//).  
1346: **example:** (Specifies a total format as "//n / t//": //n// non-empty distributions out of //t// total distributions, or simply as "//n//" if all distributions are non-empty.  In the display pictured below, the total is "11 / 19 Executables", but if all 19 distributions were non-empty, it would be simply "19 Executables")  
1347: 
1348:       <void property="totallerDescription">
1349:        <object class="org.opensolaris.chime.TotallerDescription">
1350:         <void property="totalType">
1351:          <string>UNIQUE~_COUNT</string>
1352:         </void>
1353:         <void property="displayFormat">
1354:          <string>{0, number, integer} / {1, number, integer} {1, choice,
1355:              0#executables|1#executable|2#executables}</string>
1356:         </void>
1357:         <void property="columnTestDescription">
1358:          <object class="org.opensolaris.chime.ColumnTestDescription">
1359:           <void property="columnName">
1360:            <string>File Descriptor</string>
1361:           </void>
1362:           <void property="testType">
1363:            <string>NON~_BLANK</string>
1364:           </void>
1365:           <void property="conditionalDisplayFormats">
1366:            <array class="java.lang.String" length="1">
1367:             <void index="0">
1368:              <string>{0, number, integer} {0, choice,
1369:                  0#executables|1#executable|2#executables}</string>
1370:             </void>
1371:            </array>
1372:           </void>
1373:          </object>
1374:         </void>
1375:        </object>
1376:       </void>
1377: 
1378: ![Conditional Total Format] (../screens_c/cond_total.gif)  
1379: 
1380: == A Simple Display Example
1381: 
1382: Here’s an example that specifies the absolute minimum properties: a **title**, a **DTrace program**, and **2 columns**:  
1383: 
1384: [[title>>#Title]] "System Calls"  
1385: [[programString>>#Program_String]] "syscall:::entry {@[execname] = count() }"  
1386: [[columns>>#Columns]]  
1387: > //[0]//  
1388: > [[name>>#Name]] "Executable"  
1389: > [[tupleIndex>>#Tuple_Index]] 0  
1390: > //[1]//  
1391: > [[name>>#Name]] "System Calls"  
1392: 
1393: This is a bit more verbose in XML ([[simple.xml>>../descriptions/simple.xml]]~):  
1394: 
1395: {{{
1396:     <java version="1.5.0-beta3" class="java.beans.XMLDecoder">
1397:      <object class="org.opensolaris.chime.DisplayDescription">
1398:       <void property="title">
1399:        <string>System Calls</string>
1400:       </void>
1401:       <void property="programString">
1402:        <string>syscall:::entry { @[execname] = count(); }</string>
1403:       </void>
1404:       <void property="columns">
1405:        <array class="org.opensolaris.chime.ColumnDescription" length="2">
1406:         <void index="0">
1407:          <object class="org.opensolaris.chime.ColumnDescription">
1408:           <void property="name">
1409:            <string>Executable</string>
1410:           </void>
1411:           <void property="tupleIndex">
1412:            <int>0</int>
1413:           </void>
1414:          </object>
1415:         </void>
1416:         <void index="1">
1417:          <object class="org.opensolaris.chime.ColumnDescription">
1418:           <void property="name">
1419:            <string>System Calls</string>
1420:           </void>
1421:          </object>
1422:         </void>
1423:        </array>
1424:       </void>
1425:      </object>
1426:     </java>
1427: }}}
1428: 
1429: ![Simple Example] (../screens_b/simple.gif)  
1430: 
1431: The initial sort in this example defaults to ascending by aggregation key (see [[initialSort>>#Initial_Sort]]~).  The display does not support plotting over time in a line graph (see [[plottable>>#Plottable]]~), nor does it support drilldown (see [[menuItems>>#Menu_Items]]~).  The "System Calls" column is a simple count across each interval.  To display a per-second average instead, you would change the column name to "System Calls Per Second" and set the [[valuePerSecond>>#Value_Per_Second]] column property to {{code}}true{{/code}}.  If you wanted a total row, all you would have to do is specify a [[totallerDescription>>#Totaller_Description]] for one or both columns.
OpenSolaris

Top Menu

Wiki code for XML Properties

Search

Collectives

Community Group

Project

User Group

Subsites

Project dtrace-chime Pages
