Each Chime display is described in XML as a set of properties recognized by Chime. Chime provides a wizard as well as command line options 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.
To add a new display, you can copy and modify an existing .xml description from the display_descriptions directory. A description looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<java version="1.5.0-beta3" class="java.beans.XMLDecoder">
<object class="org.opensolaris.chime.DisplayDescription">
... display properties ...
</object>
</java>
The display properties may be specified in any order.
Each property is documented in the following format:
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 <void property="title">.
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 <int>2</int>.
range: The range of valid values for the property. For example, range may a include a list of strings that Chime recognizes as valid values of a property of type java.lang.String, along with a short description of how each listed value affects the display.
property of: A link back to the object that contains the property; the object is one of Display Description, Column Description, Menu Item Description, or Totaller Description.
description: A complete description of the property.
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)
default: If the property is not required, the value used by default when the property is omitted.
recommended: A tip about how to use the property, for example "Ignore" if the property is advanced or seldom specified.
since: The version of Chime (listed in the Change Log) that added the property (assumed to be the initial release of Chime if omitted).
example: An example XML block that specifies the property.
A display description specifies all the properties of the display, including two or more columns (see Column Description) and zero or more menu items (see Menu Item Description). Every display has columns. A display with menuItems 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 execname might allow you to select "Xorg" and aggregate its system calls by function name. The menuItems 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 property to true.
The following documents each of the Chime display properties:
name: version
type: int
property of: Display Description
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).
required: no
default: none
recommended: Copy the version property from any of the display descriptions included with Chime.
example:
<void property="version">
<int>2</int>
</void>
name: title
type: java.lang.String
property of: Display Description
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.
required: yes
example:
<void property="title">
<string>System Calls</string>
</void>
name: longDescription
type: java.lang.String
property of: Display Description
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 < for < and > for >. (Note that the wizard, in step 6. Provide a Description, escapes angle brackets automatically.)
required: no
default: "No Description Available" appears in the Description pane.
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 it with others.
since: 1.4.10 (16 Aug 2006)
example:
<void property="longDescription">
<string><html>Displays <b>three</b> columns:
<ol><li>Executable</li><li>History</li>
<li>Calls Per Second</li></ol>The
lt;i>cyan</i> <u>line</u> in the <font
face="Courier">History</font> column indicates the
relative magnitude of the sparkline (the vertical scale determined by
its maximum value).</html>
</string>
</void>
name: subtitles
type: org.opensolaris.chime.util.NameValuePair[]
property of: Display Description
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 subtitles 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 is simply incorporated into the 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".
required: no
default: none
recommended: Ignore, unless the described display uses a predicate that
is too complicated to convey in the title property and the display will
not make sense without a label for the predicate.
name: columns
type: org.opensolaris.chime.ColumnDescription[]
property of: Display Description
description: Column descriptions used to generate the columns at the corresponding indices 0 .. (n – 1) 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 for more detail.
required: yes
example: (2 columns: "Executable" and "Count")
<void property="columns">
<array class="org.opensolaris.chime.ColumnDescription" length="2">
<void index="0">
<object class="org.opensolaris.chime.ColumnDescription">
<void property="name">
<string>Executable</string>
</void>
… remaining properties omitted …
</object>
</void>
<void index="1">
<object class="org.opensolaris.chime.ColumnDescription">
<void property="name">
<string>Count</string>
</void>
… remaining properties omitted …
</object>
</void>
</array>
</void>
name: uniqueKey
type: java.lang.String[]
property of: Display Description
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 property of a Column Description included in the columns property. Column name matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).
required: no
default: The unique key defaults to the names of the columns that specify a non-negative tupleIndex value, in order by tuple index.
recommended: Ignore. As of version 1.4.36, the unique key is generated automatically even in special cases like distributions generated by the DTrace quantize() and lquantize() actions.
name: displayKey
type: java.lang.String[]
property of: Display Description
description: Names of the columns used to display the uniqueKey column values, if the displayed columns differ from those of the uniqueKey. For example, if the unique key is ["User ID"], and if the column named in the unique key is hidden (see the 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 property of a Column Description included in the columns property. Column name matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).
required: no
default: Chime uses the uniqueKey, except that when a column in the unique key is hidden, Chime finds the column whose sourceColumnName property references the hidden column to display in its place.
recommended: Ignore. As of version 1.4.36, the display key is generated automatically.
name: initialSort
type: org.opensolaris.chime.util.TableSortCriteria[]
property of: Display Description
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 property of a Column Description included in the 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 (true or false).
required: no
default: Chime sorts in ascending order by the columns named in the displayKey, or by the columns named in the uniqueKey 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.
recommended: Consider sorting in descending order by the aggregated numeric value associated with each tuple.
example: (sort by Calls Per Second descending)
<void property="initialSort">
<array class="org.opensolaris.chime.util.TableSortCriteria" length="1">
<void index="0">
<object class="org.opensolaris.chime.util.TableSortCriteria">
<string>Calls Per Second</string>
<boolean>false</boolean>
</object>
</void>
</array>
</void>
name: demarcated
type: boolean
property of: Display Description
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 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 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 GROUP under the valueType property).
required: no
default: false
recommended: If your D program uses the quantize() or lquantize() actions, set the demarcated property to true to group the resulting value distributions. You will also need to specify the BUCKET and BUCKET_FREQUENCY value types for the columns that display the bucket range and the distributions values, respectively. (See the valueType property.)
example:
<void property="demarcated">
<boolean>true</boolean>
</void>
name: tandemRanges
type: java.lang.String[][]
property of: Display Description
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 column property (see the 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.
required: no
default: none
example:
<void property="tandemRanges">
<array class="[Ljava.lang.String;" length="2">
<void index="0">
<array class="java.lang.String" length="2">
<void index="0">
<string>Reads Per Second</string>
</void>
<void index="1">
<string>Writes Per Second</string>
</void>
</array>
</void>
<void index="1">
<array class="java.lang.String" length="2">
<void index="0">
<string>Total Read Time</string>
</void>
<void index="1">
<string>Total Write Time</string>
</void>
</array>
</void>
</array>
</void>
name: stackInstanceLimit
type: int
property of: Display Description
description: Limits the number of unique instances generated by the stack(), ustack(), and jstack() actions, aborting the display with org.opensolaris.chime.TooManyInstancesException 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).
required: no
default: 2,000
recommended: Ignore.
name: dataKey
type: java.lang.String
property of: Display Description
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 property serves as the dataKey. Children of a display launched by choosing a drilldown action on any row selection inherit the data key of the display that launched them.
required: no
default: same as the title property
recommended: Ignore.
name: size
type: java.awt.Dimension
property of: Display Description
description: Initial size of the window containing the display.
required: no
default: 400x300 (pixels wide by pixels high)
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 quantize() and lquantize() actions work better with a height around 700 pixels. Displays with many columns require a wider display window.
example:
<void property="size">
<object class="java.awt.Dimension">
<int>400</int>
<int>300</int>
</object>
</void>
name: programString
type: java.lang.String
property of: Display Description
description: The full contents (text) of the D program compiled by DTrace to enable probes and generate data for the display.
required: yes (unless the programFileName property is specified instead)
example:
<void property="programString">
<string>syscall:::entry { @[execname] = count(); }</string>
</void>
name: programFileName
type: java.lang.String
property of: Display Description
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 display_descriptions directory (or the directory specified by the -d 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 display_descriptions (or the directory specified by the -d option).
required: yes (unless the programString property is specified instead)
example:
<void property="programFileName">
<string>intrstat.d</string>
</void>
name: substitutions
type: org.opensolaris.chime.util.NameValuePair[]
property of: Display Description
description: Supports improved D program reusability by specifying program placeholders and values to substitute for those placeholders. Substitutions are similar to macro arguments in D, except that substitutions are performed before the program is compiled and behind the scenes without prompting the user. (See the macroArgs 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:
??PROBE??
??P0??
{
@a[??T??] = ??ACTION??(??ARGS??);
}
??P0
??T0 execname
??ACTION count
??ARGS
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 substitutions property of the display description. The predicates (P0, P1, P2, …) and the aggregation tuple (T) are special placeholder tags that should not be specified in the substitions property. Instead, use the predicates property for predicates and the tupleMember column property for tuple members. (T0, T1, T2, …) are also special tags for listing default tuple member values at the end of the program. Each allows the tupleMember 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 ??P0 without a subsequent value makes it unnecessary to specify the predicates property; the default value of no predicate is already given in the program.
A program like the one above is specified using the programString or programFileName property. Note that in order to support drilldown with the menuItems property, your D program must use the special substitution placeholders for predicates (P0, P1, P2, etc.) and aggregation tuple (T) described above. Other tags (such as PROBE, ACTION, and ARGS in the example above) are completely up to you and may be spelled however you like (these are the tags you specify in the substitutions property).
The name of each NameValuePair 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 Object, and its toString() value overwrites the matched placeholder.
required: no (unless the specified D program uses placeholders other than predicates and aggregation tuple without listing default values)
default: none
example: (specifies the probe syscall:::entry for the only substitution placeholder without a default value in the example above)
<void property="substitutions">
<array class="org.opensolaris.chime.util.NameValuePair" length="1">
<void index="0">
<object class="org.opensolaris.chime.util.NameValuePair">
<string>PROBE</string>
<object class="org.opensolaris.os.dtrace.ProbeDescription">
<string>syscall</string>
<string></string>
<string></string>
<string>entry</string>
</object>
</object>
</void>
</array>
</void>
name: predicates
type: java.lang.String[]
property of: Display Description
description: Supports improved D program reusability by replacing predicate placeholders ??P0??, ??P1??, ??P2??, 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 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 column preoprty, supports drilldown menuItems). 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 -> needs to written -> and the bitwise AND operator & needs to written as &. The specified predicate strings must omit the surrounding forward slashes ( / ); these are added by Chime.
required: no (unless the D program specified by the programString or programFileName property uses a predicate placeholder (??P0??, ??P1??, ??P2??, …) without listing a default
value)
default: none
example: (replaces ??P0?? with the predicate /args[0]->b_flags & B_READ/ and ??P1?? with the predicate /args[0]->b_flags & B_WRITE/ )
<void property="predicates">
<array class="java.lang.String" length="2">
<void index="0">
<string>args[0]->b_flags & B_READ</string>
</void>
<void index="1">
<string>args[0]->b_flags & B_WRITE</string>
</void>
</array>
</void>
name: options
type: org.opensolaris.dtracex.Option[]
property of: Display Description
description: Specifies DTrace options to use with the program specified by the programString or programFileName property. Note that the aggrate option sets the initial value of the "Interval in seconds" control in the lower left corner of the display.
required: no
default: Chime uses the following default options:
bufsize 256 KBaggsize 256 KBaggrate 1 second
example: (
aggrate 4m, bufsize 4m, dynvarsize 1m )
<void property="options">
<array class="org.opensolaris.os.dtrace.Option" length="3">
<void index="0">
<object class="org.opensolaris.os.dtrace.Option">
<string>bufsize</string>
<string>4m</string>
</object>
</void>
<void index="1">
<object class="org.opensolaris.os.dtrace.Option">
<string>aggsize</string>
<string>4m</string>
</object>
</void>
<void index="2">
<object class="org.opensolaris.os.dtrace.Option">
<string>dynvarsize</string>
<string>1m</string>
</object>
</void>
</array>
</void>
name: clearedAggregations
type: java.lang.String[]
property of: Display Description
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 or programFileName property minus the initial @. For example, if your program contains the line @counts[execname] = count(); use the name "counts". If the aggregation is unnamed ( @[execname] = counts(); ) use the empty string ( <string></string> ). 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 clearedAggregations property is omitted. Specify an empty array to display only running totals.
required: no
default: Chime clears all aggregations by default.
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 column property to true (see columns), otherwise you get the total accumulated since the last interval instead of a per-second average.
example: (displays only running totals)
<void property="clearedAggregations">
<array class="java.lang.String" length="0"/>
</void>
name: movingAverageCount
type: int
property of: Display Description
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.
required: no
default: 0
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.
example: (average with the three previous values)
<void property="movingAverageCount">
<int>4</int>
</void>
name: macroArgs
type: org.opensolaris.dtracex.MacroArgument[]
property of: Display Description
description: Specifies macro arguments to the D program specified by the programString or programFileName property. Macro argument variables in your D program are integers preceded by the $ character (or $$ 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 property). The macro argument specified at array index 0 replaces $1 or $$1, the macro argument specified at array index 1 replaces $2 or $$2, 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 $1 in / pid == $1 /. After the name, each macro argument specifies a default argument value (also a string), which may be null. If at least one macro argument has a null value, or if the promptMacroArgs property is true, Chime will prompt you for macro argument values before starting the display. At that time you can overwrite any specified defaults.
required: no (unless your D program contains macro variables)
default: none
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.
example: ( prompts for execname == $$1 and fbt:$$2::entry without providing default values )
<void property="macroArgs">
<array class="org.opensolaris.dtracex.MacroArgument" length="2">
<void index="0">
<object class="org.opensolaris.dtracex.MacroArgument">
<string>Executable</string>
<null/>
</object>
</void>
<void index="1">
<object class="org.opensolaris.dtracex.MacroArgument">
<string>Module</string>
<null/>
</object>
</void>
</array>
</void>
The program started after you enter "java" and "genunix"
name: promptMacroArgs
type: boolean
property of: Display Description
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 property) in your D program. If at least one macroArgs element does not specify a default value, Chime will display a prompt regardless of the value of this property.
required: no
default: false
example:
<void property="promptMacroArgs">
<boolean>true</boolean>
</void>
name: target
type: java.lang.String
property of: Display Description
description: A target process 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 dtrace(1M) -c option). If a process ID is specified, Chime will grab the specified process and cache its symbol tables (same as the dtrace(1M) -p option). In either case, the pid of the target process replaces the $target macro variable in your D program.
required: no
default: none
recommended: Set the promptTarget property to true if you want the user to supply the target command or pid. In that case, specify the target property only if you want to provide a default value for the prompt.
example: (traces the date command)
<void property="target">
<string>date</string>
</void>
name: promptTarget
type: boolean
property of: Display Description
description: Indicates whether Chime should prompt the user for the value of the $target macro variable in your D program. If true, Chime will prompt the user even if a default value is already specified by the target property. The prompt requests either a command to execute or the pid of an existing process.
required: no (unless your D program contains the $target macro variable and the target property does not specify its value)
default: false
example:
<void property="promptTarget">
<boolean>true</boolean>
</void>
name: menuItems
type: org.opensolaris.chime.MenuItemDescription[]
property of: Display Description
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 execname shows a high number of system calls made by Xorg:
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 probefunc instead of execname and adds the predicate /execname == "Xorg"/:
Here the "Xorg" count of the previous display is broken down by function.
A column from the original display is dropped from the drilldown display for any of the following reasons:
- its tupleIndex is non-negative
- its name is part of the uniqueKey or displayKey
- its sourceColumnName is part of the
uniqueKey or displayKey
Each menu item in the menuItems property specifies many properties of its own. For example, new columns must be described just as they were in the columns property of the previous display. See Menu Item Description for a complete list of menu item properties.
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.
required: no
default: none
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: ??T?? for the tuple, and ??P0??, ??P1??, etc. for one or more predicates (see the substitutions, tupleMember, and predicates properties). For an example of nested menu items, see the installed syscall.xml file in the display_descriptions directory.
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.)
<void property="menuItems">
<array class="org.opensolaris.chime.MenuItemDescription" length="1">
<void index="0">
<object class="org.opensolaris.chime.MenuItemDescription">
<void property="newColumns">
<array class="org.opensolaris.chime.ColumnDescription" length="1">
<void index="0">
<object class="org.opensolaris.chime.ColumnDescription">
<void property="tupleMember">
<string>probefunc</string>
</void>
<void property="name">
<string>Function</string>
</void>
<void property="tupleIndex">
<int>0</int>
</void>
</object>
</void>
</array>
</void>
<void property="singleSelectionNameFormat">
<string>{0} by Function</string>
</void>
<void property="multiSelectionName">
<string>By Function</string>
</void>
</object>
</void>
</array>
</void>
A column description specifies all the properties of a single column. See the columns display property and the newColumns menu item property; both specify column descriptions.
name: name
type: java.lang.String
property of: Column Description
description: The name of the column appearing in the displayed column header.
required: yes
example:
<void property="name">
<string>Executable</string>
</void>
name: tupleIndex
type: int
property of: Column Description
description: The zero-based index of the tuple member in the D program specified by the programString or programFileName property whose values are displayed in this column. For example, if you are aggregating @[pid, probefunc] = count(); then the column displaying the pid values might be named "Process ID", and the column displaying the probefunc values might be named "Function".
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)
example: (a column that displays the values of the first tuple member)
<void property="tupleIndex">
<int>0</int>
</void>
name: tupleMember
type: java.lang.String
property of: Column Description
description: A program variable name used to fill in the tuple member whose values are displayed by this column. The tupleMember values of one or more columns collectively replace the ??T?? substitution variable in your D program (see the substitutions property); each tupleMember fills in the tuple position specified by the column's tupleIndex property. For example, if the tupleMember is probefunc and the tupleIndex is 1, then @[??T??] is replaced by @[< … > , probefunc] (the first tuple member < … > needs to be filled in by another column specifying a tupleMember at tupleIndex 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, args[1]->dev_pathname needs to be specified as
<string>args[1]->dev_pathname</string>
Your D program (specified by the programString or programFileName property) can supply default tuple members for the ??T?? substitution variable. For example
??PROBE??
??P0??
{
@a[??T??] = ??ACTION??(??ARGS??);
}
??P0
??T0 execname
??ACTION count
??ARGS
In the example above, execname is the default value for the tuple member at index 0, so you may omit the tupleMember property if tupleIndex is 0 (accepting the default value execname).
required: no (unless your D program uses the ??T?? substitution variable without providing a default for the tuple member at the position specified by the tupleIndex property)
default: none (unless a default is specified in your D program after ??T0 for the first tuple member, or after ??T1 for the second tuple member, etc.)
example: (replaces the ??T?? substitution variable with a tuple whose member at the index specified by the tupleIndex property is execname)
<void property="tupleMember">
<string>execname</string>
</void>
name: tupleConversion
type: org.opensolaris.chime.TupleConversionDescription
property of: Column Description
description: A conversion of DTrace tuple values into a form more suitable for display. For example, you may want to display a uid 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 (or less commonly, the displayTranslation) property instead. Note that if you want to support drilldown (see the menuItems property), you will also need a 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, while the uniqueKey uses the hidden column with the unconverted DTrace values.
A tuple conversion is described with the following properties:
- conversionName (java.lang.String)
- tupleIndexes (int[])
- unconvertedIndex (int)
- cachingEnabled (boolean)
The conversionName 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 tupleIndexes property in the order given below):
- ADDR_TO_KERNEL_FUNCTION
- arguments (1)
- 32- or 64-bit integer address
- result: function name (string)
- ADDR_TO_USER_FUNCTION
- arguments (2)
- process ID (pid)
- 32- or 64-bit integer address
- result: function name (string)
- DEVPATH_TO_cNdNsN
- arguments (1)
- device path (string) in the long form such as /devices/pci@0,0/pci1022,7460@6/pci-ide@b/ide@0/cmdk@0,0:a
- result: device in the form c0d0s0 (string)
- FD_TO_PATH
- arguments (2)
- process ID (pid)
- file descriptor
- result: filename (string); int in the failure case (see also the
FD_TO_PATH displayTranslation property)
- UID_TO_USERNAME
- arguments (1)
- result: username (string)
- NAME_TO_NTH
- arguments (2)
- string S
- instance I (int)
- result: combined form S#I (string)
The tupleIndexes 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 unconvertedIndex identifies the unconverted tuple member that should be displayed in case the conversion fails for any reason.
The cachingEnabled property, when true, avoids expensive conversions by caching the results of previous conversions. You should use the default value of false if it is possible for the result of a conversion to vary for the same tuple values across a single Chime session.
required: no
default: none
example: (converts a uid in the first tuple position into a username, caching the results of previous conversions)
<void property="tupleConversion">
<object class="org.opensolaris.chime.TupleConversionDescription">
<void property="conversionName">
<string>UID_TO_USERNAME</string>
</void>
<void property="tupleIndexes">
<array class="int" length="1">
<void index="0">
<int>0</int>
</void>
</array>
</void>
<void property="unconvertedIndex">
<int>0</int>
</void>
<void property="cachingEnabled">
<boolean>true</boolean>
</void>
</object>
</void>
name: valueType
type: java.lang.String
range:
- NONE
- STACK
- BUCKET
- BUCKET_FREQUENCY
- TIME_PERCENT
- GROUP
property of: Column Description
description: The value type tells Chime how to populate the column in many special cases. For example, a tuple member generated by the DTrace
stack(),
ustack(), or
jstack() action will not display correctly unless you specify the
STACK value type. This tells Chime to replace stack traces with tags that can reasonably fit in a table:
You can select the values of interest and display the tagged stack traces with the "View Selected Stack Traces" menu action:
If you leave the stack trace viewer open, it updates automatically as the row selection in the source table changes.
The BUCKET and BUCKET_FREQUENCY value types are needed to display distributions generated by the DTrace quantize() and lquantize() actions. The column that displays the bucket range ("Nanoseconds") needs to specify the BUCKET value type, and the column that displays the distribution values ("Count") needs to specify the BUCKET_FREQUENCY value type:
The TIME_PERCENT value type is used to display the sum of elapsed time (the difference between two timestamps passed to the DTrace sum() 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 "###0.##%" (resulting in values with no comma and zero to two decimal places such as 0.01%) can be overridden with the displayFormat property.
The GROUP value type is used to display a non-repeating view of another column specified by the sourceColumnName 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 GROUP 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 property). Note that the 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 GROUP value type so that the grouped column can distinctly reference it with the sourceColumnName property. The sourceColumnName must match the 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 property.
required: no (unless the data displayed by the column fits one of the special cases indicated by the range of value types)
default: NONE
example: (a column with the header "Executable" that displays non-repeating executables from a hidden source column named "Executable Name")
<object class="org.opensolaris.chime.ColumnDescription">
<void property="name">
<string>Executable</string>
</void>
<void property="valueType">
<string>GROUP</string>
</void>
<void property="sourceColumnName">
<string>Executable Name</string>
</void>
</object>
name: displayFormat
type: java.lang.String
property of: Column Description
description: A display format string interpreted as a MessageFormat if the tupleIndex property is specified (i.e. if the column displays a tuple member) and interpreted as a DecimalFormat otherwise (the MessageFormat and DecimalFormat links provide detailed format specifications). For example, a display aggregated by CPU might specify a displayFormat of "cpu{0, number, integer}" to display a value of "1" as "cpu1".
required: no
default: none
example: (displays an integer value with commas separating thousands, e.g. 1,000 instead of 1000)
<void property="displayFormat">
<string>#,##0</string>
</void>
name: sourceColumnName
type: java.lang.String
property of: Column Description
description: Used by columns that present an alternate view of the data in another column (often hidden). The sourceColumnName must match the name of the source column exactly. Matching is case-sensitive and whitespace-sensitive (a single leading or trailing space ruins an intended match).
required: no
default: none
recommended: Ignore unless directed otherwise by another property description. (See also valueType GROUP and renderingType SPARKLINE.)
example: See the GROUP valueType example.
name: dataKey
type: java.lang.String
property of: Column Description
description: Overrides the display dataKey if specified (for this column only).
required: no
default: Use the dataKey of the display.
recommended: Ignore.
name: renderingType
type: java.lang.String
range:
- VALUE
- SPARKLINE
- BAR_GRAPH
property of: Column Description
description: The rendering type tells Chime how to render aggregation values resulting from DTrace aggregating actions such as
count() and
sum(). 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
VALUE rendering type. For background on the
SPARKLINE rendering type, see Edward Tufte's
sparklines discussion (Chime's renderer, adequate for tables, does not support sparklines embedded in text components).
required: no
default: BAR_GRAPH
example: (A "History" column that presents an alternate view of data rendered as a bar graph in the "System Calls Per Second" column)
<object class="org.opensolaris.chime.ColumnDescription">
<void property="name">
<string>History</string>
</void>
<void property="renderingType">
<string>SPARKLINE</string>
</void>
<void property="aggregationName">
<string>a</string>
</void>
<void property="plottable">
<boolean>true</boolean>
</void>
<void property="plottableName">
<string>System Calls Per Second</string>
</void>
<void property="sourceColumnName">
<string>System Calls Per Second</string>
</void>
</object>
name: aggregationName
type: java.lang.String
property of: Column Description
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 or programFileName 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 count() or sum(). 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 @ aggregation symbol. See the Aggregations chapter of the Solaris Dynamic Tracing Guide for details about aggregation naming.
required: no
default: "" (empty string identifying the anonymous aggregation)
example: (specifies the aggregation in the D program statement @a[execname] = count(); )
<void property="aggregationName">
<string>a</string>
</void>
name: minimumValueRange
type: long
property of: Column Description
description: Used with the BAR_GRAPH renderingType to specify the initial range represented by the right edge of the cell containing the bar.
required: no
default: 1000
recommended: The default is good for many values generated by the DTrace count() 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).
example:
<void property="minimumValueRange">
<string>1000000</string>
</void>
name: valuePerSecond
type: boolean
property of: Column Description
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 count() and sum(); it does not apply to aggregation keys (columns that display tuple members). If valuePerSecond is true, 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) is cleared at each interval (see the clearedAggregations property). If valuePerSecond is false, Chime displays either a total since the last interval, or a running total, depending on whether or not the source aggregation is cleared.
required: no
default: false
example:
<void property="valuePerSecond">
<boolean>true</boolean>
</void>
name: unitsDescription
type: org.opensolaris.chime.util.DisplayUnits$Description
property of: Column Description
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:
- unitMultiple (int)
- unitLabels (java.lang.String[])
- default: { null, "K", "M", "G", "T", "P", "E", "Z", "Y" }
- zeroLabeled (boolean)
- space (boolean)
- fixedUnitIndex (int)
Chime will divide each value by the
unitMultiple until it obtains a value less than
unitMultiple. Each time it divides, it increments an index into the
unitLabels array (starting at zero). Typically the value
zero does not need (and stands out better without) a unit label; the
zeroLabeled property is there in case that assumption is wrong. Setting the
space property to
false results in something like "1.5K" instead of "1.5 K". The
fixedUnitIndex, if non-negative, specifies that all values in the column should share the same unit label. In that case, Chime will divide by the
unitMultiple as needed to achieve conversion to the unit specified by the zero-based index. Assuming default units, a
fixedUnitIndex of 3 indicates that all values in the column should be converted to Gigavalues.
required: no
default: Chime does not perform unit conversions or add unit labels.
recommended: If the column header specified by the
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 property to specify the desired number of decimal places, etc.
example: (Indicates that you want unit labels and accept all the defaults)
<void property="unitsDescription">
<object class="org.opensolaris.chime.util.DisplayUnits$Description">
</object>
</void>
name: displayTranslation
type: java.lang.String
range:
property of: Column Description
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:
FD_TO_PATH. This translation post-processes the
FD_TO_PATH tupleConversion, 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
int 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.
required: no
default: none
example:
<void property="tupleConversion">
<string>FD_TO_PATH</string>
</void>
<void property="displayTranslation">
<string>FD_TO_PATH</string>
</void>
name: name
type: boolean
property of: Column Description
description: Indicates that Chime should respect the numeric values of consecutive digit substrings when sorting the string values of this column. For example, if numericString is true, the values "c0d12s1" and "c0d2s1" will sort in the following ascending order:
c0d2s1
c0d12s1
rather than alphanumerically:
c0d12s1
c0d2s1
(since "d1" comes ahead of "d2" alphanumerically)
required: no
default: false
example:
<void property="numericString">
<boolean>true</boolean>
</void>
name: renderingHint
type: java.io.Serializable
property of: Column Description
description: A rendering hint of any type recognized by the column's table cell renderer (determined by the renderingType property). For example the renderer used with the default BAR_GRAPH rendering type recognizes the folowing hints:
- java.awt.Color (bar)
- org.opensolaris.chime.util.ColorGradient
- java.awt.Color (bar at cell's left edge)
- java.awt.Color (bar at cell's right edge)
- org.opensolaris.chime.util.Pair
- Color or ColorGradient (bar)
- Color (text)
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
SPARKLINE 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).
required: no
default: Chime paints bar graphs with a blue gradient (light blue on the left to medium blue on the right).
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 property to put the text to the left of the bar graph with no overlap.
example: (paints bar graphs with a red gradient, light red on the left, darker red on the right; the fourth
Color parameter after red, green, and blue is optional and controls transparency, one way to adjust lightness against a white background)
<void property="renderingHint">
<object class="org.opensolaris.chime.util.ColorGradient">
<object class="java.awt.Color">
<int>204</int> <!—0xCC—>
<int>17</int> <!—0x11—>
<int>0</int> <!—0x00—>
<int>85</int> <!—0x55—>
</object>
<object class="java.awt.Color">
<int>204</int> <!—0xCC—>
<int>17</int> <!—0x11—>
<int>0</int> <!—0x00—>
<int>255</int> <!—0xFF—>
</object>
</object>
</void>
name: alignmentHint
type: java.lang.String
range:
property of: Column Description
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
BAR_GRAPH valueType, the
left alignment hint value has the side effect of separating the text from the bar graph, avoiding contrast issues caused by overlap.
required: no
default: Chime left-aligns string values and right-aligns numeric values.
example:
<void property="alignmentHint">
<string>left</string>
</void>
name: plottable
type: boolean
property of: Column Description
description: Indicates whether the column supports the "Plot Over Time" menu action. If true, you can plot selected values of this column over time in another window displaying a line graph.
required: no
default: false
recommended: Set this property to true in every column that displays data generated by an aggregating DTrace action such as count() or sum(). If you have a column with the SPARKLINE renderingType providing an alternate view of data in a column with the BAR_GRAPH rendering type, make only the sparkline column plottable.
example:
<void property="plottable">
<boolean>true</boolean>
</void>
name: plottableName
type: java.lang.String
property of: Column Description
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 data and is used to label the Y-axis.
required: no
default: The name of the column is used to label the Y-axis of a plot over time.
recommended: If the column uses the SPARKLINE renderingType to present an alternate view of data in another column specified by the sourceColumnName property, use the name of the source column as the plottableName.
example: See the example under the renderingType property.
name: hidden
type: boolean
property of: Column Description
description: Indicates whether or not the column should be hidden from the display. If true, the column is not visible, but its data remains available to use in new predicates (see the menuItems property).
required: no
default: false
recommended: Typically you hide a column when data from DTrace needs to be converted for display (see the tupleConversion and displayKey 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.
example:
<void property="hidden">
<boolean>true</boolean>
</void>
name: totallerDescription
type: org.opensolaris.chime.TotallerDescription
property of: Column Description
description: Describes how to display a column total. If at least one column specifies a columnTotallerDescription, 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 columnTotallerDescription simply gets a blank total. See Totaller Description for more detail.
required: no
default: none (Chime does not display a total row)
example: (Displays the total number of devices in the "Devices" column)
<void property="totallerDescription">
<object class="org.opensolaris.chime.TotallerDescription">
<void property="totalType">
<string>COUNT</string>
</void>
<void property="displayFormat">
<string>{0, number, integer} {0, choice,
0#devices|1#device|2#devices}</string>
</void>
</object>
</void>
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 property, which specifies zero or more menu item descriptions.
name: singleSelectionNameFormat
type: java.lang.String
property of: Menu Item Description
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 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 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 property is used instead to name the drilldown menu item.
required: yes
example:
<void property="singleSelectionNameFormat">
<string>{0} by Function</string>
</void>
name: multiSelectionName
type: java.lang.String
property of: Menu Item Description
description: Specifies the name of the drilldown menu item when multiple rows are selected. If a single row is selected, the singleSelectionNameFormat property is used instead.
required: no
default: If you neglect to specify a multiSelectionName for the menu item, Chime uses the singleSelectionNameFormat with an empty string argument instead.
example:
<void property="singleSelectionNameFormat">
<string>by Function</string>
</void>
name: newColumns
type: org.opensolaris.chime.ColumnDescription[]
property of: Menu Item Description
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 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 and displayKey, and they replace all the columns included in the existing uniqueKey and displayKey.
required: yes
example: (Drilldown action specifies the new key as a single column for a display aggregated by function)
<void property="newColumns">
<array class="org.opensolaris.chime.ColumnDescription" length="1">
<void index="0">
<object class="org.opensolaris.chime.ColumnDescription">
<void property="tupleMember">
<string>probefunc</string>
</void>
<void property="name">
<string>Function</string>
</void>
<void property="tupleIndex">
<int>0</int>
</void>
</object>
</void>
</array>
</void>
name: uniqueKey
type: java.lang.String[]
property of: Menu Item Description
description: Same as the uniqueKey display property, except that it specifies the unique key of the new display launched by the menu item.
required: no
default: Chime uses the names of the new columns that specify a non-negative tupleIndex value, in order by tuple index.
recommended: Ignore. Chime sets this property for you using the tupleIndex property of the new columns.
name: newDisplayKey
type: java.lang.String[]
property of: Menu Item Description
description: Same as the displayKey display property, except that it specifies the display key of the new display launched by the menu item.
required: no, unless a new column with a non-negative tupleIndex is hidden so that its value can be displayed differently in another new column.
default: Chime uses the new unique key if a new display key is omitted.
name: initialSort
type: java.lang.String
property of: Menu Item Description
description: Same as the initialSort 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.
required: no
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 initialSort display property default.
name: newWindowSize
type: java.awt.Dimension
property of: Menu Item Description
description: Same as the size display property, except that it specifies the size of the new display window launched by the menu item.
required: no
default: Chime uses the size specified for the previous display (not the current window size if the previous display was resized).
example: (Specifies a new window 400 pixels wide by 300 pixels high.)
<void property="newWindowSize">
<object class="java.awt.Dimension">
<int>400</int>
<int>300</int>
</object>
</void>
name: menuItems
type: org.opensolaris.chime.MenuItemDescription[]
property of: Menu Item Description
description: Same as the menuItems display property, except that it specifies the drilldown menu items of the new display launched by the menu item.
required: no
default: The new display has no drilldown menu items, even if the previous display does have them.
name: totalType
type: java.lang.String
range:
property of: Totaller Description
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).
required: no
default: Chime does not display a total for the column.
recommended: Use
SUM for values generated by DTrace aggregating actions such as
count() or
sum(). Use
UNIQUE_COUNT for tuple members. If you don't need to display the number of
different non-blank tuple member values,
COUNT is more efficent: it simply displays the number of
non-blank values.
example:
<void property="totalType">
<string>SUM</string>
</void>
name: displayFormat
type: java.lang.String
property of: Totaller Description
description: Same as the displayFormat 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.
required: no
default: If the totalType is SUM, Chime displays the column total using the same displayFormat specified for column values. Otherwise, Chime displays an unformatted number.
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 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.
example: (Counts the number of different values in the "CPU" column)
<void property="totalType">
<string>UNIQUE_COUNT</string>
</void>
<void property="displayFormat">
<string>{0, number, integer} {0, choice, 0#cpus|1#cpu|2#cpus}</string>
</void>
name: unitsDescription
type: org.opensolaris.chime.util.DisplayUnits$Description
property of: Totaller Description
description: Same as the unitsDescription column property, except that it applies to the column total. This property applies only to the SUM totalType.
required: no
default: Chime displays the column total using the same unitsDescription specified for column values.
recommended: Ignore. Chime automatically applies the unit labels of the column to the column total.
name: columnTestDescription
type: org.opensolaris.chime.ColumnTestDescription
property of: Totaller Description
description: Specifies a column test that may supply multiple arguments to the displayFormat (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 is UNIQUE_COUNT and the totalled column has the valueType GROUP; it is described with the following properties:
- columnName (java.lang.String)
- testType (java.lang.String)
- conditionalDisplayFormats (java.lang.String[])
The
columnName property names the column to be tested. The specified name must exactly match the
name of a column specified in the
columns display property. The
totalType property names the test implementation. The test name must match one of the recognized values in the range listed under
testType (above). The
conditionalDisplayFormats 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
NON_BLANK test type, a single alternate format is supported, used only when all values in the specified column pass the test; otherwise, the
NON_BLANK test supplies two arguments to the specified
displayFormat: first, the number of values passing the test, and second, the total number of values.
required: no
default: A single argument to a single display format is enough (
please…).
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")
<void property="totallerDescription">
<object class="org.opensolaris.chime.TotallerDescription">
<void property="totalType">
<string>UNIQUE_COUNT</string>
</void>
<void property="displayFormat">
<string>{0, number, integer} / {1, number, integer} {1, choice,
0#executables|1#executable|2#executables}</string>
</void>
<void property="columnTestDescription">
<object class="org.opensolaris.chime.ColumnTestDescription">
<void property="columnName">
<string>File Descriptor</string>
</void>
<void property="testType">
<string>NON_BLANK</string>
</void>
<void property="conditionalDisplayFormats">
<array class="java.lang.String" length="1">
<void index="0">
<string>{0, number, integer} {0, choice,
0#executables|1#executable|2#executables}</string>
</void>
</array>
</void>
</object>
</void>
</object>
</void>
Here's an example that specifies the absolute minimum properties: a title, a DTrace program, and 2 columns:
title "System Calls"
programString "syscall:::entry {@[execname] = count() }"
columns
[0]
name "Executable"
tupleIndex 0
[1]
name "System Calls"
This is a bit more verbose in XML (simple.xml):
<java version="1.5.0-beta3" class="java.beans.XMLDecoder">
<object class="org.opensolaris.chime.DisplayDescription">
<void property="title">
<string>System Calls</string>
</void>
<void property="programString">
<string>syscall:::entry { @[execname] = count(); }</string>
</void>
<void property="columns">
<array class="org.opensolaris.chime.ColumnDescription" length="2">
<void index="0">
<object class="org.opensolaris.chime.ColumnDescription">
<void property="name">
<string>Executable</string>
</void>
<void property="tupleIndex">
<int>0</int>
</void>
</object>
</void>
<void index="1">
<object class="org.opensolaris.chime.ColumnDescription">
<void property="name">
<string>System Calls</string>
</void>
</object>
</void>
</array>
</void>
</object>
</java>
The initial sort in this example defaults to ascending by aggregation key (see initialSort). The display does not support plotting over time in a line graph (see plottable), nor does it support drilldown (see menuItems). 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 column property to true. If you wanted a total row, all you would have to do is specify a totallerDescription for one or both columns.