10 Options and Tunables
To enable customization, DTrace affords its consumers several important degrees of freedom. To minimize the likelihood of requiring specific tuning, DTrace is implemented with reasonable default values and flexible default policies, but situations might arise that require tuning the behavior of DTrace on a consumer-by-consumer basis. This chapter describes DTrace options and tunables and the interfaces that you can use to modify them.
Consumer Options
DTrace is tuned by setting or enabling options. The available options for tuning DTrace are described in the following table. For some options, a corresponding dtrace command-line option is also provided.
Table 10-1 DTrace Consumer Options
Option Name | Type | Value | Description |
---|---|---|---|
|
Compile-time |
Aggregate per CPU. See Aggregations. |
|
|
Dynamic runtime |
time |
Rate of aggregation reading. See Aggregations. |
|
Runtime |
size |
Aggregation buffer size/ See Aggregations. |
|
Dynamic runtime |
|
Sort aggregations by key. See Aggregations. |
|
Dynamic runtime |
scalar |
Number of the aggregation key on which to sort. See Aggregations. |
|
Dynamic runtime |
scalar |
Number of the aggregation variable on which to sort See Aggregations. |
|
Dynamic runtime |
|
Sort aggregations in reverse order. See Aggregations. |
|
Compile-time |
string |
Stability attribute minimum. |
|
Compile-time |
Do not require all macro arguments to be used. |
|
|
Runtime |
|
Buffer policy. See Buffers and Buffering . |
|
Runtime |
|
Buffer resizing policy. See Buffers and Buffering . |
|
Runtime |
size |
Principal buffer size (equivalent to the dtrace -b). See Buffers and Buffering . |
|
Runtime |
time |
Cleaning rate. See Speculative Tracing. |
|
Compile-time |
Enable core dumping by dtrace. |
|
|
Compile-time |
Use cpp to pre-process the input file. |
|
|
Compile-time |
Specify the -H option to cpp to print the name of each header file that is used. |
|
|
Compile-time |
string |
Specify the path name of cpp. |
|
Runtime |
scalar |
CPU on which to enable tracing. |
|
Compile-time |
string |
Write out Compact Type Format (CTF) definitions of all C types used in a program at the end of a D compilation run. |
|
Compile-time |
Enable DTrace debugging mode (equivalent to setting the
environment variable |
|
|
Compile-time |
Allow references to unspecified macro arguments. Use
See Scripting. |
|
|
Compile-time |
string |
Define a macro name and optional value in the form name[=value]. (equivalent to dtrace -D). |
|
Runtime |
Allow destructive actions (equivalent to dtrace -w). |
|
|
Compile-time |
Specifies that drop tags are used. |
|
|
Compile-time |
string |
Write out CTF definitions of all D types that are used in a program at the end of a D compilation run. |
|
Runtime |
size |
Dynamic variable space size. See Variables. |
|
Compile-time |
Permit compilation of empty D source files. |
|
|
Compile-time |
Prefix default error message with error tags. |
|
|
Compile-time |
|
Control when DTrace starts tracing a new process. For dynamically linked binaries, tracing starts:
For statically linked binaries,
For stripped, statically linked binaries,
|
|
Dynamic runtime |
Indent function entry and prefix with
Unindent function return and prefix with
Indent system call entry and prefix with
Unindent system call return and prefix with
Equivalent to dtrace -F. |
|
|
Compile-time |
string |
Add a |
|
Compile-time |
scalar |
Size of the DTrace Intermediate Format (DIF) integer
register set. The default value is |
|
Compile-time |
Do not permit unresolved kernel symbols. |
|
|
Compile-time |
Permit unresolved kernel symbols. |
|
|
Compile-time |
|
Specify whether references to dynamic translators are permitted:
|
|
Compile-time |
|
Specify that the DTrace Object Format (DOF) should be lazily loaded rather than actively loaded. |
|
Compile-time |
string |
Specify the path of the dynamic linker loader (ld). |
|
Compile-time |
string |
Add a library directory to the library search path. |
|
Compile-time |
|
Specify the symbol linking mode that is used by the assembler when processing external symbol references:
|
|
Compile-time |
|
Specify the output file type:
|
|
Compile-time |
string |
Module path. The default path is
|
|
Compile-time |
Do not process D system libraries. |
|
|
Runtime |
scalar |
Number of speculations. See Speculative Tracing. |
|
Compile-time |
scalar |
Limit on the number of threads that DTrace can grab for
tracing. The default value is |
|
Compile-time |
scalar |
Amount of memory to preallocate. |
|
Compile-time |
string |
Path to the |
|
Compile-time |
Interpret ambiguous specifiers as probe names. |
|
|
Dynamic runtime |
Output only explicitly traced data (equivalent to dtrace -q). |
|
|
Dynamic runtime |
Suppress buffer-resize messages. |
|
|
Dynamic runtime |
Always print |
|
|
Runtime |
size |
Speculation buffer size. See Speculative Tracing. |
|
Runtime |
scalar |
Number of stack frames. |
|
Dynamic runtime |
scalar |
Number of white space characters to use when indenting
|
|
Runtime |
time |
Rate of status checking. |
|
Compile-time |
|
Specify ISO C conformance settings for the preprocessor when invoking cpp with the -C option.
The
The |
|
Compile-time |
Strip non-loadable sections from the program. |
|
|
Runtime |
size |
String size. |
|
Dynamic runtime |
time |
Rate of buffer switching. See Buffers and Buffering . |
|
Compile-time |
string |
Path name of system libraries. |
|
Compile-time |
scalar |
Value of the DTrace tree dump bitmap. |
|
Compile-time |
scalar |
Size of the DIF tuple register set. The default value is
|
|
Compile-time |
Do not permit unresolved user symbols. |
|
|
Compile-time |
string |
Undefine a symbol when invoking the preprocessor. Equivalent to dtrace -U. |
|
Compile-time |
Permit unresolved user symbols. |
|
|
Runtime |
scalar |
Number of user-land stack frames. |
|
Compile-time |
DIF verbose mode, which shows each compiled DIF object (DIFO). |
|
|
Compile-time |
string |
Request a specific version of the native DTrace library. |
|
Compile-time |
Permit probe definitions that match zero probes. |
Values that denote sizes can be given an optional suffix of
k
, m
, g
,
or t
to denote kilobytes, megabytes, gigabytes,
and terabytes, respectively. Values that denote times can be given
an optional suffix of ns
,
us
, ms
, s
or hz
to denote nanoseconds, microseconds,
milliseconds, seconds, and number per second, respectively.
Modifying Options
You can set options in a D script by using #pragma
D
followed by the string option
and
the option name. If the option takes a value, the option name
should be followed by an equal sign (=
) and the
option value. The following are examples of valid option settings:
#pragma D option nspec=4 #pragma D option bufsize=2g #pragma D option switchrate=10hz #pragma D option aggrate=100us #pragma D option bufresize=manual
The dtrace command also accepts option settings on the command line as an argument to the -x option, for example:
# dtrace -x nspec=4 -x bufsize=2g \ -x switchrate=10hz -x aggrate=100us -x bufresize=manual
If an invalid option is specified, dtrace indicates that the option name is invalid and exits, as shown in the following example:
# dtrace -x wombats=25 dtrace: failed to set option -x wombats: Invalid option name
Similarly, if a value is not valid for the given option, dtrace indicates that the value is invalid, as shown here:
# dtrace -x bufsize=100wombats dtrace: failed to set option -x bufsize: Invalid value for specified option
If an option is set more than once, subsequent settings overwrite earlier settings. Some options can only be set. The presence of such an option sets it, and you cannot subsequently unset it.