Oracle® Linux

Dynamic Tracing Guide for Release 6

Oracle Legal Notices

E38608-08

May 2014

Abstract

This manual provides information about the Dynamic Tracing facility (version 0.4) for Oracle Linux engineered by Oracle.

Document generated on: 2014-05-15 (revision: 1863)


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 for 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 Performance Considerations
14.1 Limit Enabled Probes
14.2 Use Aggregations
14.3 Use Cacheable Predicates
15 Stability
15.1 Stability Levels
15.2 Dependency Classes
15.3 Interface Attributes
15.4 Stability Computations and Reports
15.5 Stability Enforcement
16 Translators
16.1 Translator Declarations
16.2 xlate Operator
16.3 Process Model Translators
16.4 Stable Translations
17 Versioning
17.1 Versions and Releases
17.2 Versioning Options
17.3 Provider Versioning