10.1 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 Chapter 3, Aggregations.

aggrate

Dynamic runtime

time

Rate of aggregation reading.

See Chapter 3, Aggregations.

aggsize

Runtime

size

Aggregation buffer size/

See Chapter 3, Aggregations.

aggsortkey

Dynamic runtime

false or true

Sort aggregations by key.

See Chapter 3, Aggregations.

aggsortkeypos

Dynamic runtime

scalar

Number of the aggregation key on which to sort.

See Chapter 3, Aggregations.

aggsortpos

Dynamic runtime

scalar

Number of the aggregation variable on which to sort

See Chapter 3, Aggregations.

aggsortrev

Dynamic runtime

false or true

Sort aggregations in reverse order.

See Chapter 3, Aggregations.

amin

Compile-time

string

Stability attribute minimum.

See Section 16.5, “Stability Enforcement”

argref

Compile-time

 

Do not require all macro arguments to be used.

bufpolicy

Runtime

fill, ring, or switch

Buffer policy.

See Chapter 5, Buffers and Buffering .

bufresize

Runtime

auto or manual

Buffer resizing policy.

See Chapter 5, Buffers and Buffering .

bufsize

Runtime

size

Principal buffer size (equivalent to the dtrace -b).

See Chapter 5, Buffers and Buffering .

cleanrate

Runtime

time

Cleaning rate.

See Chapter 7, 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 Chapter 5, 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 Chapter 9, 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 Chapter 4, 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 Section 2.9, “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 halts a new process after grabbing it:

exec

Halt the process immediately after exec().

main

Halt after constructor execution, immediately before main(). For stripped binaries, main and postinit are silently converted to preinit because a symbol table is required to locate main().

postinit

Equivalent to main.

preinit

Halt after initialization of the dynamic linker loader (ld.so) and before constructor invocation (default behavior).

For statically linked binaries, preinit is equivalent to exec, and it might not skip ld.so initialization, which can happen after main().

For stripped, statically linked binaries, both postinit and main are equivalent to preinit, because the main symbol cannot be looked up if there is no symbol table.

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 Chapter 8, 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 Chapter 7, 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 Chapter 8, dtrace Command Reference.

quietresize

Dynamic runtime

 

Suppress buffer-resize messages.

See Chapter 5, Buffers and Buffering.

rawbytes

Dynamic runtime

 

Always print trace output in hexadecimal.

See Chapter 4, Actions and Subroutines.

specsize

Runtime

size

Speculation buffer size.

See Chapter 7, Speculative Tracing.

stackframes

Runtime

scalar

Number of stack frames.

See Chapter 4, Actions and Subroutines.

stackindent

Dynamic runtime

scalar

Number of white space characters to use when indenting stack and ustack output.

See Chapter 4, 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 Section 2.11, “DTrace Support for Strings”.

switchrate

Dynamic runtime

time

Rate of buffer switching.

See Chapter 5, 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 Chapter 4, 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.