DTrace Programs in Chime
The following are some important observations to make about your DTrace
program:
- Aggregations: Since Chime is a tool for visualizing DTrace
aggregations, it follows that your program must include at least one
aggregation. See the Aggregations chapter of the Solaris Dynamic
Tracing Guide for details about DTrace aggregations.
- printa(): If you use the
printa()
action on an aggregation, that aggregation will thereafter be
unavailable to Chime. Typically, printa() is found
in a profile probe such as tick-1sec. You should delete
these tick clauses from your program. Instead of printing
your aggregations, you are now relying on Chime to display them.
- Tuples: You can have multiple aggregations in your program.
However, Chime assumes that all aggregations in the same program
share the same tuple (aggregation key). If two aggregations in
your program have different tuples, the results in Chime are currently
undefined.
Macro Arguments
Macro argument variables in your DTrace program are integers starting
at 1 ($0 is reserved for the executable name) and 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. You can specify default values for macro arguments. The
user of Chime will have the opportunity to override those defaults
before launching the display. Use macro arguments instead of
substitutions for values that can be specified by the user at runtime.
Unlike Chime substitutions, macro argument placeholders remain visible
to the user through the Display DTrace Program menu action.
Substitutions
Chime substitution variables are surrounded by question mark pairs, for
example: ??PROBE??. The default value for that variable (if any) is
specified using the same variable name preceded by a single pair of
question marks at the start of a line, usually at the end of the
program, for example:
??PROBE??
??P0??
{
@[??T??] = count();
}
??PROBE syscall:::entry
??P0
The default value for P0 is blank (no predicate). T
(@[??T??]) has no default value. P0, P1, P2, etc. are
special, reserved variable names used only for predicates. Do
not surround predicate variables or their default values with forward
slashes. T is a special reserved variable name for the aggregation
tuple, and is used in combination with predicate variables to support
drilldown. You may specify default values for aggregation tuple members
as T0, T1, etc. However, you do not specify a value for the tuple
variable here. Instead, specify one column in the Specify
Columns step for each tuple member and set its Tuple Member
property: these collectively replace the ??T?? tuple variable in your
program.
Substitutions improve program reusability and support drilldown. They
are not visible to the user of Chime.