Oracle® Linux

DTrace Guide

Oracle Legal Notices
Oracle Documentation License

E38608-21

November 2018

Table of Contents

Preface
1 About DTrace
1.1 Getting Started With DTrace
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 Clause Predicates
2.1.4 Probe 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 Predicate Examples
2.5 Output Formatting Examples
2.6 Array Overview
2.6.1 Associative Array Example
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 Operator 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 Scalar 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 DTrace Support for 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 Aggregation Concepts
3.2 Basic Aggregation Statement
3.3 Aggregation Examples
3.3.1 Basic Aggregation
3.3.2 Using Keys
3.3.3 Using the avg Function
3.3.4 Using the stddev Function
3.3.5 Using the quantize Function
3.3.6 Using the lquantize Function
3.4 Printing Aggregations
3.5 Data Normalization
3.6 Clearing Aggregations
3.7 Truncating Aggregations
3.8 Minimizing Drops
4 Actions and Subroutines
4.1 Action Functions
4.1.1 Default Action
4.1.2 Data Recording Actions
4.1.3 Destructive Actions
4.1.4 Special Actions
4.2 Subroutine Functions
4.2.1 alloca
4.2.2 basename
4.2.3 bcopy
4.2.4 cleanpath
4.2.5 copyin
4.2.6 copyinstr
4.2.7 copyinto
4.2.8 d_path
4.2.9 dirname
4.2.10 getmajor
4.2.11 getminor
4.2.12 htonl
4.2.13 htonll
4.2.14 htons
4.2.15 index
4.2.16 inet_ntoa
4.2.17 inet_ntoa6
4.2.18 inet_ntop
4.2.19 lltostr
4.2.20 mutex_owned
4.2.21 mutex_owner
4.2.22 mutex_type_adaptive
4.2.23 mutex_type_spin
4.2.24 ntohl
4.2.25 ntohll
4.2.26 ntohs
4.2.27 progenyof
4.2.28 rand
4.2.29 rindex
4.2.30 rw_iswriter
4.2.31 rw_read_held
4.2.32 rw_write_held
4.2.33 speculation
4.2.34 strchr
4.2.35 strjoin
4.2.36 strlen
4.2.37 strrchr
4.2.38 strstr
4.2.39 strtok
4.2.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 Action
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 Action
6.3 trace Default Format
7 Speculative Tracing
7.1 About Speculative Tracing
7.2 Speculation Interfaces
7.3 Creating a Speculation
7.4 Using a Speculation
7.5 Committing a Speculation
7.6 Discarding a Speculation
7.7 Example of a Speculation
7.8 Speculation Options and Tuning
8 dtrace Command Reference
8.1 dtrace Command Description
8.2 dtrace Command Options
8.3 dtrace Command Operands
8.4 dtrace Command 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 DTrace Providers
11.1 dtrace Provider
11.1.1 BEGIN Probe
11.1.2 END Probe
11.1.3 ERROR Probe
11.1.4 dtrace Stability
11.2 profile Provider
11.2.1 profile-n Probes
11.2.2 tick-n Probes
11.2.3 profile Probe Arguments
11.2.4 profile Probe Creation
11.2.5 prof Stability
11.3 fbt Provider
11.3.1 fbt Probes
11.3.2 fbt Probe Arguments
11.3.3 fbt Examples
11.3.4 Module Loading and fbt
11.3.5 fbt Stability
11.4 syscall Provider
11.4.1 syscall Probes
11.4.2 syscall Probe Arguments
11.4.3 syscall Stability
11.5 sdt provider
11.5.1 Creating sdt Probes
11.5.2 sdt Stability
11.6 pid Provider
11.6.1 Naming pid Probes
11.6.2 pid Probe Arguments
11.6.3 pid Stability
11.7 proc Provider
11.7.1 proc Probes
11.7.2 proc Probe Arguments
11.7.3 proc Examples
11.7.4 proc Stability
11.8 sched Provider
11.8.1 sched Probes
11.8.2 sched Probe Arguments
11.8.3 sched Examples
11.8.4 sched Stability
11.9 io Provider
11.9.1 io Probes
11.9.2 io Probe Arguments
11.9.3 io Examples
11.9.4 io Stability
11.10 fasttrap Provider
11.10.1 fasttrap Probes
11.10.2 fasttrap Stability
12 User Process Tracing
12.1 copyin and copyinstr Subroutines
12.1.1 Avoiding Errors
12.2 Eliminating dtrace Interference
12.3 Using the syscall Provider
12.4 ustack Action
12.5 uregs[] Array
12.6 Using the pid Provider
12.6.1 User Function Boundary Tracing
12.6.2 Tracing Arbitrary Instructions
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 Using Aggregations
15.3 Using Cacheable Predicates
16 DTrace Stability Features
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 D Operator
17.3 Process Model Translators
17.4 Stable Translations
18 DTrace Versioning
18.1 Versions and Releases
18.2 Versioning Options
18.3 Provider Versioning

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