CONTENTS Title Page Copyright Page Preface 1 Introduction to DECtrace 1.1 What Is Event-Based Data Collection? 1.2 What Can DECtrace Do for You? 1.3 How Does DECtrace Work? 1.3.1 DECtrace Registrar Process 1.3.2 DECtrace Administration Database 1.4 Overview of DECtrace Processing 1.5 Explanation of Sample Application 2 Creating a Facility Selection 2.1 Choosing Which Data to Collect 2.2 Creating a Selection 2.3 Deleting a Selection 2.4 Displaying Information About a Selection 2.4.1 BRIEF Format 2.4.2 FULL Format 2.4.3 NAMES_ONLY Format 3 Scheduling Data Collection 3.1 Choosing the Processes from Which to Collect Data 3.1.1 Process Registration 3.1.2 Using the Registration ID 3.1.3 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 Generating Reports 4.1 Overview of Reporting 4.2 Merging and Formatting Data Collection Files 4.2.1 Merging and Formatting the Collected Data into an Rdb/VMS Database 4.2.2 Merging and Formatting the Collected Data into a VAX RMS File 4.3 Formatting Optimization 4.4 Report Types 4.4.1 Detail Report 4.4.2 Frequency Report 4.4.3 Summary Report 4.5 Text Wrapping in Reports 4.5.1 Groupable Items 4.5.2 Groups 4.5.3 Headers 4.5.4 Report Item Text 4.6 Special Cases for Reporting on Duration Events 4.7 Report Optimization 4.8 Report Options 4.8.1 Creating a Customized Report 5 Instrumenting Applications 5.1 Programming Interface 5.1.1 LSE Environment Files Available 5.1.2 Language Definition Files 5.1.3 Using the FLAGS Argument to Instrument Efficiently 5.2 DECtrace Data Structures 5.3 Determining Your Events 5.4 Using EPC$INIT to Register a Facility 5.4.1 Waiting for the Registrar to Respond 5.4.2 Waiting for EPC$INIT to Complete 5.5 Coding an Event in the ATM Sample Application 5.6 Instrumenting an Application in VAX C 5.6.1 Instrumenting Simple Events 5.6.2 Instrumenting Events and Items 5.6.2.1 Collecting Basic Facility-Specific Items 5.6.2.2 Collecting Facility-Specific Items Efficiently 5.7 Instrumenting a Multi-Threaded Facility Using VAX BLISS-32 5.7.1 Call EPC$INIT to Register the NEW_TOOL Facility 5.7.2 Call EPC$SET_CONTEXT to Set Thread Context 5.7.3 Call EPC$DELETE_CONTEXT to Delete the Thread Context 5.7.4 Call EPC$START_EVENT and EPC$END_EVENT to Collect Event Data 5.8 Linking an Instrumented Program 6 Creating Facility Definitions 6.1 Creating a Facility Definition 6.1.1 Creating and Defining Events 6.1.2 Creating and Defining Items 6.1.3 Creating and Defining Collection Classes 6.2 Deleting Facility Definitions 6.3 Transporting Facility Definitions 6.3.1 Extracting Definitions 6.3.2 Inserting Definitions Using a KITINSTAL.COM Procedure 6.3.3 Inserting Definitions Without KITINSTAL.COM 6.4 Displaying Facility Definitions 6.4.1 FULL Format 6.4.2 NAMES_ONLY Format 6.5 Facility Definition Options 7 DECtrace 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 SELECTION DELETE DEFINITION DELETE SELECTION EXIT EXTRACT DEFINITION FORMAT HELP INSERT DEFINITION REPORT REPORT Options-EVENT REPORT Options-ITEM REPORT Options-RESTRICTION SCHEDULE COLLECTION SET ACCESS SET HISTORY SHOW ACCESS SHOW COLLECTION SHOW DEFINITION SHOW HISTORY SHOW REGISTER SHOW SELECTION SHOW VERSION SPAWN STOP SYSTEM 8 DECtrace Service Routines 8.1 Error Handling 8.2 Program Execution Modes EPC$DELETE_CONTEXT EPC$END_EVENT EPC$END_EVENTW EPC$EVENT EPC$EVENTW EPC$INIT EPC$SET_CONTEXT EPC$START_EVENT EPC$START_EVENTW 9 System Management Tasks 9.1 Required Account and Process Quotas 9.2 Controlling DECtrace 9.2.1 Starting DECtrace 9.2.2 Stopping DECtrace 9.2.3 Recovering From a System Crash 9.3 Installing Facilities on Your System 9.3.1 Installing New Facilities 9.3.2 Installing New Versions of Existing Facilities 9.3.3 Installing a New Version of Rdb/VMS 9.4 Managing the History Database 9.5 Disabling Data Collection 9.6 Using DECtrace Efficiently 9.7 Troubleshooting DECtrace 9.7.1 Error Messages and Recovery Procedures A Formatted Database and File Layouts A.1 The Rdb/VMS Database A.1.1 The Data Types A.1.2 String Data Segmentation A.1.3 Relations for the Control Information A.1.3.1 The EPC$IDENT Relation A.1.3.2 The EPC$SELECTION Relation A.1.3.3 The EPC$COLLECTION Relation A.1.3.4 The EPC$DCF Relation A.1.3.5 The EPC$REG Relation A.1.3.6 The EPC$FACILITY Relation A.1.3.7 The EPC$EVENT Relation A.1.3.8 The EPC$ITEM Relation A.1.3.9 The EPC$EVENT_ITEM Record A.1.3.10 The EPC$PROCESS Relation A.1.3.11 The EPC$IMAGE Relation A.1.3.12 The EPC$DCF_IMAGE Relation A.1.3.13 The EPC$FACILITY_IMAGE Relation A.1.4 Relations for the Collected Data A.1.5 The Entity Relationship Diagram for the Database A.1.6 The Predefined Views A.1.6.1 Relating Collection Information with Event Data A.1.6.2 Relating Selection and Collection Information with Event Data A.1.6.3 Relating Image Information with Event Data A.1.6.4 Relating Process and Image Information with Event Data A.1.7 Limitations A.2 The VAX RMS File Format A.2.1 Data Types A.2.1.1 Date A.2.1.2 Fixed ASCIC/ASCIW String A.2.2 Records Organization A.2.2.1 Control Records A.2.2.1.1 FMTDICT Record A.2.2.1.2 COLLECTION Record A.2.2.1.3 FACILITY Record A.2.2.1.4 DCF Record A.2.2.1.5 IMAGE Record A.2.2.1.6 FACILITY-REGISTRATION Record A.2.2.1.7 EVENT Record A.2.2.1.8 Item Descriptor A.2.2.2 Data Collection Records Glossary administration database . . . DECtrace service routines duration event . . . facility definition facility library . . . item name local collection . . . source program start event . . . start event EXAMPLES 2-1 Display Format for SHOW DEFINITION /FORMAT=NAMES_ONLY 2-2 Display for SHOW SELECTION Using the Brief Format 2-3 Display for SHOW SELECTION Using the Full Format 2-4 Display for SHOW SELECTION Using the Names Only Format 3-1 Process Registration Display 3-2 Display Format for SHOW REGISTER/CLUSTER 3-3 Sample Command Procedure for Starting a Local Collection 3-4 Display for SHOW COLLECTION Using the Brief Format 3-5 Display for SHOW HISTORY /FORMAT=ERROR 3-6 Display for SHOW HISTORY /FORMAT=INFORMATIONAL 4-1 Display for Detail Report 4-2 Sample Detail Report Based on ATM Data 4-3 Display for Frequency Report Using /INTERVAL=SECONDS 4-4 Sample Frequency Report Based on ATM Data 4-5 Display for Summary Report 4-6 Sample Summary Report Based on ATM Data 4-7 Wrapping of a Groupable Item 4-8 Wrapping of Groups 4-9 Wrapping of Headers 4-10 Wrapping of Report Item Text 4-11 Using Reporting Options to Generate a Customized Report 4-12 Sample DECtrace Report Based on VAX DBMS Data 5-1 Instrumentation of EPC$INIT in the ATM Application 5-2 Code to Guarantee Collection of First Events 5-3 Instrumentation of the WITHDRAWAL Event in the ATM Application 5-4 DB Sample Facility 5-5 Instrumentation Using LIB$FIND_IMAGE_SYMBOL 6-1 Sample Procedure to Insert Binary Facility Definitions 6-2 Display for SHOW DEFINITION Using the Full Format 6-3 Display for SHOW DEFINITION Using the Names Only Format FIGURES 1-1 Overview of DECtrace Processing 5-1 Flowchart of the Sample Application Showing One Event A-1 The Entity Relationship Diagram for the Database TABLES 2-1 Commands for Manipulating Collection Definitions 3-1 Commands for Manipulating Data Collections 4-1 Commands for Generating Reports 4-2 Format Optimization Parameters 4-3 DECtrace Reports 4-4 Data Formats 4-5 Parts of a Summary Report Event Group 5-1 DECtrace Service Routines 5-2 Resource Utilization Items 5-3 Summary of Facility Definition Options 6-1 Facility Definition Commands 6-2 Standard Resource Utilization Items 6-3 Summary of Facility Definition Options 7-1 DECtrace Commands 7-2 ITEM Data Types 7-3 ITEM Default Report Widths 7-4 ITEM Usage Types 7-5 ITEM Usage Types by Data Type 7-6 Rdb/VMS Optimization Parameters 7-7 Collection File Characteristics 8-1 DECtrace Service Routines 9-1 User Account Quotas for Using DECtrace 9-2 Troubleshooting DECtrace Problems A-1 Rdb/VMS Representations of DECtrace-Supported Data Types A-2 The point event relation EPC$1_40_REQUEST A-3 A relation for segmented strings A-4 EPC$IDENT Relation A-5 EPC$SELECTION Relation A-6 EPC$COLLECTION Relation A-7 EPC$DCF Relation A-8 EPC$REG Relation A-9 EPC$FACILITY Relation A-10 EPC$EVENT Relation A-11 EPC$ITEM Relation A-12 EPC$EVENT_ITEM Relation A-13 EPC$PROCESS Relation A-14 EPC$IMAGE Relation A-15 EPC$DCF_IMAGE Relation A-16 EPC$FACILITY_IMAGE Relation A-17 Event Relation Fields A-18 Record Type Literal A-19 FMTDICT Record A-20 COLLECTION Record A-21 FACILITY Record A-22 DCF Record A-23 IMAGE Record A-24 FACILITY-REGISTRATION Record A-25 Event Record Description A-26 Item Descriptor A-27 Data Collection Record