DTrace User Guide

The contents of this Documentation are subject to the Public Documentation License Version 1.01 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at http://www.opensolaris.org/os/community/documentation/license.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.

U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

This distribution may include materials developed by third parties.

Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.

Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coffee Cup logo, docs.sun.com, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license agreements.

Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis et dans d'autres pays.

Cette distribution peut comprendre des composants développés par des tierces personnes.

Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.

Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coffee Cup, docs.sun.com, Java et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.

L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.

Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucléaires, des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement designés, sont rigoureusement interdites.

LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.

May 2006

Abstract

This book serves as an introduction to the dynamic tracing capabilities introduced in Solaris 10. The basic features of the DTrace framework are introduced. The book contains extensive examples of basic DTrace functions.


Table of Contents

Preface
Who Should Use This Book
Before You Read This Book
Related Books
Documentation, Support, and Training
Typographic Conventions
Shell Prompts in Command Examples
1. Introduction
DTrace Capabilities
Architecture overview
DTrace Providers
DTrace Probes
DTrace Predicates
DTrace Actions
D Scripting Language
2. DTrace Basics
Listing Probes
Specifying Probes in DTrace
Enabling Probes
DTrace Action Basics
Data Recording Actions
Destructive Actions
DTrace Aggregations
DTrace Aggregation Syntax
3. Scripting With the D Language
Writing D Scripts
Executable D Scripts
D Literal Strings
Creating D Scripts That Use Arguments
DTrace Built-in Variables
4. Using DTrace
Performance Monitoring
Examining Performance Problems With The sysinfo Provider
Tracing User Processes
Using the copyin and copyinstr Subroutines
Eliminating dtrace Interference
syscall Provider
The ustack Action
The pid Provider
Anonymous Tracing
Anonymous Enablings
Claiming Anonymous State
Anonymous Tracing Examples
Speculative Tracing
Speculation Interfaces
Creating a Speculation
Using a Speculation
Committing a Speculation
Discarding a Speculation
Speculation Example
Index

List of Tables

1. Typographic Conventions
2. Shell Prompts
2.1. DTrace Aggregating Functions
3.1. DTrace Consumer Options
4.1. DTrace Speculation Functions

List of Examples

2.1. Listing Probes by Specific Function
2.2. Listing Probes by Specific Module
2.3. Listing Probes by Specific Name
2.4. Listing Probes by Provider of Origin
2.5. Multiple Providers Supporting a Specific Function or Module
2.6. Enabling Probes by Module
2.7. Enabling Probes by Provider
2.8. Enabling Probes by Name
2.9. Enabling Probes by Fully Specified Name
2.10. Specifying a Probe's Action
2.11. Tracing an Executable Name
2.12. Tracing A System Call's Time of Entry
2.13. Specifying Multiple Actions
2.14. Using an Aggregating Function
3.1. Running a D Script from the Command Line
3.2. Using D Literal Strings With The trace Function
3.3. PID Argument Example
4.1. Using the quantize Aggregation Function With the sysinfo Probes
4.2. Finding the Source of Cross-Calls
4.3. userfunc.d: Trace User Function Entry and Return
4.4. errorpath.d: Trace User Function Call Error Path
4.5. Typical Use of The speculation Function
4.6. specopen.d: Code Flow for Failed open