Options and Tunables

{anchor:top}
h1. {anchor:CHP-OPT} 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.

[Top|#top]
h2. {anchor:CHP-OPT-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)|http://docs.sun.com/doc/819-2240/dtrace-1m?a=view] provides a corresponding command-line option.
h6. {anchor:TBL-OPTIONS} DTrace Consumer Options
||Option Name||Value||[{{dtrace}}(1M)|http://docs.sun.com/doc/819-2240/dtrace-1m?a=view] Alias||Description||See Chapter||
|{{aggrate}}|_time_| |Rate of aggregation reading|[Chapter 9, Aggregations|Aggregations]|
|{{aggsize}}|_size_| |Aggregation buffer size|[Chapter 9, Aggregations|Aggregations]|
|{{bufresize}}|{{auto}} or {{manual}}| |Buffer resizing policy|[Chapter 11, Buffers and Buffering|Buffers and Buffering]|
|{{bufsize}}|_size_|\-b|Principal buffer size|[Chapter 11, Buffers and Buffering|Buffers and Buffering]|
|{{cleanrate}}|_time_| |Cleaning rate|[Chapter 13, Speculative Tracing|Speculative Tracing]|
|{{cpu}}|_scalar_|\-c|CPU on which to enable tracing|[Chapter 11, Buffers and Buffering|Buffers and Buffering]|
|{{defaultargs}}|—| |Allow references to unspecified macro arguments|[Chapter 15, Scripting|Scripting]|
|{{destructive}}|—|\-w|Allow destructive actions|[Chapter 10, Actions and Subroutines|Actions and Subroutines]|
|{{dynvarsize}}|_size_| |Dynamic variable space size|[Chapter 3, Variables|Variables]|
|{{flowindent}}|—|\-F|Indent function entry and prefix with {{->}}; unindent function return and prefix with {{<-}}|[Chapter 14, dtrace(1M) Utility|dtrace(1M) Utility]|
|{{grabanon}}|—|\-a|Claim anonymous state|[Chapter 36, Anonymous Tracing|Anonymous Tracing]|
|{{jstackframes}}|_scalar_| |Number of default stack frames {{jstack}}|[Chapter 10, Actions and Subroutines|Actions and Subroutines]|
|{{jstackstrsize}}|_scalar_| |Default string space size for {{jstack}}|[Chapter 10, Actions and Subroutines|Actions and Subroutines]|

|{{stackframes}}|_scalar_| |Number of stack frames|[Chapter 10, Actions and Subroutines|Actions and Subroutines]|
|{{stackindent}}|_scalar_| |Number of whitespace characters to use when indenting {{stack}} and {{ustack}} output|[Chapter 10, Actions and Subroutines|Actions and Subroutines]|
|{{statusrate}}|_time_| |Rate of status checking| |
|{{switchrate}}|_time_| |Rate of buffer switching|[Chapter 11, Buffers and Buffering|Buffers and Buffering]|
|{{ustackframes}}|_scalar_| |Number of user stack frames|[Chapter 10, Actions and Subroutines|Actions and Subroutines]|
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.

[Top|#top]
h2. {anchor:CHP-OPT-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:
{noformat}
#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
{noformat}
The [{{dtrace}}(1M)|http://docs.sun.com/doc/819-2240/dtrace-1m?a=view] command also accepts option settings on the command-line as an argument to the \-x option. For example:
{noformat}
# dtrace -x nspec=4 -x grabanon -x bufsize=2g \
-x switchrate=10hz -x aggrate=100us -x bufresize=manual
{noformat}
If an invalid option is specified, {{dtrace}} indicates that the option name is invalid and exits:
{noformat}
# dtrace -x wombats=25
dtrace: failed to set option -x wombats: Invalid option name
#
{noformat}
Similarly, if an option value is not valid for the given option, {{dtrace}} will indicate that the value is invalid:
{noformat}
# dtrace -x bufsize=100wombats
dtrace: failed to set option -x bufsize: Invalid value for specified option
#
{noformat}
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|Anonymous Tracing] for information about enabling anonymous tracing.
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:25:15 PM{excerpt}