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
aggpercpu	Compile-time		Aggregate per CPU. See Aggregations.
aggrate	Dynamic runtime	time	Rate of aggregation reading. See Aggregations.
aggsize	Runtime	size	Aggregation buffer size/ See Aggregations.
aggsortkey	Dynamic runtime	false or true	Sort aggregations by key. See Aggregations.
aggsortkeypos	Dynamic runtime	scalar	Number of the aggregation key on which to sort. See Aggregations.
aggsortpos	Dynamic runtime	scalar	Number of the aggregation variable on which to sort See Aggregations.
aggsortrev	Dynamic runtime	false or true	Sort aggregations in reverse order. See Aggregations.
amin	Compile-time	string	Stability attribute minimum. See Stability Enforcement
argref	Compile-time		Do not require all macro arguments to be used.
bufpolicy	Runtime	fill, ring, or switch	Buffer policy. See Buffers and Buffering .
bufresize	Runtime	auto or manual	Buffer resizing policy. See Buffers and Buffering .
bufsize	Runtime	size	Principal buffer size (equivalent to the dtrace -b). See Buffers and Buffering .
cleanrate	Runtime	time	Cleaning rate. See Speculative Tracing.
core	Compile-time		Enable core dumping by dtrace.
cpp	Compile-time		Use cpp to pre-process the input file.
cpphdrs	Compile-time		Specify the -H option to cpp to print the name of each header file that is used.
cpppath	Compile-time	string	Specify the path name of cpp.
cpu	Runtime	scalar	CPU on which to enable tracing. See Buffers and Buffering.
ctypes	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.
debug	Compile-time		Enable DTrace debugging mode (equivalent to setting the environment variable DTRACE_DEBUG).
defaultargs	Compile-time		Allow references to unspecified macro arguments. Use 0 as the value for an unspecified argument. See Scripting.
define	Compile-time	string	Define a macro name and optional value in the form name[=value]. (equivalent to dtrace -D).
destructive	Runtime		Allow destructive actions (equivalent to dtrace -w). See Actions and Subroutines.
droptags	Compile-time		Specifies that drop tags are used.
dtypes	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.
dynvarsize	Runtime	size	Dynamic variable space size. See Variables.
empty	Compile-time		Permit compilation of empty D source files.
errtags	Compile-time		Prefix default error message with error tags.
evaltime	Compile-time	exec, main, postinit, or preinit	Control when DTrace starts tracing a new process. For dynamically linked binaries, tracing starts: exec After exec(). preinit After initialization of the dynamic linker to load the binary. postinit (default) After constructor execution. main Before main() starts. Same as postinit. For statically linked binaries, preinit is equivalent to exec. For stripped, statically linked binaries, postinit and main are equivalent to preinit.
flowindent	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. See dtrace Command Reference.
incdir	Compile-time	string	Add a #include directory to the preprocessor search path (equivalent to dtrace -I).
iregs	Compile-time	scalar	Size of the DTrace Intermediate Format (DIF) integer register set. The default value is 8.
kdefs	Compile-time		Do not permit unresolved kernel symbols.
knodefs	Compile-time		Permit unresolved kernel symbols.
late	Compile-time	dynamic or static	Specify whether references to dynamic translators are permitted: dynamic Allow references to dynamic translators. static Require translators to be statically defined.
lazyload	Compile-time	false or true	Specify that the DTrace Object Format (DOF) should be lazily loaded rather than actively loaded.
ldpath	Compile-time	string	Specify the path of the dynamic linker loader (ld).
libdir	Compile-time	string	Add a library directory to the library search path.
linkmode	Compile-time	dynamic, kernel, or static	Specify the symbol linking mode that is used by the assembler when processing external symbol references: dynamic All symbols are treated as dynamic. kernel Kernel symbols are treated as static and user symbols are treated as dynamic. static All symbols are treated as static.
linktype	Compile-time	dof or elf	Specify the output file type: dof Produce a standalone DOF file. elf Produce an ELF file that contains DOF.
modpath	Compile-time	string	Module path. The default path is /lib/modules/ version.
nolibs	Compile-time		Do not process D system libraries.
nspec	Runtime	scalar	Number of speculations. See Speculative Tracing.
pgmax	Compile-time	scalar	Limit on the number of threads that DTrace can grab for tracing. The default value is 8.
preallocate	Compile-time	scalar	Amount of memory to preallocate.
procfspath	Compile-time	string	Path to the procfs file system. The default path is /proc.
pspec	Compile-time		Interpret ambiguous specifiers as probe names.
quiet	Dynamic runtime		Output only explicitly traced data (equivalent to dtrace -q). See dtrace Command Reference.
quietresize	Dynamic runtime		Suppress buffer-resize messages. See Buffers and Buffering.
rawbytes	Dynamic runtime		Always print trace output in hexadecimal. See Actions and Subroutines.
specsize	Runtime	size	Speculation buffer size. See Speculative Tracing.
stackframes	Runtime	scalar	Number of stack frames. See Actions and Subroutines.
stackindent	Dynamic runtime	scalar	Number of white space characters to use when indenting stack and ustack output. See Actions and Subroutines.
statusrate	Runtime	time	Rate of status checking.
stdc	Compile-time	a, c, s, or t	Specify ISO C conformance settings for the preprocessor when invoking cpp with the -C option. The a, c, and t settings include the-std=gnu99 option (conformance with 1999 C standard including GNU extensions). The s setting includes the -traditional-cpp option (conformance with K&R C).
strip	Compile-time		Strip non-loadable sections from the program.
strsize	Runtime	size	String size. See DTrace Support for Strings.
switchrate	Dynamic runtime	time	Rate of buffer switching. See Buffers and Buffering .
syslibdir	Compile-time	string	Path name of system libraries.
tree	Compile-time	scalar	Value of the DTrace tree dump bitmap.
tregs	Compile-time	scalar	Size of the DIF tuple register set. The default value is 8.
udefs	Compile-time		Do not permit unresolved user symbols.
undef	Compile-time	string	Undefine a symbol when invoking the preprocessor. Equivalent to dtrace -U.
unodefs	Compile-time		Permit unresolved user symbols.
ustackframes	Runtime	scalar	Number of user-land stack frames. See Actions and Subroutines.
verbose	Compile-time		DIF verbose mode, which shows each compiled DIF object (DIFO).
version	Compile-time	string	Request a specific version of the native DTrace library.
zdefs	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.