DTrace Runtime and Compile-time Options Reference

4 DTrace Runtime and Compile-time Options Reference

DTrace uses reasonable default values and flexible default policies for runtime configuration. Tuning mechanisms in the form of DTrace compiler or runtime option can change the default behavior of the dtrace utility. You can find more information about the dtrace utility and various command line options in the dtrace(8) manual page.

Options that can be specified when running the dtrace utility can be categorized into three types:

Compile-time Options: affect the compilation process but might also affect runtime behavior.
Runtime Options: affect the runtime behavior of DTrace but which are often set at compile time.
Dynamic Runtime Options: affect the runtime behavior of DTrace but which can be changed while tracing, by using the setopt function.

Setting DTrace Compile-time and Runtime Options

You can tune DTrace by setting or enabling a selection of runtime or compiler options. You can set options by either using the -x command line switch when running the dtrace command, or by specifying pragma lines in D programs. If an option takes a value, follow the option name with an equal sign (=) and the option value.

Value Suffixes

Use the following optional suffixes for values that denote size or time:

k or K: kilobytes
m or M: megabytes
g or G: gigabytes
t or T: terabytes
ns or nsec: nanoseconds
us or usec: microseconds
ms or msec: milliseconds
s or sec: seconds
m or min: minutes
h or hour: hours
d or day: days
hz: number per second

Example 4-1 Enabling Options Using the DTrace Utility

The dtrace command accepts option settings on the command line by using the -x switch, for example:

sudo dtrace -x nspec=4 -x bufsize=2g \
-x switchrate=10hz -x aggrate=100us -x bufresize=manual

Example 4-2 DTrace Pragma Lines To Enable Options in a D Program

You can set options in a D program by using #pragma D followed by the string option and the option name and 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

Compile-time Options

Compile-time options can control how DTrace programs are compiled into eBPF code that's loaded into kernel space.

aggpercpu

Compile-time option that forces the compiler to perform aggregation per CPU.

amin=<string>

Compile-time option that sets the stability attribute minimum.

argref

Compile-time option that disables the requirement to use all macro arguments.

core

Compile-time option that enables core dumping by dtrace.

cpp

Compile-time option that enables cpp to preprocess the input file.

cppargs

Compile-time option that specifies and extra arguments to pass to cpp (when using -C).

cpphdrs

Compile-time option that specifies the -H option to cpp to print the name of each header file used.

cpppath=<string>

Compile-time option that specifies the path name of cpp.

ctfpath

Compile-time option that can specify the path of vmlinux.ctfa.

ctypes=<string>

Compile-time option that specifies Compact Type Format (CTF) definitions of all C types used in a program at the end of a D compilation run.

debug

Compile-time option that enables DTrace debugging mode. This option is the same as setting the environment variable DTRACE_DEBUG.

debugassert

Compile-time option that can enable specific debug modes [UNTESTED].

defaultargs

Compile-time option that allows references to unspecified macro arguments. Use 0 as the value for an unspecified argument.

define=<string>

Compile-time option that specifies a macro name and optional value in the form name[=value]. This option is the same as running dtrace -D.

disasm

Compile-time option to specify requested disassembler listings (when using -S).

droptags

Compile-time option that specifies that drop tags are used.

dtypes=<string>

Compile-time option that specifies CTF definitions of all D types that are used in a program at the end of a D compilation run.

empty

Compile-time option that permits compilation of empty D source files.

errtags

Compile-time option that prefixes default error message with error tags.

evaltime=[exec|main|postinit|preinit]

Compile-time option that controls 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: After constructor execution. Default value.
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.

incdir=<string>

Compile-time option that adds an #include directory to the preprocessor search path. This option is the same as running dtrace -I.

iregs=<scalar>

Compile-time option that sets the size of the DTrace Intermediate Format (DIF) integer register set. The default value is 8.

kdefs

Compile-time option that prevents unresolved kernel symbols.

knodefs

Compile-time option that permits unresolved kernel symbols.

late=[dynamic|static]

Compile-time option that specifies whether to permit references to dynamic translators:

dynamic: Allow references to dynamic translators.
static: Require translators to be statically defined.

lazyload=<true|false>

Compile-time option that specifies lazy loading for the DTrace Object Format (DOF) rather than active loading.

ldpath=<string>

Compile-time option that specifies the path of the dynamic linker loader (ld).

libdir=<string>

Compile-time option that adds a library directory to the library search path.

linkmode=[dynamic|kernel|static]

Compile-time option that specifies the symbol linking mode 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.

linknommap

Compile-time option to disable use of MMAP-based libelf support when linking USDT objects.

linktype=[dof|elf]

Compile-time option that specifies the output file type:

dof: Produce a standalone DOF file.
elf: Produce an ELF file that contains DOF.

