Oracle® Linux

DTrace Guide

Oracle Legal Notices
Oracle Documentation License

E38608-14

August 2015

Table of Contents

Preface
1 About DTrace
1.1 Getting Started
1.2 Providers and Probes
2 The D Programming Language
2.1 D Program Structure
2.1.1 Probe Clauses and Declarations
2.1.2 Probe Descriptions
2.1.3 Predicates
2.1.4 Actions
2.1.5 Order of Execution
2.1.6 Use of the C Preprocessor
2.2 Compilation and Instrumentation
2.3 Variables and Arithmetic Expressions
2.4 Predicates
2.5 Output Formatting
2.6 Arrays
2.7 External Symbols and Types
2.8 Types, Operators, and Expressions
2.8.1 Identifier Names and Keywords
2.8.2 Data Types and Sizes
2.8.3 Constants
2.8.4 Arithmetic Operators
2.8.5 Relational Operators
2.8.6 Logical Operators
2.8.7 Bitwise Operators
2.8.8 Assignment Operators
2.8.9 Increment and Decrement Operators
2.8.10 Conditional Expressions
2.8.11 Type Conversions
2.8.12 Precedence
2.9 Variables
2.9.1 Scalar Variables
2.9.2 Associative Arrays
2.9.3 Thread-Local Variables
2.9.4 Clause-Local Variables
2.9.5 Built-in Variables
2.9.6 External Variables
2.10 Pointers and Arrays
2.10.1 Pointers and Addresses
2.10.2 Pointer Safety
2.10.3 Array Declarations and Storage
2.10.4 Pointer and Array Relationship
2.10.5 Pointer Arithmetic
2.10.6 Generic Pointers
2.10.7 Multi-Dimensional Arrays
2.10.8 Pointers to DTrace Objects
2.10.9 Pointers and Address Spaces
2.11 Strings
2.11.1 String Representation
2.11.2 String Constants
2.11.3 String Assignment
2.11.4 String Conversion
2.11.5 String Comparison
2.12 Structs and Unions
2.12.1 Structs
2.12.2 Pointers to Structs
2.12.3 Unions
2.12.4 Member Sizes and Offsets
2.12.5 Bit-Fields
2.13 Type and Constant Definitions
2.13.1 typedefs
2.13.2 Enumerations
2.13.3 Inlines
2.13.4 Type Namespaces
3 Aggregations
3.1 Aggregating Functions
3.2 About Aggregations
3.3 Printing Aggregations
3.4 Data Normalization
3.5 Clearing Aggregations
3.6 Truncating Aggregations
3.7 Minimizing Drops
4 Actions and Subroutines
4.1 Actions
4.2 Default Action
4.3 Data Recording Actions
4.3.1 freopen
4.3.2 ftruncate
4.3.3 func
4.3.4 mod
4.3.5 printa
4.3.6 printf
4.3.7 stack
4.3.8 sym
4.3.9 trace
4.3.10 tracemem
4.3.11 ustack
4.3.12 uaddr
4.3.13 usym
4.4 Destructive Actions
4.4.1 Process Destructive Actions
4.4.2 Kernel Destructive Actions
4.5 Special Actions
4.5.1 Speculative Actions
4.5.2 exit
4.5.3 setopt
4.6 Subroutines
4.6.1 alloca
4.6.2 basename
4.6.3 bcopy
4.6.4 cleanpath
4.6.5 copyin
4.6.6 copyinstr
4.6.7 copyinto
4.6.8 d_path
4.6.9 dirname
4.6.10 getmajor
4.6.11 getminor
4.6.12 htonl
4.6.13 htonll
4.6.14 htons
4.6.15 index
4.6.16 inet_ntoa
4.6.17 inet_ntoa6
4.6.18 inet_ntop
4.6.19 lltostr
4.6.20 mutex_owned
4.6.21 mutex_owner
4.6.22 mutex_type_adaptive
4.6.23 mutex_type_spin
4.6.24 ntohl
4.6.25 ntohll
4.6.26 ntohs
4.6.27 progenyof
4.6.28 rand
4.6.29 rindex
4.6.30 rw_iswriter
4.6.31 rw_read_held
4.6.32 rw_write_held
4.6.33 speculation
4.6.34 strchr
4.6.35 strjoin
4.6.36 strlen
4.6.37 strrchr
4.6.38 strstr
4.6.39 strtok
4.6.40 substr
5 Buffers and Buffering
5.1 Principal Buffers
5.2 Principal Buffer Policies
5.2.1 switch Policy
5.2.2 fill Policy
5.2.3 fill Policy and END Probes
5.2.4 ring Policy
5.3 Other Buffers
5.4 Buffer Sizes
5.5 Buffer Resizing Policy
6 Output Formatting
6.1 printf
6.1.1 Conversion Specifications
6.1.2 Flag Specifiers
6.1.3 Width and Precision Specifiers
6.1.4 Size prefixes
6.1.5 Conversion Formats
6.2 printa
6.3 trace Default Format
7 Speculative Tracing
7.1 Speculation Interfaces
7.2 Creating a Speculation
7.3 Using a Speculation
7.4 Committing a Speculation
7.5 Discarding a Speculation
7.6 Speculation Example
7.7 Speculation Options and Tuning
8 The dtrace Utility
8.1 Description
8.2 Options
8.3 Operands
8.4 Exit Status
9 Scripting
9.1 Interpreter Files
9.2 Macro Variables
9.3 Macro Arguments
9.4 Target Process ID
10 Options and Tunables
10.1 Consumer Options
10.2 Modifying Options
11 Providers
11.1 dtrace Provider
11.1.1 BEGIN Probe
11.1.2 END Probe
11.1.3 ERROR Probe
11.1.4 Stability
11.2 profile Provider
11.2.1 profile-n Probes
11.2.2 tick-n Probes
11.2.3 Probe Creation
11.2.4 Stability
11.3 syscall Provider
11.3.1 Probes
11.3.2 Arguments
11.3.3 Stability
11.4 sdt provider
11.4.1 Creating SDT Probes
11.4.2 Stability
11.5 proc Provider
11.5.1 Probes
11.5.2 Arguments
11.5.3 lwpsinfo_t
11.5.4 psinfo_t
11.5.5 Examples
11.5.6 Stability
11.6 sched Provider
11.6.1 Probes
11.6.2 Arguments
11.6.3 cpuinfo_t
11.6.4 Examples
11.6.5 Stability
11.7 io Provider
11.7.1 Probes
11.7.2 Arguments
11.7.3 bufinfo_t
11.7.4 devinfo_t
11.7.5 fileinfo_t
11.7.6 Examples
11.7.7 Stability
11.8 fasttrap Provider
11.8.1 Probes
11.8.2 Stability
12 User Process Tracing
12.1 copyin and copyinstr
12.1.1 Avoiding Errors
12.2 Eliminating dtrace Interference
12.3 syscall Provider
12.4 ustack Action
12.5 uregs[] Array
13 Statically Defined Tracing of User Applications
13.1 Choosing the Probe Points
13.2 Adding Probes to an Application
13.2.1 Defining Providers and Probes
13.2.2 Adding Probes to Application Code
13.2.3 Testing if a Probe Is Enabled
13.2.4 Building Applications with Probes
13.2.5 Using Statically Defined Probes
14 Statically Defined Tracing of Kernel Modules
14.1 Inserting Static Probe Points
14.2 Building Modules with Static Probes
14.3 Using DTrace to Test Modules with Static Probes
15 Performance Considerations
15.1 Limit Enabled Probes
15.2 Use Aggregations
15.3 Use Cacheable Predicates
16 Stability
16.1 Stability Levels
16.2 Dependency Classes
16.3 Interface Attributes
16.4 Stability Computations and Reports
16.5 Stability Enforcement
17 Translators
17.1 Translator Declarations
17.2 xlate Operator
17.3 Process Model Translators
17.4 Stable Translations
18 Versioning
18.1 Versions and Releases
18.2 Versioning Options
18.3 Provider Versioning

Copyright © 2013, 2015, Oracle and/or its affiliates. All rights reserved. Legal Notices