10.1 Consumer Options

DTrace is tuned by setting or enabling options. The available options are described in the table below. For some options, dtrace provides a corresponding command-line option.

Table 10.1 DTrace Consumer Options

Option Name

Type

Value

Description

aggpercpu

Compile-time

Aggregate per CPU.

See Chapter 3, Aggregations.

aggrate

Dynamic run-time

time

Rate of aggregation reading.

See Chapter 3, Aggregations.

aggsize

Run-time

size

Aggregation buffer size.

See Chapter 3, Aggregations.

aggsortkey

Dynamic run-time

false or true

Sort aggregations by key.

See Chapter 3, Aggregations.

aggsortkeypos

Dynamic run-time

scalar

Number of the aggregation key on which to sort.

See Chapter 3, Aggregations.

aggsortpos

Dynamic run-time

scalar

Number of the aggregation variable on which to sort.

See Chapter 3, Aggregations.

aggsortrev

Dynamic run-time

false or true

Sort aggregations in reverse order.

See Chapter 3, Aggregations.

amin

Compile-time

string

Stability attribute minimum.

See Section 15.5, “Stability Enforcement”.

argref

Compile-time

Do not require all macro arguments to be used.

bufpolicy

Run-time

fill, ring, or switch

Buffer policy.

See Chapter 5, Buffers and Buffering .

bufresize

Run-time

auto or manual

Buffer resizing policy.

See Chapter 5, Buffers and Buffering .

bufsize

Run-time

size

Principal buffer size. Equivalent to dtrace option -b.

See Chapter 5, Buffers and Buffering .

cleanrate

Run-time

time

Cleaning rate.

See Chapter 7, Speculative Tracing.

core

Compile-time

false or true

Enable core dumping by dtrace.

cpp

Compile-time

Use cpp to preprocess the input file.

cpphdrs

Compile-time

Specify the -H option to cpp to print the name of each header file used.

cpppath

Compile-time

string

Specify the path name of cpp.

cpu

Run-time

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 option -D.

destructive

Run-time

Allow destructive actions. Equivalent to dtrace option -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 used in a program at the end of a D compilation run.

dynvarsize

Run-time

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 postinit

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. (On Oracle Solaris, DTrace grabs the process immediately after the #pragma init constructors are executed.)

preinit

Halt after initialization of the dynamic linker loader (ld.so) and before constructor invocation. This is the 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 run-time

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 option -F.

See Chapter 8, The dtrace Utility.

incdir

Compile-time

string

Add a #include directory to the preprocessor search path. Equivalent to dtrace option -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 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

Run-time

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 run-time

Output only explicitly traced data. Equivalent to dtrace option -q.

See Chapter 8, The dtrace Utility.

quietresize

Dynamic run-time

Suppress buffer-resize messages.

See Chapter 5, Buffers and Buffering.

rawbytes

Dynamic run-time

Always print tracemem output in hexadecimal.

See Chapter 4, Actions and Subroutines.

specsize

Run-time

size

Speculation buffer size.

See Chapter 7, Speculative Tracing.

stackframes

Run-time

scalar

Number of stack frames.

See Chapter 4, Actions and Subroutines.

stackindent

Dynamic run-time

scalar

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

See Chapter 4, Actions and Subroutines.

statusrate

Run-time

time

Rate of status checking.

stdc

Compile-time

a, c, s, or t

Specify ISO C conformance settings for the preprocessor when invoking cpp using the -C option.

The a, c, and t settings include the option -std=gnu99 (conformance with 1999 C standard including GNU extensions).

The s setting includes the option -traditional-cpp (conformance with K&R C) .

strip

Compile-time

Strip non-loadable sections from the program.

strsize

Run-time

size

String size.

See Section 2.11, “Strings” .

switchrate

Dynamic run-time

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 option -U.

unodefs

Compile-time

Permit unresolved user symbols.

ustackframes

Run-time

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