Options and Tunables
To allow for customization, DTrace affords its consumers several important degrees of freedom. To minimize the likelihood of requiring specific tuning, DTrace is implemented using reasonable default values and flexible default policies. However, situations may arise that require tuning the behavior of DTrace on a consumer-by-consumer basis. This chapter describes the DTrace options and tunables and the interfaces you can use to modify them.
16.1. Consumer Options
DTrace is tuned by setting or enabling options. The available options are described in the table below. For some options, dtrace(1M) provides a corresponding command-line option.
Option Name |
Value |
dtrace(1M) Alias |
Description |
---|---|---|---|
|
time |
Rate of aggregation reading. See Aggregations. |
|
|
size |
Aggregation buffer size. See Aggregations. |
|
|
|
Buffer resizing policy. See Buffers and Buffering. |
|
|
size |
|
Principal buffer size. See Buffers and Buffering. |
|
time |
Cleaning rate. Must be specified in number-per-second with the
|
|
|
scalar |
|
CPU on which to enable tracing. See Buffers and Buffering. |
|
— |
Allow references to unspecified macro arguments. See Scripting. |
|
|
— |
|
Allow destructive actions. See Actions and Subroutines. |
|
size |
Dynamic variable space size. See Variables |
|
|
— |
|
Indent function entry and prefix with |
|
— |
|
Claim anonymous state. See Anonymous Tracing. |
|
scalar |
Number of default stack frames for |
|
|
scalar |
Default string space size for |
|
|
scalar |
Number of speculations. See Speculative Tracing. |
|
|
— |
|
Output only explicitly traced data. See dtrace(1M) Utility. |
|
size |
Speculation buffer size. See Speculative Tracing. |
|
|
size |
String size. See Strings. |
|
|
scalar |
Number of stack frames. See Actions and Subroutines. |
|
|
scalar |
Number of whitespace characters to use when indenting
|
|
|
time |
Rate of status checking |
|
|
time |
Rate of buffer switching. See Buffers and Buffering. |
|
|
— |
Order output in temporal order. See Buffers and Buffering. |
|
|
scalar |
Number of user stack frames. See Actions and Subroutines. |
|
|
string |
Limit USDT enablings to specified zone. See Statically Defined Tracing for User Applications. |
Values that denote sizes may be given an optional suffix of k
, m
, g
, or t
to denote kilobytes,
megabytes, gigabytes, and terabytes respectively. Values that denote times
may be given an optional suffix of ns
, us
, ms
, s
or hz
to denote nanoseconds,
microseconds, milliseconds, seconds, and number-per-second, respectively.
16.2. Modifying Options
Options may be set 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 equals sign (=
)
and the option value. The following examples are all valid option settings:
#pragma D option nspec=4
#pragma D option grabanon
#pragma D option bufsize=2g
#pragma D option switchrate=10hz
#pragma D option aggrate=100us
#pragma D option bufresize=manual
The dtrace(1M) command
also accepts option settings on the command-line as an argument to the -x
option.
For example:
# dtrace -x nspec=4 -x grabanon -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:
# dtrace -x wombats=25 dtrace: failed to set option -x wombats: Invalid option name #
Similarly, if an option value is not valid for the given option, dtrace
will indicate that the value is invalid:
# 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, such as grabanon
, may only be
set. The presence of such an option sets it, and you cannot subsequently unset
it.
Options that are set for an anonymous enabling will be honored by the DTrace consumer that claims the anonymous state. See Anonymous Tracing for information about enabling anonymous tracing.