CONTENTS Title Page Copyright Page Send Us Your Comments Preface 1 Introduction to Oracle Trace 1.1 What Can Oracle Trace Do for You? 1.1.1 Database Tuning 1.1.2 Transaction Processing 1.1.3 Relating Events Among Facilities 1.2 What Is Event-Based Data Collection? 1.3 Description of the Sample Applications 1.4 How to Use the Sample Applications 1.5 Overview of Oracle Trace Commands 1.6 How to Use Oracle Trace 1.7 Oracle Trace Internal Components 1.7.1 Oracle Trace Registrar Process 1.7.2 Oracle Trace Administration Database 1.7.3 History Database 1.8 Details of How Oracle Trace Sets Up Collections 2 Creating a Facility Selection 2.1 Choosing Which Data to Collect 2.2 How to Ensure the Presence of a Facility Definition 2.3 Creating a Selection 2.4 Deleting a Selection 2.5 Displaying Information About a Selection 2.5.1 BRIEF Format 2.5.2 FULL Format 2.5.3 NAMES_ONLY Format 3 Scheduling Data Collection 3.1 Limiting Collections to Specific Processes 3.1.1 Displaying Information About Process Registration 3.2 Scheduling a Collection 3.2.1 Scheduling Data Collection on a Standalone System 3.2.2 Scheduling Data Collection on a Cluster 3.2.3 Scheduling Data Collection on Part of a Cluster 3.3 Data Collection Files 3.3.1 File Protection Schemes 3.4 Canceling Data Collection 3.5 Displaying Information About Data Collection 3.5.1 Displaying the Schedule for Data Collection 3.5.2 Displaying the History for Collections 4 Instrumenting Applications 4.1 The Oracle Trace Service Routines 4.2 How Oracle Trace Interacts with a Facility 4.3 Oracle Trace Buffering 4.4 Aids to Instrumenting 4.4.1 Examples of Instrumented Applications 4.4.2 LSE Environment Files 4.4.3 Language Definition Files 4.5 Using the Flags Argument to Instrument Efficiently 4.6 Identifying Events and Data Items of Interest 4.7 Defining Data Structures for Your Application 4.7.1 Event Collection Flags List 4.7.2 Item Flags List 4.7.3 User-Defined Buffer 4.7.3.1 How to Define a User-Defined Buffer in C 4.7.3.2 How to Define a User-Defined Buffer in COBOL 4.8 Using EPC$INIT to Register a Facility 4.8.1 Waiting for the Registrar to Respond 4.8.2 Waiting for EPC$INIT to Complete 4.9 Checklist for Instrumenting Events 4.9.1 Verifying That Oracle Trace Is Collecting an Event 4.9.2 Calling Event Service Routines 4.9.2.1 Designating Events to Collect Standard Resource Items 4.9.2.2 Defining Events in Both the Application and the Facility Definition 4.9.2.3 Defining Facility-Specific Items in Both the Application and the Facility Definition 4.9.2.4 Collecting Facility-Specific Items More Efficiently 4.9.3 Relating Events Among Applications 4.10 Instrumenting a Multithreaded Facility 4.10.1 Setting Thread Context 4.10.2 Deleting the Thread Context 4.11 Linking an Instrumented Program 5 Creating Facility Definitions 5.1 Creating a Facility Definition 5.1.1 Creating and Defining Events 5.1.2 Creating and Defining Items 5.1.3 Creating and Defining Collection Classes 5.2 Relating Events Among Facilities 5.2.1 Defining Relationships Among Events 5.3 Deleting Facility Definitions 5.4 Transporting Facility Definitions 5.4.1 Extracting Definitions 5.4.2 Inserting Definitions Using a KITINSTAL.COM Procedure 5.4.3 Inserting Definitions Without KITINSTAL.COM 5.5 Displaying Facility Definitions 5.5.1 FULL Format 5.5.2 NAMES_ONLY Format 5.6 Facility Definition Options 6 Oracle Trace Commands @ (Execute Procedure) CANCEL COLLECTION CREATE DEFINITION CREATE DEFINITION Options-ITEM CREATE DEFINITION Options-GROUP CREATE DEFINITION Options-EVENT CREATE DEFINITION Options-CLASS CREATE DEFINITION Options-DEFAULT_CLASS CREATE DEFINITION Options-RELATE CREATE SELECTION DELETE DEFINITION DELETE SELECTION EXIT EXTRACT DEFINITION HELP INSERT DEFINITION SCHEDULE COLLECTION SET ACCESS SET HISTORY SHOW ACCESS SHOW COLLECTION SHOW DEFINITION SHOW HISTORY SHOW REGISTER SHOW SELECTION SHOW VERSION SPAWN STOP SYSTEM 7 Oracle Trace Service Routines 7.1 Error Handling 7.2 Program Execution Modes EPC$DELETE_CONTEXT EPC$END_EVENT EPC$END_EVENTW EPC$EVENT EPC$EVENTW EPC$GET_CF_ITEMS EPC$INIT EPC$SET_CF_ITEMS EPC$SET_CF_VALUE EPC$SET_CONTEXT EPC$START_EVENT EPC$START_EVENTW 8 System Management Tasks 8.1 Required Account and Process Quotas 8.2 Controlling Oracle Trace 8.2.1 Starting Oracle Trace 8.2.2 Stopping Oracle Trace 8.2.3 Recovering from a System Crash 8.3 Installing Facilities on Your System 8.3.1 Installing New Facilities 8.3.2 Installing New Versions of Existing Facilities 8.3.3 Installing a New Version of Oracle Rdb 8.4 Managing the History Database 8.5 Disabling Data Collection 8.6 Using Oracle Trace Efficiently 9 Troubleshooting Oracle Trace 9.1 Error Messages and Recovery Procedures A Example of the ATM-Sample Facility Instrumented B Registering a Cross-Facility Item Glossary administration database . . . data collection file data formatting . . . event name event pair . . . interval item . . . point event registered facility . . . start event