modpath=<string>

Compile-time option that specifies the module path. The default path is /lib/modules/ version.

nolibs

Compile-time option that prevents processing D system libraries.

pgmax=<scalar>

Compile-time option that sets a limit on the number of threads that DTrace can grab for tracing. The default value is 8.

preallocate=<scalar>

Compile-time option that sets the amount of memory to preallocate.

procfspath=<string>

Compile-time option that sets the path to the procfs file system. The default path is /proc.

pspec

Compile-time option that enables interpretation of ambiguous specifiers as probe names.

stdc=[a|c|s|t]

Compile-time option that specifies 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 option that strips non-loadable sections from the program.

syslibdir=<string>

Compile-time option that sets the path name of system libraries.

tree=<scalar>

Compile-time option that sets the value of the DTrace tree dump bitmap.

tregs=<scalar>

Compile-time option that sets the size of the DIF tuple register set. The default value is 8.

udefs

Compile-time option that prevents unresolved user symbols.

undef=<string>

Compile-time option that undefines a symbol when invoking the preprocessor. This option is the same as running dtrace -U.

unodefs

Compile-time option that permits unresolved user symbols.

useruid

Compile-time option to use first UID that isn't in the system range .

verbose

Compile-time option that enables DIF verbose mode, which shows each compiled DIF object (DIFO).

version=<string>

Compile-time option that requests a specific version of the DTrace library.

zdefs

Compile-time option that permits probe definitions that match zero probes.

Runtime Options

Runtime options can control how the DTrace utility behaves.

aggsize=<size>: Runtime option that sets the buffer size for aggregation.
bpflog=<size>: Runtime option that forces reporting of the BPF verifier log (even if verification was successful).
bpflogsize: Runtime option that sets the maximum size of the BPF verifier log.
bufsize=<size>: Runtime option that sets the principal buffer size. The default buffer size is set to 4 MB. This option is the same as running dtrace -b.
cleanrate=<time>: Runtime option that sets the cleaning rate.
cpu=<scalar>: Runtime option that restricts tracing to a particular CPU.
destructive: Runtime option that permits destructive functions to run. This option is the same as running dtrace -w.
dynvarsize=<size>: Runtime option that sets dynamic variable space size.
lockmem: Runtime option that sets the locked pages limit.
maxframes=<scalar>: Runtime option that sets the maximum number of stack frames reported by the kernel.
noresolve: Runtime option that disables automatic resolving of userspace symbols.
nspec=<scalar>: Runtime option that sets the number of speculations.
pcapsize=<size>: Runtime option that sets the maximum packet data capture size.
scratchsize=<size>: Runtime option that sets the maximum DTrace scratch memory size. Some functions in DTrace require that scratch memory, is made available. For example, when you allocate memory in a program by using the alloca() function, scratch memory is used for this purpose. Scratch memory is only valid while a clause is being processed and is released when the clause has finished being processed. If there isn't enough scratch memory, a function in a DTrace script can return an error and any remaining processing of the clause might fail. The default value is 256 bytes.
specsize=<size>: Runtime option that sets the speculation buffer size.
stackframes=<scalar>: Runtime option that sets the number of stack frames. The default value is 20.
statusrate=<time>: Runtime option that sets the rate of status checking.
strsize=<size>: Runtime option that sets the string size. The default value is 256.
ustackframes=<scalar>: Runtime option that sets the number of user-land stack frames. The default value is 100.

Dynamic Runtime Options

Dynamic runtime options are specific to D programs themselves and are likely to change depending on program functionality and requirements.

aggrate=<time>

Dynamic runtime option that sets the amount of time between aggregation readings.

aggsortkey=<true|false>

Dynamic runtime option that sorts aggregations by key.

aggsortkeypos=<scalar>

Dynamic runtime option that sets the position, or number, of the aggregation key on which to sort.

aggsortpos=<scalar>

Dynamic runtime option that sets the position, or number, of the aggregation variable on which to sort

aggsortrev=<true|false>

Dynamic runtime option that sorts aggregations in reverse order.

flowindent

Dynamic runtime option that controls indentation.

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 <=.

This option is the same as running dtrace -F.

quiet

Dynamic runtime option that restricts output to explicitly traced data. This option isthe same as running dtrace -q.

quietresize

Dynamic runtime option that suppresses buffer-resize messages.

rawbytes

Dynamic runtime option that prints trace output in hexadecimal.

stackindent=<scalar>

Dynamic runtime option that sets the number of white space characters to use when indenting stack and ustack output. The default value is 14.

switchrate=<time>

Dynamic runtime option that sets the rate at which the buffer is read. You can increase the rate to help prevent data drops, or consider increasing the size of the principal buffer with the bufsize option.