Dynamic Tracing Guide
PreviousNext
Chapter 16

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.

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.

DTrace Consumer Options

Option Name

Value

dtrace(1M) Alias

Description

See Chapter

aggrate

time

Rate of aggregation reading

Chapter 9, Aggregations

aggsize

size

Aggregation buffer size

Chapter 9, Aggregations

bufresize

auto or manual

Buffer resizing policy

Chapter 11, Buffers and Buffering

bufsize

size

-b

Principal buffer size

Chapter 11, Buffers and Buffering

cleanrate

time

Cleaning rate. Must be specified in number-per-second with the hz suffix.

Chapter 13, Speculative Tracing

cpu

scalar

-c

CPU on which to enable tracing

Chapter 11, Buffers and Buffering

defaultargs

Allow references to unspecified macro arguments

Chapter 15, Scripting

destructive

-w

Allow destructive actions

Chapter 10, Actions and Subroutines

dynvarsize

size

Dynamic variable space size

Chapter 3, Variables

flowindent

-F

Indent function entry and prefix with ->; unindent function return and prefix with <-

Chapter 14, dtrace(1M) Utility

grabanon

-a

Claim anonymous state

Chapter 36, Anonymous Tracing

jstackframes

scalar

Number of default stack frames jstack

Chapter 10, Actions and Subroutines

jstackstrsize

scalar

Default string space size for jstack

Chapter 10, Actions and Subroutines

nspec

scalar

Number of speculations

Chapter 13, Speculative Tracing

quiet

-q

Output only explicitly traced data

Chapter 14, dtrace(1M) Utility

specsize

size

Speculation buffer size

Chapter 13, Speculative Tracing

strsize

size

String size

Chapter 6, Strings

stackframes

scalar

Number of stack frames

Chapter 10, Actions and Subroutines

stackindent

scalar

Number of whitespace characters to use when indenting stack and ustack output

Chapter 10, Actions and Subroutines

statusrate

time

Rate of status checking

switchrate

time

Rate of buffer switching

Chapter 11, Buffers and Buffering

temporal

Order output in temporal order

Chapter 11, Buffers and Buffering

ustackframes

scalar

Number of user stack frames

Chapter 10, Actions and Subroutines

zone

string

Limit USDT enablings to specified zone.

Chapter 34, 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.

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 Chapter 36, Anonymous Tracing for information about enabling anonymous tracing.

PreviousNext