Escolar Documentos
Profissional Documentos
Cultura Documentos
Wily Technology, Inc. 8000 Marina Boulevard, Suite 700 Brisbane, CA 94005 1 888 GET WILY < US Toll Free > 415 562 2000 < phone > 415 562 2100 < fax > www.wilytech.com
Contents - Chapters
Contents - Detailed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Chapter 1 Introscope Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Chapter 2 Preparing For Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Chapter 3 Installing Introscope Components . . . . . . . . . . . . . . . . . . . . . . . . . 35 Chapter 4 Configuring and Running the Introscope Enterprise Manager. . . . 57 Chapter 5 Configuring Introscope Security and Permissions . . . . . . . . . . . . . 76 Chapter 6 Configuring Java Applications With Introscope . . . . . . . . . . . . . . . 94 Chapter 7 Configuring WebLogic Server With Introscope . . . . . . . . . . . . . . . 95 Chapter 8 Configuring WebSphere Application Server With Introscope . . . 106 Chapter 9 Configuring WebSphere on z/OS With Introscope . . . . . . . . . . . 117 Chapter 10 Configuring Sun ONE Application Server With Introscope . . . . 128 Chapter 11 Configuring Oracle Application Server 10g With Introscope . . . 136 Chapter 12 Configuring SAP NetWeaver With Introscope . . . . . . . . . . . . . . 142 Chapter 13 Configuring Other Application Servers or Applications With Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Chapter 14 Configuring the Java Applications Manually With ProbeBuilder 155 Chapter 15 Optional Introscope Configurations. . . . . . . . . . . . . . . . . . . . . . 168 Chapter 16 Database Configuration and Reporting . . . . . . . . . . . . . . . . . . . 202 Chapter 17 ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Appendix A Introscope Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Appendix B Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 3
Contents - Detailed
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Introscope 6.0.1 Installation and Configuration Guide Audience Introscope 6.0.1 User Guides . . . . . . . . . . . . . . Introscope 6.0.1 Upgrade Guide . . . . . . . . . . Introscope 6.0.1 Installation and Configuration Introscope 6.0.1 Workstation Guide . . . . . . . Introscope 6.0.1 WebView Guide . . . . . . . . . . . . . . . . . . . . 15 . . . . . . . . . . . . . . . . . . . . . . . . . 15 . . . . . . . . . . . . . . . . . . . . . . . . . 15 Guide (this guide) . . . . . . . . . . . 15 . . . . . . . . . . . . . . . . . . . . . . . . . 15 . . . . . . . . . . . . . . . . . . . . . . . . . 16
Organization of the Introscope 6.0.1 Installation Guide . . . . . . . . . . . . . . . . . . 16 Need Help With Installation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Supported Modes By Platform Step 3: Check System Requirements Supported Platforms . . . . . . . Space Requirements . . . . . . . Memory Requirements . . . . . . Bundled JVMs . . . . . . . . . . . . JVM Used by Installer . . . . . . Step 4: Review Installation Notes . .
.. . .. .. .. .. .. ..
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. 29 . 29 . 29 . 30 . 31 . 31 . 32 . 32
Information to Collect Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Enterprise Manager Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Reviewing Installation and Configuration Process . . . . . . . . . . . . . . . . . . . . . . . 33 Starting the Installation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Installing Introscope In Console Mode . . . . . . . . Launching Console Mode Installer . . . . . . . . . . Using z/OS . . . . . . . . . . . . . . . . . . . . . . Using Any Other Platform . . . . . . . . . . . Next Steps - Installing Introscope Agent .
Installing Introscope In Silent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Response File Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Using an Automatically-generated Response File . . . . . . . . . . . . . . . . . . . 51 Using a Manually-Configured Sample Response File . . . . . . . . . . . . . . . . . 51 Launching Silent Mode Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Using z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Using Any Other Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Next Steps - Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . 53 Uninstalling Introscope . . . . . . . . . . . . . . . . . . Uninstall Modes . . . . . . . . . . . . . . . . . . . . . Forcing an Uninstall Mode . . . . . . . . . . Running Uninstaller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 . . . . . . . . . . . . . . . . . . . 54 . . . . . . . . . . . . . . . . . . . 54 . . . . . . . . . . . . . . . . . . . 54
Page 5
Enterprise Manager Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 SmartStorTM Data Storage . . . . . . . . . . . . . . . . . . . . Configuring SmartStor . . . . . . . . . . . . . . . . . . . . . Enabling SmartStor . . . . . . . . . . . . . . . . . . . Determining SmartStor System Requirements Specifying SmartStor Data Tier Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 . . . . . . . . . . . . . . . . . . . . 60 . . . . . . . . . . . . . . . . . . . . 60 . . . . . . . . . . . . . . . . . . . . 61 . . . . . . . . . . . . . . . . . . . . 61
Transaction Event Database Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Configuring Transaction Event Database Settings . . . . . . . . . . . . . . . . . . . . . . . 62 Enterprise Manager Metric Throttle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Configuring Enterprise Manager Metric Throttle . . . . . . . . . . . . . . . . . . . . . . . . 63 Enterprise Manager Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Running Enterprise Manager in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . . 63 Redirecting Enterprise Manager Output to a File . . . . . . . . . . . . . . . . . . . . . . . . 64 Running Enterprise Manager in nohup Mode on UNIX . . . . . . . . . . . . . . . . . . . . 64 Additional Enterprise Manager Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Configuring Enterprise Manager To Run As A Windows Service . . . . . . . . . . . . . 65 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Configure and Register Enterprise Manager as a Windows Service . . . . . . . . . . . 65 Register Enterprise Manager as a Service . . . . . . . . . . . . . . . . . . . . . . . . 65 Deregister Enterprise Manager(s) Running as a Windows Service . . . . . . . . . . . . 66 Changing Windows Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Running the Enterprise Manager as a Windows Service . . . . . . . . . . . . . . . . . . . 67 Connecting to a Database Configured After Enterprise Manager Service Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Configuring Enterprise Manager To Run As a z/OS Batch Job . . . . . . . . . . . . . . 67 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Overview of Installation Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Copying and Customizing Introscope Enterprise Manager Files . . . . . . . . . . 70 Customizing the Introscope Enterprise Manager Properties File . . . . . . . . . 70 Customizing runem.sh the UNIX Shell Script . . . . . . . . . . . . . . . . . . . . . 71 Copying Introscope Enterprise Manager z/OS files to a z/OS Partitioned Dataset (PDS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Customizing the z/OS PROC That Invokes BPXBATCH . . . . . . . . . . . . . . . . 72 Running the Introscope Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Executing the z/OS PROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Starting the Introscope Enterprise Manager automatically . . . . . . . . . . . . . 74 DB2 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Database Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . . 75
SuperDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User-defined Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Domain Attributes and Syntax . . . . . . . . . . . . . . . . . . . . . . . Domain Creation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Domain and Mapping Agents . . . . . . . . . . . . . . . . Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Associating Management Modules With Domains . . . . . . . . . . . . . . Adding Sample Management Module to Newly Created Domains Changing the Domain Mapping of an Agent . . . . . . . . . . . . . . . . . . Deleting a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Merging Two Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving a Domain From One Introscope Installation to Another . . . . . Moving a Domain Between Installations To Clone the Domains . Moving a Domain Between Non-cloned Installations . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. 76 . 77 . 77 . 77 . 77 . 78 . 78 . 78 . 79 . 79 . 79 . 80 . 80 . 80 . 80
Configuring User Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Local User Authentication Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Configuring Local Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Configuring Enterprise Manager to Use Local Authentication . . . . . . . . . . . 82 Configuring Location or Name of Local Authentication File . . . . . . . . . . . . . 82 Defining a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 User Configuration Modifiers and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 82 Defining a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Generating Encoded Passwords (Optional) . . . . . . . . . . . . . . . . . . . . . . . . 83 Default User Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Configuring Enterprise Manager to Use LDAP Authentication . . . . . . . . . . . 85 Configuring LDAP Authentication Extension . . . . . . . . . . . . . . . . . . . . . . . 85 LDAP Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Defining User Permissions . . . . . . . . . . . . . . . . . . Permissions Rules . . . . . . . . . . . . . . . . . . Domain Permissions . . . . . . . . . . . . . . . . . . . . Domain Access Rules . . . . . . . . . . . . . . . Domain Permissions Defined . . . . . . . . . . Defining Domain Permissions . . . . . . . . . . Domain Permissions and the Explorer Tree Server Permissions . . . . . . . . . . . . . . . . . . . . . Server Permissions Rules . . . . . . . . . . . . Server Permissions Defined . . . . . . . . . . . Defining Server Permissions . . . . . . . . . . . Agent Failover and Domain/User Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 . . . . . . . . . . . . . . . . . . . . 88 . . . . . . . . . . . . . . . . . . . . 88 . . . . . . . . . . . . . . . . . . . . 88 . . . . . . . . . . . . . . . . . . . . 89 . . . . . . . . . . . . . . . . . . . . 90 . . . . . . . . . . . . . . . . . . . . 91 . . . . . . . . . . . . . . . . . . . . 91 . . . . . . . . . . . . . . . . . . . . 91 . . . . . . . . . . . . . . . . . . . . 92 . . . . . . . . . . . . . . . . . . . . 92 . . . . . . . . . . . . . . . . . . . . 93
Chapter 6 Configuring Java Applications With Introscope . . . . . . . . . . . . . . . 94 Chapter 7 Configuring WebLogic Server With Introscope . . . . . . . . . . . . . . . 95
Configuring Introscope With WebLogic Overview . . . . . . . . . . . . . . . . . . . . . . . 95 Installing Introscope Agent With WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 7
JVM AutoProbe Using Java 5.0 JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . JVM AutoProbe With WebLogic Using Sun or IBM JVM . . . . . . . . . . . . . . Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . Running AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . JVM AutoProbe With WebLogic Using HP HotSpot JVM . . . . . . . . . . . . . . JVM AutoProbe With WebLogic Using WebLogic JRockit . . . . . . . . . . . . . Application Server AutoProbe With WebLogic . . . . . . . . . . . . . . . . . . . . Application Server AutoProbe With WebLogic 8.1 . . . . . . . . . . . . . Application Server AutoProbe With WebLogic 7.0 . . . . . . . . . . . . . Application Server AutoProbe With WebLogic 6.1 SP3 . . . . . . . . . . Application Server AutoProbe With WebLogic 6.1 . . . . . . . . . . . . . Configuring HTTP Servlet Tracing For Application Server AutoProbe Configuring Basic Agent Settings for WebLogic Agent Profile Location . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
Additional Configuration Options . . . . . . . . . . . . . . Creating a WebLogic Startup Class . . . . . . . . . . . Configuring a Startup Class In WebLogic 8.1 Optional WebLogic Configurations . . . . . . . . . . . .
Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Configuring a Custom Service in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . 116 Configuring a Custom Service in WebSphere 6.0/5.0 . . . . . . . . . . . . . . . . 116 Optional WebSphere Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Page 8
Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . JVM AutoProbe With WebSphere Using IBM JVM . . . . . . . . . . . . . . . . . . Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . Application Server AutoProbe With WebSphere for z/OS . . . . . . . . . . . . Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS Configuring HTTP Servlet Tracing For Application Server AutoProbe
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
Configuring Basic Agent Settings for WebSphere . . . . . . . . . . . . . . . . . . . . . . . 124 Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 New z/OS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Using PMI with Introscope on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Configuring a Custom Service in WebSphere 5.0 . . . . . . . . . . . . . . . . . . . . . . 127 Configuring a Custom Service in WebSphere 5.0 . . . . . . . . . . . . . . . . . . 127 Optional WebSphere Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Further Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Page 9
Configuring Basic Agent Settings . . . . . . . . . . . . Agent Profile Location . . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . . Additional Configuration Options . . . . . . .
Configuring Basic Agent Settings . . . . . . . . . . . . Agent Profile Location . . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . . Additional Configuration Options . . . . . . .
Page 10
Options for Running Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . 166 Switching Back to Your Non-Introscope-enabled Code . . . . . . . . . . . . . . . . . . 167
Other Optional Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Using Custom ProbeBuilder Directives Files (AutoProbe installations only) . . . . . 177 Removing Line Numbers in Bytecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Turning Off Socket Input/Output Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Agent Logging Options . . . . . . . . . . . . . . . . . . . Agent Log Files and Automatic Agent Naming . Agent Logfile Automatic Naming Notes . Running Agent in Verbose Mode . . . . . . . . . . Redirecting Agent Output to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 . . . . . . . . . . . . . . . . . . . 179 . . . . . . . . . . . . . . . . . . . 179 . . . . . . . . . . . . . . . . . . . 179 . . . . . . . . . . . . . . . . . . . 179
Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 Enabling Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Enabling Platform Monitors on Windows Server 2003 . . . . . . . . . . . . . . . 181 Enabling Platform Monitors on AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Disabling Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Platform Configuration Troubleshooting Option . . . . . . . . . . . . . . . . . . . . . . . . 182 JMX Filters For Obtaining Advanced Performance Data . . . . . . . . . . . . . . . . . . 182 WebLogic 9.0 MBean Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Metric Name Conversion and Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Primary Keys Conversion Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Default Conversion Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 JMX Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Configuring JMX Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Step 1: Enabling JMX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 11
Step 2: Defining Primary Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Step 3: Defining JMX Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Viewing JMX Data In Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 WebLogic Diagnostic Framework Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Metric Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Obtaining WLDF Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Advanced WebSphere Performance Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Turning on Performance Monitor Settings in WebSphere . . . . . . . . . . . . . . . . . 189 Turning on Performance Monitor Settings in WebSphere 6.0/5.0.x . . . . . . 189 Turning on Performance Monitor Settings in WebSphere 4.0 (Distributed) . 189 Enabling and Defining PMI Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Viewing WebSphere Agent PMI Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Enterprise Manager Database Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Upgrading Database Schema Tables From Previous Versions . . . . . . . . . . . . . . 194 Configuring a New Enterprise Manager to Database Connection . . . . . . . . . . . . 194 Running Database Creation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Setting Database Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Sample Microsoft Access Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Optional Enterprise Manager Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Running Enterprise Manager Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Configuring Scheduled Export of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Configuring Scheduled Export of Data . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Adding or Moving Management Modules Between Enterprise Managers . . . . . . . 198 Defining Explicit Table Qualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Workstation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Workstation Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Running Workstation in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Redirecting Workstation Output to a File . . . . . . . . . . . . . . . . . . . . . . . . 200 Connecting Workstation to Enterprise Manager Behind Firewall . . . . . . . . . . . . 200 Optional ProbeBuilder Configurations . . . . . . . . Integrating ProbeBuilder into the Build Process . ProbeBuilder Log . . . . . . . . . . . . . . . . . . . . . . AutoProbe ProbeBuilder Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 . . . . . . . . . . . . . . . . . . 200 . . . . . . . . . . . . . . . . . . 201 . . . . . . . . . . . . . . . . . . 201
Database Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 12
Querying Introscope Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Creating Reports from Introscope Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Introscope Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Default ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Full and Typical ProbeBuilder Directives Sets . . . . . . . . . . . . . . . . . . . . . . . . . 215 Modifying Default ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Default Tracer Groups and Toggles Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Turning on Toggles To Gather Additional Metric Information . . . . . . . . . . 217 Turning Tracer Groups On or Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Turning a Tracer Group On or Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Turning On InstrumentPoint Directives . . . . . . . . . . . . . . . . . . . . . . . . . 218 Adding Classes to a Tracer Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 EJB Subclass Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Creating Custom Tracers . . . . . . . . . . . . . . . . . Custom Tracers and Keywords . . . . . . . . . . Tracer Syntax . . . . . . . . . . . . . . . . . . Custom Method Tracer Examples . . . . . . . . Example Average Tracer . . . . . . . . . . Example Rate Tracer . . . . . . . . . . . . . Example Per Interval Counter Tracer . . Example Counter Tracer . . . . . . . . . . Example Combined Counter Tracers . . Custom Tracers in Blame Technology . . . . . Creating Advanced Custom Tracers . . . . . . . Advanced Single-Metric Tracers . . . . . . . . Signature Differentiation . . . . . . . . . Keyword-Based Substitution . . . . . . Metric-Name-Based Parameters . . . . Skips . . . . . . . . . . . . . . . . . . . . . . . . . . . Combining Custom Tracers . . . . . . . . . . . Counting Object Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 . . . . . . . . . . . . . . . . . . . 220 . . . . . . . . . . . . . . . . . . . 221 . . . . . . . . . . . . . . . . . . . 223 . . . . . . . . . . . . . . . . . . . 223 . . . . . . . . . . . . . . . . . . . 223 . . . . . . . . . . . . . . . . . . . 223 . . . . . . . . . . . . . . . . . . . 223 . . . . . . . . . . . . . . . . . . . 223 . . . . . . . . . . . . . . . . . . . 224 . . . . . . . . . . . . . . . . . . . 225 . . . . . . . . . . . . . . . . . . . 225 . . . . . . . . . . . . . . . . . . . 225 . . . . . . . . . . . . . . . . . . . 225 . . . . . . . . . . . . . . . . . . . 226 . . . . . . . . . . . . . . . . . . . 227 . . . . . . . . . . . . . . . . . . . 227 . . . . . . . . . . . . . . . . . . . 227 . . . . . . . . . . . . . . . . . . . . . . 227 . . . . . . . . . . . . . . . . . . 228 . . . . . . . . . . . . . . . . . . 228 . . . . . . . . . . . . . . . . . . 230
Directive Keywords . . . . . . . . . . . . . . . . . . . . . . ProbeBuilder Skip Keywords . . . . . . . . . . . . . ProbeBuilder Action Keywords . . . . . . . . . . . Threshold ProbeBuilder Action Keywords
Updating Introscope With Modified or New ProbeBuilder Directives Files . . . . 231 Adding New Custom ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . 232 Using AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Using ProbeBuilder Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Applying Changes To ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . 232 Using AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 13
Introscope Workstation Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 IntroscopeWorkstation.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Introscope Workstation.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Introscope WebView Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 IntroscopeWebView.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Introscope WebView.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Database Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 CustomDBRecordTypes.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Extensions Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 LocalAuthenticationExtension.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 LDAPAuthenticationExtension.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Page 14
Preface
Introscope is a system management application created to help you manage Java Application performance. Unlike development tools, Introscope is designed to scale with minimal performance impact. This allows you to monitor and manage your application performance in live production environments.
Organization of the Introscope 6.0.1 Installation Guide This guide includes information on: Viewing data displayed in the Explorer and Console Creating and editing Introscope Elements, including Alerts, Persistent Collections, and Metric Groupings Creating and editing Introscope Dashboards
Page 16
Organization of the Introscope 6.0.1 Installation Guide Chapter 12, Configuring SAP NetWeaver With Introscope, describes how to install and configure the Introscope Agent and Introscope-enable your Java application with SAP NetWeaver Application Server. Chapter 13, Configuring Other Application Servers or Applications With Introscope, describes how to install and configure the Introscope Agent with Application Servers not integrated with AutoProbe. Chapter 14, Configuring the Java Applications Manually With ProbeBuilder describes how to install and configure the Introscope Agent and manually Introscope-enable your Java application. Chapter 15, Optional Introscope Configurations, describes optional configurations for Introscope components. Chapter 16, Database Configuration and Reporting, describes the structure of Introscope database tables. Chapter 17, ProbeBuilder Directives, describes how to create custom Directives so that Introscope reports desired Metrics. Appendix A, Introscope Properties Files, shows various properties files and the specific variables that you may need or want to customize. Appendix B, Licenses, contains third-party licenses.
Courier font
bold font <italic blue text purple italicized text directory
font>
Variable names that will be replaced with actual items. For example: Replace <filename> with the name of an actual file. A hyperlinked cross reference within an Introscope Guide (in the PDF file, when clicked, it jumps to the link destination) Cross reference between Introscope Guides (not hyperlinked) By default, Introscope is installed into a directory named Introscope. This book refers to the full pathname of this directory as <Introscope home>. Use the full path of your installation directory in place of the directory <Introscope home> in procedures in this book. A diamond indicates a procedure consisting of a single step. Unless stated otherwise, examples in this book use conventions for UNIX machines. Separates directory and file names in UNIX path names as,
Introscope
In UNIX / (slash)
/Introscope6.0.1/examples/ IntroscopeAgent.profile.
Page 17
Convention
# (pound sign)
Is Used For
UNIX prompt with
# cd /usr
Do not type the # (pound sign). : (colon) In UNIX path names in path variables, separates file or directory names from each other, as:
/<your-applicationpath>.isc/classes:/<yourapplicationpath>.isc/lib/app.jar: /Introscope6.0.1/lib/Agent.jar
_ (underscore) In Windows Separates words in UNIX launcher application names. Unless stated otherwise, examples in this book use conventions for UNIX machines. If you are on a Windows machine, substitute the Windows conventions below for the shown UNIX conventions. Separates directory and file names in Windows path names, as
\ (backslash) ; (semicolon)
C:\Introscope\bin\pdh.dll
In Windows path names in path variables, separates file or directory names from each other, as:
Page 18
1 Introscope Overview
Introscope version 6.0.1 is a system management application created to help you manage Java Application performance. Unlike development tools, Introscope is designed to scale with minimal performance impact. This allows you to monitor and manage your application performance in live production environments. Introscope provides real-time Java Application performance management without requiring access to or modification of the applications source code. Rich and customizable data views are integral to the product. Alerts can be user-defined and set up to be triggered by application activity. Introscope also includes historical performance analysis and trend analysis. All of these features can be used on every Java component in the system even purchased software for which there is no source code, including the Java Web application server. Introscopes Blame Technology enables you to study interactions between components to identify which components are causing the application to be slow or busy. Introscope is tightly and easily integrated with selected Web application servers and JVMs: WebLogic Server 6.1 or higher WebSphere Application Server 4.0 or higher Sun ONE Application Server 7.0 or higher Oracle Application Server 10g 10.0.3 Hewlett-Packard HotSpot Java Virtual Machine (HP JVM) 1.2.2.08 or higher WebLogic JRockit 7.0 or higher Fujitsu Interstage 6.0 (Japanese version) You can quickly start managing these applications by placing a few files in the applications directory and relaunching the application server. Application server vendors, application vendors, and others can provide extensions and customizations to Introscope to provide additional value to the product.
Page 19
Figure 1. How Introscope prepares bytecode Introscope, through the ProbeBuilder, adds Introscope Probes to a Java Application. Using AutoProbe automates this process, with the ProbeBuilder dynamically adding Probes to the Java Application when the application starts up. The Probes measure specific pieces of information about an application without changing the applications business logic. An Introscope Agent is installed on the same machine as the Introscope-enabled application. Once the Probes have been installed in the bytecode, the Java Application is referred to as an Introscope-enabled application. Once the Java Application with Probes is running, it is called a managed application. Figure 2 is a simple conceptual view of Introscope components and how they cooperate and communicate with each other.
Figure 2. Introscope conceptual overview As a managed application runs, Probes relay collected data to the Agent. The Agent then collects and summarizes the data and sends it to the Enterprise Manager.
Page 20
Introscope Components and Terms Data collected by the Enterprise Manager can be accessed through one or more Workstations. You can use the Workstation to view performance data, and configure the Enterprise Manager to perform such tasks as collecting information for later analysis, and creating Alerts. The Enterprise Manager can also be configured to send data to an external data store, such as a database or flat file. The following table summarizes key interactions among the components in an Introscope environment:
ProbeBuilder Probes Agent Enterprise Manager Workstation Database Refers to ProbeBuilder Directives files to define data to be collected Adds Probes to Java Application Collects data defined by ProbeBuilder Directives files Sends collected data to Agent Sends collected data to the Enterprise Manager Receives collected data from Agent Connects to the Enterprise Manager to view data Configures the Enterprise Manager Receives data from the Enterprise Manager
Agent
An Agent runs as part of the managed application on the Java Application machine. It collects and summarizes the Probe-reported data and sends it to the Enterprise Manager.
Introscope-enabled Code
Introscope-enabled code is code that has had Introscope Probes added to it.
Probes
Probes measure specific pieces of information about an application without changing the applications business logic. Probes track real-time performance information, making the information available for review and action.
Page 21
AutoProbe
AutoProbe makes administration of a managed application with Introscope easy. With AutoProbe, the ProbeBuilder inserts probes dynamically into the application code as it is loaded. There are two AutoProbe configuration options: JVM AutoProbe: dynamically Introscope-enables all classes loaded by the JVM Application Server AutoProbe: dynamically Introscope-enables all applications loaded by the application server AutoProbe integration is available on the following platforms: BEA WebLogic Server v6.1 or higher IBM WebSphere Application Server v4.0 or higher Sun ONE Application Server 7.0 or higher Oracle Application Server 10g 10.0.3 Hewlett-Packard HotSpot JVM v1.2.2.08 or higher WebLogic JRockit 7.0 and higher Fujitsu Interstage 6.0 (Japanese version)
Enterprise Manager
The following terms relate to the Introscope Enterprise Manager.
Enterprise Manager
The Enterprise Manager is the central process of an Introscope system. The Enterprise Manager receives performance data from managed applications via the Agent, runs requested calculations, makes performance data available to Workstation users, and sends performance data to a database for later analysis.
Page 22
Metric
A Metric is a measurement of a specific application activity. By default, Probes report a standard set of Metrics for a managed Java Application. Examples of Metrics collected by default are: CORBA method timers Remote Method Invocation (RMI) method timers Thread counters Network bandwidth JDBC update and query timers Servlet timers Java Server Pages (JSP) timers System logs File system input and output bandwidth meters Available and used memory EJB (Enterprise JavaBean) timers
Resource
All Metric information reporting through a single Agent is organized under Resources. Resources can also contain sub-resources that further group Metrics.
Metric Grouping
A Metric Grouping is a filter using a regular expression that selects a set of Metrics from the group of all Metrics. Metric Groupings are the building blocks for any Elements created, such as Views, Alerts, or Persistent Collections.
Blame Technology
Introscopes Blame Technology works in a managed Java Application to enable you to identify component interactions and component resource usage.
Domains
A Domain is a partition of Agents and monitoring logic.
SuperDomain
The superset of all Domains. Viewing the contents of the SuperDomain in the Workstation allows users to conveniently view all Agents, Management Modules, and Dashboards in a deployment in one location.
Workstation
The following terms relate to the Introscope Workstation.
Page 23
Workstation
The Workstation is the graphical user interface for viewing performance data. You use the Workstation to create custom views of performance data which you can monitor. The Workstation consists of three main windows, the Console, Introscope Explorer and the Dashboard Editor.
Console
The Console displays performance data in a set of customizable views called Dashboards, such as the one shown below.
Page 24
Introscope Explorer
The Explorer displays, in hierarchical tree structure, all data collected by Agents. The Explorer also provides tools for creating and editing Management Module Elements, such as Metric Groupings, Alerts and Calculators that filter performance data.
Page 25
Dashboard Editor
The Dashboard Editor consolidates all Dashboard editing tasks in one location, and adds even more functionality, such as drawing program functions.
Management Module
Management Modules organize Elements in the Workstation so they can be conveniently found and manipulated. Management Modules can be used to transport sets of Elements between Enterprise Managers.
Element
Elements are objects that contain and organize data with monitoring logic. Elements include: Actions Alerts Calculators Dashboards Persistent Collections Metric Groupings Report Templates SNMP Collections Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 26
You might have both UNIX and Windows machines in your Introscope/Java Application configuration. For example, the machine that runs your Java Application might be a UNIX machine, whereas the machine that runs the Workstation might be a Windows machine. Therefore, you might be installing the UNIX version of Introscope on UNIX machines and the Windows version on Windows machines.
Page 27
Preparing To Install Introscope Automatic configuration of the following settings is possible during installation: Enterprise Manager settings: Workstation and Agent port numbers location and data aging information for Transaction Event Database storage location for data from SmartStorTM, the Introscope data storage mechanism JVM settings (optional) configuration of the Enterprise Manager as a Windows Service (Windows only) Workstation settings: Host and port numbers JVM settings default user login WebView settings Enterprise Manager host and port numbers HTTP port configuration of the WebView as a Windows Service (Windows only) JVM settings (optional) ProbeBuilder settings: JVM settings (optional)
Install Notes
The installer performs a clean Introscope installation. It will not upgrade a previous version of Introscope, or install Introscope Agents, PowerPacks or other Introscope add-on products. The installer can perform either a complete Introscope core component install, or a per component install (except Agent). The installer only performs basic configuration operations, such as specifying Enterprise Manager ports. To configure more detailed and/or optional settings after installation, including configuring a database for use with Introscope, see Optional Introscope Configurations, page 168.
Page 28
Preparing To Install Introscope The Console mode installer presents a series of text prompts that will collect user input, prompt the user to correct any incorrect settings, install Introscope components and summarize installation results. Silent mode The Silent mode installer is invoked from the command line and gets input from a specified response file. The installer runs in the background as it installs Introscope components, and doesnt provide output at runtime. To see the installation results, the user must check the install log.
Console
No Yes
Silent Mode
Yes Yes
Default Mode
GUI GUI
No No Yes
Note: For installers without a default mode (z/OS and OS/400), you must specify an
install mode on the command line.
Supported Platforms
As described earlier, the Introscope system is composed of the Enterprise Manager, Workstation and Agent(s). WebView is also included in the installer package. Each of these components has a specific list of supported platforms. General guidelines for platform support of each part of Introscope are as follows: TABLE 2. Supported Platforms By Component Introscope Component Supported Platforms
Page 29
Enterprise Manager
Most major operating systems including: Windows 2000 Windows Server 2003 Solaris AIX HP-UX z/OS Microsoft Windows 2000 Windows Server 2003 Windows XP
Workstation
Any operating system and hardware combination supported by J2EE application server vendor Windows and Internet Explorer 6 or higher
Note: For a complete list of environments supported by Introscope, please refer to the
Wily Compatibility Guide, available from your Wily representative.
Space Requirements
The following table details space requirements for the Introscope installation. TABLE 3. Installation Space Requirements What
Hard Drive Space
How Much
100 MB (complete installation package) 80 MB for Workstation alone 80 MB for Enterprise Manager alone 10 MB for Agent install 80 for WebView alone
Details
Space required for package including JVM
200 MB
The amount of space required differs depending on the platform and installer type used. SmartStorTM records all application performance data (Introscope Metrics) at all times. SmartStor is enabled by default during Introscope installation.
Page 30
Memory Requirements
Table 4 shows the minimum memory each component requires. TABLE 4. Component Requirements Component
Workstation Enterprise Manager ProbeBuilder Wizard WebView AutoProbe Command Line ProbeBuilder Managed applications with Version 6.0.1 Agent
Note: Please note that these memory requirements are for Introscope components only.
Additional memory will be required for the operating system and any other programs running.
Please see the Wily Compatibility Guide (available from your Wily representative) for the specific list of support configurations.
Bundled JVMs
For your convenience, Java Virtual Machine comes bundled with the Introscope install on the following platforms: Sun Solaris, Windows, AIX, HP-UX and Red Hat Linux. Table 5 shows which JDK versions are bundled with the installer: TABLE 5. Bundled JVM Versions Operating System
Solaris
JDK
Sun JDK 1.4.2_03
Page 31
Sun JDK 1.4.2_03 IBM JDK 1.4.1 HP JVM 1.4.1.03 Sun JDK 1.4.1 none none
Note: If you plan to use Agent Failover, you will need to collect host and port information
for each backup Enterprise Manager as well. Collect or decide on the following information before installing Introscope:
Page 32
Reviewing Installation and Configuration Process TABLE 6. Enterprise Manager Information To Collect Enterprise Manager Information Host and Port Information Host Name or IP address EM1_________________ EM2_________________ EM3_________________ EM4_________________ Agent Port EM1_______ EM2________ EM3_______ EM4________ Workstation Port EM1________ EM2_______ EM3_______ EM4_______ Secure Workstation Port EM1__________ EM2__________ EM3__________ EM4__________
Page 33
Reviewing Installation and Configuration Process 5. 6. 7. 8. Configure Domains and user permissions. Configure authentication, either local or external. Configure any optional functionality for Introscope components, such as Agent Failover, or JMX and PMI information. Start up everything and see the Agent reporting.
Note: If you are upgrading your Introscope deployment, consult the Introscope 6.0.1
Upgrade Guide to be sure that the necessary files are backed up before performing a clean install.
Page 34
Installer Files
Obtain the appropriate aggregate installer file from your Wily representative. You now have a choice of two installer files: install package that contains Introscope components (Enterprise Manager, Workstation, and WebView) plus the Introscope Agent install package of Introscope components without the Introscope Agent The following table details the names of the installer files.
Operating System
Windows Solaris HP-UX AIX Red Hat Linux OS/400 z/OS Other
Installer Filename
introscope6.0.1windowsinstall.SAPExpertCenter.zip
Page 35
If using Windows or OS/400, unzip the installer file. If using any other platform, extract the installer files using the following command (substituting the appropriate filename for the one in this example):
Installer Files
The following table details the names of the installer files inside the aggregate install package.
Operating System
Windows Solaris HP AIX Red Hat Linux OS/400 z/OS Other
Installer Filename
introscope6.0.1windows.exe introscope6.0.1solaris.bin introscope6.0.1hpux.bin introscope6.0.1aix.bin introscope6.0.1linux.bin introscope6.0.1os400.jar introscope6.0.1zOS.jar introscope6.0.1other.jar
Installer Filename
introscope6.0.1windows.SAPExpertCenter.exe introscope6.0.1solaris.SAPExpertCenter.bin introscope6.0.1hpux.SAPExpertCenter.bin introscope6.0.1aix.SAPExpertCenter.bin introscope6.0.1linux.SAPExpertCenter.bin
Page 36
c:> .\<installername>.exe
For .bin files (with bundled JVM), invoke it from the command line. For example:
[root@qaserver:/] ./introscope6.0.1solaris.bin
For .jar files (no bundled JVM), invoke it from the command line, and specify the appropriate JVM. For example:
Page 37
In the Choose Install Set screen, choose which Introscope components to install. You have the following options: Complete Install: installs all Introscope components Minimal Install: installs only the Enterprise Manager and Workstation Custom, and check the boxes for which components to install.
Page 38
Installing Introscope In GUI Mode 3. Click Next. The Choose Install Folder screen appears.
Click Next to accept the default location, or click Browse to specify a different location. 4. Click Next. If you are using an installer on a platform which includes a bundled JVM, the Configure JVM Settings screen appears.
Note: If you are using an installer which does not include a JVM, you will not see this
choice screen. You will be automatically prompted in later screens to specify JVM settings per component.
Page 39
Installing Introscope In GUI Mode Select Yes from the drop-down list box to configure JVM settings for installed Introscope components during this installation. Later in the installation, a JVM Settings screen will appear for each Introscope component you will be installing. Select No to accept default JVM settings for Introscope components, or if you plan to configure them manually after installation. 5. Click Next.
Note: Users performing SAP installations will not see this screen.
Click the Browse button to browse to the location of the Wily license file. During installation, the Wily license file will be copied into the <Introscope home>/ license folder.
Note: If you dont have a Wily license, you can install it later. Click Next, then Skip
License. 6. Click Next.
Page 40
Installing Introscope In GUI Mode The Enterprise Manager Port Settings screen appears.
7.
Click Next to accept the default port values OR type other values in the appropriate fields, and click Next.
8.
Click Next to accept the default location, or click Browse to specify a different location.
Page 41
Note: Be sure to place the Transaction Event Database directory on drive with at
least 2GB of disk space available for data storage. The amount of space required will vary depending on factors such as number of Transactions stored and how long the data is kept.
9.
Click Next to accept the default aging value, or enter another value (in days) and then click Next. 10. The Enterprise Manager Data Storage Configuration screen appears.
Leave the default Yes setting in the drop-down list box to use the SmartStor feature, which constantly records all Introscope data without the need for a
Page 42
Installing Introscope In GUI Mode database. See SmartStorTM Data Storage, page 60 for more information on configuring frequency and aging of data.
Note: Using SmartStor does not interfere with data sent to Persistent Collections.
Select No to disable SmartStor data storage. 11. Click Next. The Enterprise Manager Data Storage Directory screen appears.
Click Next to accept the default location, or click Browse to specify a different location.
Note: Be sure to place the SmartStor directory on drive with at least 8 GB of disk
space for SmartStor data storage. Since the amount of space required will vary depending on factors such as number of Metrics and storage frequency, see SmartStorTM Data Storage, page 60, for information on estimating disk size requirements.
Page 43
Installing Introscope In GUI Mode 12. (OPTIONAL) If you selected yes in the earlier Configure JVM Settings screen, the Enterprise Manager Advanced JVM Settings screen appears.
Specify the Java executable to use to run Introscope, and any desired command-line JVM arguments. 13. Click Next.
Click No to continue without configuring Enterprise Manager as a Windows Service. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 44
Installing Introscope In GUI Mode Select Yes to configure the Enterprise Manager as a Windows Service. Then: enter a unique service name for this instance of Enterprise Manager as Windows Service either accept the default display name, or enter a unique display name.
Note: If you have configured this Enterprise Manager service to connect to a database
that doesnt exist yet (or hasnt been updated to the new schema), you will need to restart this Service after the database has been created/properly configured.
Workstation Settings
The Workstation Settings screen appears.
Workstation Default User: the username entered here will be shown by default in the Workstation Login screen.
Note: An Admin user exists by default in the users.xml file. If you enter any other username in this screen, that user must exist in the users.xml (if
using local authentication) or exist in the external authentication system in order to log in successfully. See Chapter 5, Configuring Introscope Security and Permissions for information on adding new users.
Page 45
Installing Introscope In GUI Mode Workstation Default Host: the host entered here will be shown by default in the Workstation Login screen. Workstation Default Port: the port entered here will be shown by default in the Workstation Login screen. 16. Click Next. If you selected yes in the earlier Configure JVM Settings screen, the Workstation Advanced JVM Settings screen appears.
Specify the Java executable to use to run the Workstation, and any desired JVM command-line arguments. 17. Click Next. The Workstation Pre-Installation Summary screen appears. Review the summary of Workstation installation configurations. Go back and make corrections if necessary. 18. Click Next.
Page 46
WebView Settings
The WebView Settings screen appears.
19. Click Next to accept the default HTTP host, and Enterprise Manager port and host values OR type other values in the appropriate fields, and click Next. The WebView As Windows Service screen appears.
Click No to continue without configuring WebView as a Windows Service. Select Yes to configure the WebView as a Windows Service. Then: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 47
Installing Introscope In GUI Mode enter a unique service name for this instance of WebView as Windows Service either accept the default display name, or enter a unique display name. 20. Click Next. If you selected yes in the earlier Configure JVM Settings screen, the WebView Advanced JVM Settings screen appears.
Specify the Java executable to use to run WebView, and any desired JVM commandline arguments. 21. Click Next. The WebView Pre-Installation Summary screen appears. Review the summary of WebView installation configurations. Go back and make corrections if necessary.
Page 48
ProbeBuilder Settings
If you selected yes in the earlier Configure JVM Settings screen, the ProbeBuilder Advanced JVM Settings screen appears.
Specify the Java executable to use to run the ProbeBuilder, and any desired JVM command-line arguments. 22. Click Next. The ProbeBuilder Pre-Installation Summary screen appears. Review the summary of ProbeBuilder installation configurations. Go back and make corrections if necessary. 23. Click Install. Introscope will install and notify you when installation is complete.
Note: If errors occurred during the installation, you will be directed to view the
appropriate component logs. For help, contact Wily Support.
Page 49
Installing Introscope In Console Mode There will be some minor differences, mostly that the installer in Console mode can only gather one variable per "window, where the GUI mode can collect many variables from a single window. See the GUI Installation Sequence, page 37, to review the information requested by the installer. During the installation process in Console mode, you can type Back to return to a previous window.
echo $JAVA_HOME
2. If it exists, continue to step 3. If no such variable exists: Open the runinstaller.sh script in a text editor. Find the line that sets the Java home. Uncomment this line, and modify the path to specify your own Java home. Save your changes, then launch the script. 3. Launch the script using:
runinstaller.sh introscope6.0.1zOS.jar
For example:
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 50
[root:/] /usr/java/bin/java -classpath introscope6.0.1os400.jar install i console Note: You must use a flag to force console mode, since Swing mode is default for
.jar files.
<Introscope home>/examples/installer/SampleResponseFile.txt
Page 51
Installing Introscope In Silent Mode The response file can have any name, and can be located in any directory, as long as you specify the name and location in the command line when invoking the silent mode for the installer. The properties in the response file are very similar to those in the usual properties files. However, keep in mind the following issues when entering values for the properties in the response file: On Windows, backslashes need to be escaped. On Windows, any directory supplied needs to be suffixed by a slash. For example:
/tmp/Wily1/Introscopedirectory/
To specify any JVM settings, you will need to first uncomment the properties.
echo $JAVA_HOME
2. If it exists, continue to step 3. If no such variable exists: open the runinstaller.sh script in a text editor. Find the line that sets the Java home. Uncomment this line, and modify the path to specify your own Java home. Save your changes, then launch the script. 3. Launch the script using:
Page 52
[root@qaserver:/] /usr/java/bin/java classpath introscope6.0.1os400.jar install f /tmp/myResponseFile.txt Note: If the response file specified doesnt exist or the path is invalid, the installer will
attempt to run in GUI mode. However, if GUI mode isnt supported on the platform, the installer will fail.
Page 53
Uninstalling Introscope
Uninstalling Introscope
The Introscope base installer comes with an uninstaller program, which will remove all installed components. The following things will happen when you run the uninstaller: all files originally installed with Introscope will be deleted if you created a sample database during install, the uninstaller will ask to delete it if any other database is present, it will not be removed if there were files installed or created after original Introscope install (such as Enterprise Manager logs), the uninstaller will instruct you to hand-delete them
Uninstall Modes
The uninstaller will run in whichever mode the installer originally ran in. For example, if you installed in GUI mode, the uninstaller will also run in GUI mode. However, for installers with bundled JVMs, you can force a different uninstall mode (for example, if you originally ran the install in silent mode, and now want to control what is uninstalled in the GUI mode). This section displays the uninstall process in GUI mode. Just like in the installer, the Console mode will ask for the same information as the GUI mode. The silent mode uninstaller will just uninstall everything in the background.
Running Uninstaller
To uninstall Introscope components: 1. Locate the Introscope uninstaller for your platform: Windows: <Introscope home>/Uninstaller Data/Uninstall Introscope.exe.
Page 54
Uninstall_Introscope
z/OS, OS/400 and other: <Introscope home>/Uninstaller Data/
Uninstall/uninstaller.jar
2. Run the uninstaller, using the appropriate command for your platform: For .exe or .bin files: run the .exe, or ./<bin file> For other: run the following command:
3.
If you opted to install the Enterprise Manager or WebView as a Windows Service during the installation, a screen similar to this appears:
Page 55
Uninstalling Introscope Select Yes, Deregister Service to remove the Enterprise Manager or WebView instance you configured as a Windows Service during installation. This command will stop the service, and deregister it. The Windows Service will be deleted as part of the uninstall process.
Note: Introscope will tell you to manually deregister any remaining Enterprise
Managers or WebView instances configured as Windows Services, just in case you changed the name of the Windows Service configured during installation, or configured a service yourself, outside of the installation process.
5. 6.
Manually delete any extra files that exist in the Introscope directory. Repeat the uninstall process on other machines as necessary.
Page 56
Page 57
Installing License
Installing License
If you chose not to install a license during the installation process, use the following instructions. 1. 2. To obtain a license, contact your Wily Technology sales representative. Place the license file in the <Introscope home>/license directory on the machine that will run the Enterprise Manager.
Note: Make sure the Enterprise Manager has both read access and write access to the <Introscope home>/config directory, so that configuration changes will be
properly saved.
UNIX
OS/400
The Enterprise Manager can be started in OS/400 by: using a start script (described in the following section) running the Enterprise Manager as a Java Program, described in Running the Enterprise Manager as a Java Program, page 59.
Page 58
Starting Enterprise Manager will assume that the Introscope home is the directory where you launched the script.
z/OS
To start the Enterprise Manager, use the runem.sh file. For instructions on running the Enterprise Manager on z/OS, please see Configuring Enterprise Manager To Run As a z/ OS Batch Job, page 67.
iscopeshutdown
If you are a user with shutdown privileges for the Enterprise Manager, you can also shut down the Enterprise Manager from within the Workstation in an Explorer window, by selecting Manager > Shut Down Enterprise Manager.
When the Enterprise Manager is shut down: Agents will stop collecting data SmartStor will not save data data will stop being sent to a database (if one is configured) you will be logged out of the Workstation all users connected to the Enterprise Manager will be disconnected
Page 59
introscopeEnterpriseManager.properties
Under Port Settings, find the property,
introscope.enterprisemanager.port.agentlistener
Set it to the port that will listen for incoming Agent connections. For example:
introscope.enterprisemanager.port.agentlistener=5001
4. Save your changes.
Be sure that the port defined in this property matches the one defined in the Agent profile.
Configuring SmartStor
SmartStor is enabled by default during Introscope installation (unless you disable it).
Enabling SmartStor
SmartStorTM is enabled by default during installation (unless you chose to turn it off during installation). To enable SmartStorTM: 1. 2. Open the file, IntroscopeEnterpriseManager.properties. For the property, introscope.enterprisemanager.smartstor.enable, enter a value of true.
Page 60
SmartStorTM Data Storage 3. To use the default frequency and aging settings, save changes and restart the Enterprise Manager. Otherwise, use the instructions in the following sections to customize frequency and aging settings.
<Introscope home>/examples/SmartStorSizing.xls
You can experiment with different values for number of Metrics, and different periods and aging ranges for your data tiers. The resulting GB size usage will appear in the table below. SmartStors performance is sensitive to the Operating System, JVM, and file system choices. The following screenshot shows the SmartStor Sizing Tool formula window.
After you have determined the appropriate data tier frequency and aging periods, you can enter your specifications into the appropriate SmartStor properties.
Transaction Event Database Storage the storage frequency must be a multiple of 15 seconds the frequency must not be greater than 1800 seconds (30 minutes) each tier's frequency must be an even multiple of the previous tier's frequency (this multiple can be one; each tier can have the same frequency) the age must not be zero all three tiers must be defined, and you cannot define more than three tiers. To configure the SmartStor data tier values: 1. 2. 3. 4. 5. Open the file, IntroscopeEnterpriseManager.properties. For the introscope.enterprisemanager.smartstor.tier1.frequency property, enter the desired value. For the introscope.enterprisemanager.smartstor.tier1.age property, enter the desired value. Repeat for the remaining two data tier property pairs. Restart the Enterprise Manager. its best to adjust data to your new configuration, but it may lose a days worth of data.
Note: If you change your data tiers and reboot the Enterprise Manager, SmartStor will do
Property
introscope.enterprisemanager.transactioneve nts.storage.dir
Function
Specifies where to store transaction event data.
Notes
Select a location that has at least 2 GB of available space.
Page 62
introscope.enterprisemanagter.transactionev ents.storage.max.data.age
Increasing the data aging period has overhead and storage implications.
3.
Save changes.
8/11/05 12:59:48 PM PDT [ERROR] [Manager.Agent] The agent SuperDomain|AcmeWest|BalancedFirehoseAgent|ACMETH22Agent has exceeded the metric count limit of 50000 and will be shut off to prevent overload
The Agent will appear grayed out in the Explorer tree, but this is not a persistent state. When the Agent is rebooted (and hopefully, reconfigured to run properly), the Agent will be recognized by the Enterprise Manager and be allowed to run as before.
Running Enterprise Manager in nohup Mode on UNIX 1. 2. Open the file, IntroscopeEnterpriseManager.properties. In the property, log4j.logger.Manager, replace INFO with the following:
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
3. Save changes.
log4j.logger.Manager=VERBOSE#com.wily.util.feedback.Log4JSeverit yLevel,logfile
3. 4. If desired, change the name and/or location of the Enterprise Manager logfile in the property, log4j.appender.logfile.File. Save changes.
lax.stdin.redirect=
2. In the IntroscopeEnterpriseManager.properties file, ensure that the property introscope.enterprisemanager.disableInteractiveMode is set to true, as in:
introscope.enterprisemanager.disableInteractiveMode=true
3. Start the Enterprise Manager with the following command:
nohup Introscope_Enterprise_Manager&
It is critical that both of the Introscope Enterprise Manager properties are set exactly as described above. If you attempt to run the Enterprise Manager in nohup mode without changing these properties as described, or set them incorrectly, the Enterprise Manager may not start, or CPU utilization may become excessive.
System Requirements
The Enterprise Manager can be run as a Windows Service on the following platforms: Windows 2000 Professional Windows 2000 Server Windows Advanced Server Windows Datacenter Server Windows Server 2003 Standard Edition Windows Server 2003 Enterprise Edition Windows Server 2003 Datacenter Edition Windows XP Professional
lax.stdin.redirect
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 65
Configuring Enterprise Manager To Run As A Windows Service 3. 4. Save changes to the file. In the file, IntroscopeEnterpriseManager.properties, ensure the following property is set to true, as shown in the example below:
introscope.enterprisemanager.disableInteractiveMode=true
5. 6. Save changes to the file. The Enterprise Manager Service must have a unique name. If this is the only Service installed on this machine, you can use the default names provided. If you will have multiple services on the same machine, specify the unique names in the file, <Introscope home>/EMService.conf. Change the following properties to customize the naming of the Enterprise Manager in the Windows Services GUI: wrapper.ntservice.name=<unique EM name> wrapper.ntservice.displayname=<EM display name> 7. 8. Save changes to the <Introscope home>/EMService.conf file. Run the script, <Introscope Home>/RegisterEMService.bat to register the Enterprise Manager instance as a service.
The Windows Services console will show that the Enterprise Manager is configured as a Windows Service. Repeat these steps for each Enterprise Manager installation to register multiple Services.
Note: If either the Enterprise Manager Service or the Windows Services GUI are active,
Page 66
Overview
Prerequisites
z/OS base infrastructure for Java
The infrastructure required to run the Introscope Enterprise Manager as an MVS batch job or started task is straightforward and easily realized. The MVS utility program, BPXBATCH, enables users to invoke UNIX System Services to run shell commands, shell scripts and executable files in MVS batch. Specifically, the Introscope Enterprise Manager can be started using the BPXBATCH utility.
Software Prerequisites
The specific software prerequisites to run Java (and therefore the Introscope Enterprise Manager) on the z/OS can be found in the Java for z/OS Program Directory GI10-0614. The minimum software requirements are: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 67
Configuring Enterprise Manager To Run As a z/OS Batch Job The Introscope Enterprise Manager requires Java 1.4. This is supported on z/OS 1.4 and can run on some earlier versions if the appropriate OS patches are installed. Check your OS documentation to make sure it supports Java 1.4. UNIX System Services must be enabled Language Environment 1.5 or higher Java for z/OS
Virtual Memory
If the OMVS address space is not large enough, an out of memory condition will occur when an attempt is made to run the Introscope Enterprise Manager. The OMVS ASSIZEMAX(address-space-size) parameter in the RACF profile for the owner of the Introscope Enterprise Manager job or started task must be large enough to execute the Introscope Enterprise Manager. The maximum value for this parameter is 2G.
DB2
1. To access JDBC and SQLJ from UNIX Systems Services, you must set the following environment variables: STEPLIB must include the SDSNEXIT and SDSNLOAD data sets
Page 68
Configuring Enterprise Manager To Run As a z/OS Batch Job LIBPATH and LD_LIBRARY_PATH must include the DLL libraries for the JDBC and SQLJ drivers 2. In order to run the Introscope Enterprise Manager as a z/OS job, the runem.sh shell script must contain the following statements where DSNXXX denotes the High Level Qualifier of your DB2 libraries:
runem.sh shell script should include the following file: /usr/lpp/dsn710/db2/db2710/classes/db2sqljclasses.zip Note: The character string 710 in dsn710 and db2710 refers to the version and release
of DB2 being used. If another version of DB2 is being used, these directories must be changed.
4.
Specify the DB2 subsystem identifier: SYS_DB2_SUB_SYSTEM_NAME=xxx, where xxx is the subsystem identifier
JDBC
JDBC for z/OS is based on the DB2 Call Level Interface (CLI). You must ensure that the DB2 CLI has been set up as follows: 1. The DB2 CLI application plan (the default name is DSNACLI) must be bound before you can use the DB2 CLI. A sample bind job can be found in DSNXXX.SDSNSAMP(DSNTIJCL) where DSNXXX denotes the high level qualifier of your DB2 installation. The DB2 CLI application plan must be public. Execute the following command from SPUFI or from a batch job:
2.
Page 69
DASD
The Introscope Enterprise Manager DB2 database constitutes the only significant DASD requirement. DASD space for the Introscope Enterprise Manager DB2 database is discussed in section Customizing the tablespaces and the sample CREATE TABLE statements, page 75.
Installation
Overview of Installation Tasks
Before the Introscope Enterprise Manager can run as a z/OS batch job, the following files (extracted from the z/OS installer file) must be copied into the z/OS environment and customized to ensure compatibility with site-specific requirements. IntroscopeEnterpriseManager.properties the Introscope Enterprise Manager properties file, which specifies information pertinent to the operation of the Introscope Enterprise Manager runem.sh the shell script used to launch the Introscope Enterprise Manager process WILYPROC the z/OS PROC used to execute z/OS BPXBATCH program that launches the shell script readme.txt - a description of the runem.sh and WILYPROC files and how to use and customize them
IntroscopeEnterpriseManager.properties file.
Page 70
Configuring Enterprise Manager To Run As a z/OS Batch Job 2. Find the Database Settings heading. Under this heading, you should find the following statements:
Note: You do not have to change the username and password because they will
not be used by DB2 for authorization. 3. 4. Uncomment the property,
introscope.enterprisemanager.db.useBatchInserts=true.
Find the Interactive Mode heading and make sure the value for the following property is set to true.
introscope.enterprisemanager.disableInteractiveMode=true
Note: If you are connecting to a DB2 subsystem other than version 7.1, you must
change all instances of 710 to the appropriate character string for the version being used.
The following is a list of settings in the runem.sh script that must be changed: In the CLASSPATH, /usr/lpp/dsn710/db2/db2710/classes/
db2sqljclasses.zip export STEPLIB=DSN710.SDSNEXIT:DSN710.SDSNLOAD #export LIBPATH=/usr/lpp/dsn710/db2/db2710/lib:$LIBPATH #export LD_LIBRARY_PATH=/usr/lpp/dsn710/db2/db2710/ lib:$LD_LIBRARY_PATH Note: If LIBPATH and LD_LIBRARY_PATH have been commented out, remove the
#.
Copying Introscope Enterprise Manager z/OS files to a z/OS Partitioned Dataset (PDS)
Copy WILYPROC into the PDS
1. Using ISPF, create a partition dataset named userid.JCL.CNTL, (where userid is the userid assigned to WILY) with fixed block (FBA) 80 byte records.
Page 71
Configuring Enterprise Manager To Run As a z/OS Batch Job 2. 3. Copy WILYPROC into the PDS userid.JCL.CNTL, where userid is the userid assigned to Wily and userid.JCL.CNTL is the name of the previously created PDS. Do not try to copy the shell script, runem.sh, or the properties file, IntroscopeEnterpriseManager.properties, into this PDS. These files have lines that are longer than 80 bytes. An attempt to copy them will either fail or lines will be truncated.
//STDOUT //STDERR
DD PATH='/<path>/stdout', DD PATH='/<path>/stderr',
Using ISPF option 3, copy the PROC to xxxx.PROCLIB where xxxx represents an sitedependent high level qualifier. If WILYPROC is not an acceptable name in your installation, rename the PROC accordingly.
Page 72
To run the Introscope Enterprise Manager as a started task, type the following command on the MVS console or on the command line of SDSF:
/start WILYPROC
You must type the member name of the PROC stored in an active PROCLIB. If you were required to change the name of WILYPROC, you must use the new name in the /start command.
To run the Introscope Enterprise Manager as a batch job, submit the following JCL:
//jobname ISCOPE /*
JOB EXEC
You must execute the member name of the PROC stored in an active PROCLIB. If you were required to change the name WILYPROC, you must use the new name on the EXEC statement. The z/OS batch job and the OMVS Shell will end shortly after the Introscope Enterprise Manager processes have started. If you submitted the batch JCL from your ISPF session and your JOB card contains NOTIFY=&SYSUID, your ISPF session will receive notification when your batch jobs ends.
Page 73
$VS,start WILYPROC
2. You must type the member name of the PROC stored in an active PROCLIB. If you were required to change the name of WILYPROC, you must use the new name in the /start command.
You can also run the Introscope Enterprise Manager as a batch job using whatever job scheduling package you use to manage your batch workload.
DB2 Considerations
DB2 for z/OS provides many installation parameters and customization options that are designed to leverage the reliability, availability and serviceability of the z/OS platform as well as the special features of DB2. Users of DB2 for z/OS generally augment these parameters and options with site-specific standards, naming conventions, operator procedures and OEM products. For this reason, the assumptions and suggestions contained in this document and the db2_zOS.sql obtained from Wily Technology should be thoroughly and carefully reviewed prior to installation of the Introscope Enterprise Manager.
Assumptions
Table Usage
The database contains 14 tables and one view. There is a single unique index defined on each table. The following tables are small, non-volatile, code tables: WT_PROPERTY WT_AGENT WT_RESOURCE WT_RESOURCE_METRIC WT_METRIC_NAME WT_RECORD_TYPE WT_VERSIONLIST WT_INDEX WT_METADATA WT_TMP_Q_1 WT_TMP_Q_2 WT_TMP_Q_3 WT_TMP_Q_4
Page 74
Currently, the DDL for these tables takes all defaults except for IN database.
WT_METRIC
The WT_Metric table is the largest table in the Introscope Enterprise Manager database and the most heavily used. The implementation of the Introscope Enterprise Manager described below represents the anticipated upper bound for number of agents deployed and number of Metrics collected. Consequently, this implementation represents the anticipated upper bound for the size of the WT_Metric table.
Environment
The Introscope Enterprise Manager is the primary means of accessing the WT_Metric table. Only rarely will SQL queries be executed against the WT_Metric table outside of the Introscope Enterprise Manager application.
Page 75
Overview
The process of configuring Introscope Security and Permissions involves the following tasks: Configuring Domains Configuring User Authentication (and optionally external authentication) Defining User Permissions
Domain Types
There are two types of Domains in Introscope: SuperDomain User-defined Domain
SuperDomain
The SuperDomain is the superset Domain that contains all user-defined Domains in the system, and holds any Agents which are not specifically mapped to a Domain. In the default configuration shipped with Introscope, there is only one Domain: the SuperDomain. If no other Domains are configured by a user, all Agents will be mapped to the SuperDomain.
Page 76
User-defined Domains
New Domains are defined in the <Introscope home>/config/domains.xml file. The file provides mappings of Domain names to regular expressions.
Creating Domains
If Domains are added/removed/edited, the changes will not be recognized until the Enterprise Manager is restarted.
value
name of Domain short description of Domain fully-qualified Agent name (Domain|host|process|Age nt) for Agent
Rules
alphanumeric characters only, and _ and no spaces allowed any characters except quotation marks The value of agent mapping attribute is a Perl5 regular expression special characters (such as the pipe character) must be escaped with a backslash The Agent name defined must match the actual full Agent name exactly (spelled correctly and also matching in case) or it will be placed in the SuperDomain instead of being mapped to the desired Domain.
grant user
permission
Users are granted permissions per Domain. Domain permissions are discussed in Defining User Permissions, page 88.
Here is the Domain syntax: <domain name=Domainname description=Domain description> <agent mapping=host\|process\|agentname or matching agents/> <grant user=username permission=permission/> </domain>
Configuring and Managing Domains You may have multiple Agent mappings within a Domain or SuperDomain If an Agent matches the mapping in more than one Domain defined in the XML file, the Agent will be placed in the first Domain in the list that it matches. You may change the Agent mapping of the SuperDomain If you do not alter the current SuperDomain Agent mapping (by default it is configured to match all Agents), place any newly created Domains before the <SuperDomain> tags. Agents that do not match any mappings (either due to mistakes in the regular expressions in the domains.xml file, or other issues) will be placed in the SuperDomain
Note: If there are any syntax or other errors in the domains.xml file, the Enterprise
Next Steps
Each Introscope user configured in the users.xml file or defined in an external authentication system will need Domain permissions. See Defining User Permissions, page 88.
<Introscope home>/config/modules/PetstoreA Note: The Domain directory must match the name defined in the domains.xml file
exactly (spelled correctly and also matching in case) or any Management Modules that reside in the directory will not be loaded.
Page 78
Configuring and Managing Domains 2. 3. Move the desired Management Module from the <Introscope home>/config/ modules directory into the new directory you just created. Restart the Enterprise Manager so it can load the new Domains.
newly created Domain. For example, if you created a Domain called Petstore A, you would copy the file into the following directory:
<Introscope home>/config/modules/PetstoreA
2. Restart the Enterprise Manager so it can load the new Management Module. linked in any way to the original Sample Management Module. Any changes to the original Sample Management Module will NOT be reflected in any copies of the Sample Management Module in other Domains, and vice versa.
Note: IMPORTANT! The Sample Management Module copied into the new Domain is NOT
Deleting a Domain
You may need to delete a Domain when you: assign an Agent to a different Domain merge two Domains To delete a Domain and disconnect its associations: 1. 2. 3. 4. Shut down the Enterprise Manager. Delete the Domain from the <Introscope home>/config/domains.xml file. If necessary, reassign any mapped Agents to different Domains. Delete the corresponding Domain directory from <Introscope home>/config/ modules.
Page 79
Note: If any Management Modules already exist in the target Domain directory with
the same name as the ones you are moving over, you will need to rename the Management Modules from the source Domain.
7. 8.
Delete the source Domain from domains.xml. Restart the Enterprise Manager.
3. 4.
Page 80
Configuring User Authentication 1. 2. 3. 4. 5. 6. 7. 8. Open the <Introscope home>/config/domains.xml file in the source installation. Copy the Domain information. Open the <Introscope home>/config/domains.xml file in the target installation. Copy the Domain information into the domains.xml file. In the target installation, create new Management Module directories that correspond to those in the source installation in <Introscope home>/config/modules. Copy any Management Modules that belong to the Domain you are moving over and paste them into the corresponding Domain directories. Delete the Domain from the source installation. Restart the Enterprise Manager.
Page 81
IntroscopeEnterpriseManager.properties.
introscope.enterprisemanager.authentication.providers=local
4. Save changes to this file if necessary, and restart the Enterprise Manager.
Note: If you are migrating users from a previous Introscope installation, do not change the name or location of the users.xml file until after migration is complete.
To configure the pathname of the local authentication file: 1. 2. 3. Open the file, <Introscope home>/config/
LocalAuthenticationExtension.properties.
For the property, authentication.extension.local.userFile, enter the path of the users.xml file. Save changes, and restart the Enterprise Manager.
Defining a User
User Configuration Modifiers and Syntax
You must define a username and password for each user. The following table contains the modifiers for defining users: TABLE 8. User configuration attributes Modifier
name
value
username
Rules
alphanumeric characters only, and _ and -
Page 82
Modifier
password
value
user password
Rules
any characters except quotation marks by default, passwords are in clear-text and are not encrypted or obfuscated (can optionally generate encoded passwords) password characters can be legal xml characters a password value can be empty
Defining a User
To define a user: 1. 2. Open the <Introscope home>/config/users.xml file in an xml editing program. Define a user name and password using the above attributes and syntax.
Note: If there are any syntax or other errors in the users.xml file, the Enterprise
Manager will not start.
for Windows,
3.
Copy the generated encoded password, and past it into the password attribute of the <user> tag im the users.xml file. For example:
Next Steps
If you are using local authentication, you must define Domain and Enterprise Manager permissions for each user, in the next section, Defining User Permissions, page 88. Workstation login will fail for a user with no defined Domain or Enterprise Manager permissions.
Configuring External Authentication IBM Directory Server (version 5.1) SunONE Directory Server (version 5.1) MS Active Directory (Windows 2000 version) LDAP authentication is configured in the <Introscope home>/config/ LDAPAuthenticationExtension.properties file. You must first configure the Enterprise Manager to use LDAP as the primary authentication mechanism, and then configure LDAP extension properties.
home>/ext/LDAPAuthenticationExtension.jar.
Open the file, <Introscope home>/config/ Locate the Authentication Providers section. For the property,
IntroscopeEnterpriseManager.properties.
introscope.enterprisemanager.authentication.providers=ldap
5. Check that the following LDAP configuration properties are present and uncommented:
Note: If there are any syntax or other errors in the LDAPAuthenticationExtension.properties file, the Enterprise Manager will
not start. The following table describes the properties in this file:
Page 85
This Setting
authentication.extension.ldap.url=
Specifies
URL for the remote LDAP server The default port for non-SSL connections is 389, the default port for SSL connections is 636.
Default Setting
ldap://host:port
Whether to use SSL to connect to remote LDAP server Name used to bind to LDAP server. If blank, anonymous bind is used. Password used to bind to LDAP server. If anonymous bind is used, this property is ignored. Authentication type to use when binding. Options are: none, simple, CRAMMD5.
simple
Suffix to append to Introscope user name for use with LDAP queries. Base distinguished name (DN) for all user object queries Search depth when querying for a user object Name of LDAP attribute that will match an Introscope username LDAP search filter used to query a user object. The token %u will be filled in with the Introscope username before the query executes. Name of certificate file. Supported certificate types are of type X.509, and base64-encoded. If not specified, default certificate authorities provided by the JVM will be used (see http://
authentication.extension.ldap.serverCertif icate
blank
java.sun.com/j2se/1.4.2/docs/ index.html).
Page 86
authentication.extension.ldap.url=ldaps://jonesey.acme.com:636 authentication.extension.ldap.useSSL=true authentication.extension.ldap.bindName= authentication.extension.ldap.bindPassword= authentication.extension.ldap.bindAuthentication=simple authentication.extension.ldap.user.nameSuffix= authentication.extension.ldap.user.baseDN=ou=fjones,cn=users,dc=acme ,dc=com authentication.extension.ldap.user.scopeDepth=subtree authentication.extension.ldap.user.usernameAttribute=uid authentication.extension.ldap.user.userObjectQuery=(&(uid=%u)(object class=person)) authentication.extension.ldap.serverCertificate=config/spock2.cer
authentication.extension.ldap.url=ldaps://jonesey.acme.com:636 authentication.extension.ldap.useSSL=true authentication.extension.ldap.bindName= authentication.extension.ldap.bindPassword= authentication.extension.ldap.bindAuthentication=simple authentication.extension.ldap.user.nameSuffix= authentication.extension.ldap.user.baseDN=ou=users,dc=acme,dc=com authentication.extension.ldap.user.scopeDepth=subtree authentication.extension.ldap.user.usernameAttribute=uid authentication.extension.ldap.user.userObjectQuery=(&(uid=%u)(object class=user)) authentication.extension.ldap.serverCertificate=config/ acmebase64.cer
MS Active Directory
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 87
Defining User Permissions The following example shows LDAP properties configured for use with MS Active Directory, using SSL.
authentication.extension.ldap.url=ldaps://173.92.10.15:636 authentication.extension.ldap.useSSL=true authentication.extension.ldap.bindName= authentication.extension.ldap.bindPassword= authentication.extension.ldap.bindAuthentication=simple authentication.extension.ldap.user.nameSuffix=@dev.com authentication.extension.ldap.user.baseDN=cn=Users,dc=dev,dc=com authentication.extension.ldap.user.scopeDepth=subtree authentication.extension.ldap.user.usernameAttribute=cn authentication.extension.ldap.user.userObjectQuery=(&(cn=%u)(objectc lass=user)) authentication.extension.ldap.serverCertificate=config/sulu5.cer
domains.xml
Enterprise Manager permissions are configured in <Introscope home>/
config/server.xml
Permissions Rules
Permissions for a user are fixed when a user logs in; if changes are made for that user while they are logged in, they will not be recognized until the next time that user attempts to log in. This means that a user will not be booted off if their permissions are removed while they are logged in. Introscope permissions are dynamic; the domains.xml and server.xml files are checked whenever a user attempts to log in. Thus, permissions changes can be made without restarting the Enterprise Manager.
Domain Permissions
Domain Access Rules
the SuperDomain is treated just like any other Domain in terms of permissions
Page 88
Defining User Permissions Any permissions granted to a user with access to the SuperDomain will also allow them to use these privileges in all user-defined Domains. one user can have multiple permissions for a single Domain one user can have permissions in multiple Domains if a user has multiple permissions, use one line for each user/permission pair
Definition
User can view all Agents and business logic in Domain. This includes tasks such as: Viewing Explorer tree (which will show Agents and Management Modules in the Domain user has access to) Viewing Dashboards in the Console Viewing Metric and Element data in the Explorer Preview pane, including default Top N Filtered Views for certain Resources in the Explorer tree Viewing any Management Module, Agent or Element settings Viewing Alert messages Refreshing historical data in a historical Data Viewer, and zoom in and out Changing historical date range options for historical Data Viewer Showing/Hiding Metrics in a Graph Moving Metrics in a Data Viewer to the back or front Changing User Preferences (setting a home Dashboard, displaying Management Module names with Dashboard names) Note: Users with read permission will be able to see all commands in the Workstation, but the commands they do not have access to will be disabled.
write
A user with write permission can do everything a user with read permission can, but can also: view all Agents and business logic in Domain create and edit Dashboards edit all monitoring logic in a Domain
run_tracer
Page 89
Permission
live_agent_control
Definition
User can shut off reporting for Metrics, Resources, and Agent within Domain
Note: If there are any syntax or other errors in the domains.xml file, the Enterprise
<domain name="HRApplication" description=""> <agent mapping="(.*)HRAppAgent(.*)" /> <grant user="bsmith" permission="full" /> <grant user="fjones" permission="read" /> <grant user="fjones" permission="run_tracer" /> </domain>
<SuperDomain> <agent mapping="(.*)"/> <grant user="jlo" permission="write"/> <grant user="pdiddy" permission="read"/> </SuperDomain>
</domains>
Server Permissions
Server permissions are defined for activities relating to operation of the Enterprise Manager: shutting down the Enterprise Manager purging non-reporting Metrics publishing MIB files
Page 91
Definition
User can shut down the Enterprise Manager. User can remove Metrics from persistent data store (only database) User can publish SNMP collection data to a MIB.
Note: If there are any syntax or other errors in the server.xml file, the Enterprise
<grant user="bsmith" permission="shutdown" /> <grant user="tjones" permission="purge_metrics" /> <grant user="tjones" permission="publish_mib" /> </server>
Note: For more information on Agent Failover, see Agent Failover, page 173.
Page 93
If you are using this Application Server WebLogic WebSphere (distributed) WebSphere on z/OS Sun ONE Oracle 10g Fujitsu Interstage 6.0 (Japanese version) SAP NetWeaver Other Application Server (other than those listed above) Any - Using ProbeBuilder Wizard or Command-Line ProbeBuilder
Page 94
Agent.jar IntroscopeAgent.profile
connectors/CreateAutoProbeConnector.jar WebAppSupport.jar Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 95
ProbeBuilder Configuration Options Several .pbd and .pbl files (ProbeBuilder Directives and List files)
Page 96
ProbeBuilder Configuration Options you would use the instructions in the section, JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99. If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. TABLE 11. ProbeBuilder Configuration Options Table
JVM
WebLogic 9.0
JVM AutoProbe 5.0 JVM JRockit JVM AutoProbe Using Java 5.0 JVM, page 99 JVM AutoProbe With WebLogic Using WebLogic JRockit, page 100
WebLogic 8.1
JVM AutoProbe Sun IBM HP JRockit JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using HP HotSpot JVM, page 100 JVM AutoProbe With WebLogic Using WebLogic JRockit, page 100
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebLogic 8.1, page 101
WebLogic 7.0
JVM AutoProbe Sun IBM HP JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using HP HotSpot JVM, page 100
Page 97
JRockit
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebLogic 7.0, page 101
WebLogic 6.1SP3
JVM AutoProbe Sun IBM HP JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using HP HotSpot JVM, page 100
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebLogic 6.1 SP3, page 101
WebLogic 6.1
JVM AutoProbe Sun IBM HP JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99 JVM AutoProbe With WebLogic Using HP HotSpot JVM, page 100
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebLogic 6.1, page 102
Page 98
-javaagent:<path-to-Agent.jar>
2. Proceed to the section, Configuring Basic Agent Settings for WebLogic, page 102 to configure the Agent profile.
Note: This method will not work with WebLogic 9.0. Use the method described in the
section, JVM AutoProbe Using Java 5.0 JVM, page 99.
wily/connectors/AutoProbeConnector.jar
startMedRecServer.cmd) using the following command to include the AutoProbeConnector.jar you created:
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 99
-Xbootclasspath:wily/connectors/
AutoProbeConnector.jar:<jvm_home>/lib/rt.jar:<jvm_home>/lib/ i18n.jar:<path-to-Agent.jar> Note: If you are using something other than the default bootstrap classpath, add the Agent.jar and AutoProbeConnector.jar files to the beginning of
your customized bootstrap classpath. 2. Proceed to the section, Configuring Basic Agent Settings for WebLogic, page 102 to configure the Agent profile.
-Xprepcom/wily/introscope/api/hp/HPAutoProbeFactory -Xbootclasspath/a:<path-to-Agent.jar>
3. Proceed to the section, Configuring Basic Agent Settings for WebLogic, page 102 to configure the Agent profile.
-Xbootclasspath/a:<path-to-Agent.jar> -Xmanagement:class=com.wily.introscope.api.jrockit. AutoProbeLoader Note: The above command should be all on one line.
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 100
-Dweblogic.classloader.preprocessor= com.wily.introscope.api.weblogic.PreProcessor
3. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 102.
startWLS.cmd) with the -D option. This will activate Introscope AutoProbe: -Dweblogic.classloader.preprocessor= com.wily.introscope.api.weblogic.PreProcessor
3. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 102.
-Dweblogic.classloader.preprocessor= com.wily.introscope.api.weblogic.PreProcessor
3. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 102.
Agent.jar file.
Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 102.
#TurnOn: HTTPServletTracing
4. Turn on the HTTPAppServerAutoProbeServletTracing Tracer group by removing the pound sign from the beginning of the line, as in the following example:
TurnOn: HTTPAppServerAutoProbeServletTracing
5. 6. Repeat steps 2-4 for <WebLogic home>/wily/toggles-typical.pbd Proceed to the section, Configuring Basic Agent Settings for WebLogic, page 102 to configure the Agent profile.
com.wily.introscope.agentProfile
Page 102
Configuring Basic Agent Settings for WebLogic if com.wily.introscope.agentProfile is not defined (or the Agent profile is not found in the defined location) it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log. See AutoProbe ProbeBuilder Log, page 201.
Agent Naming
The standard method to name an Agent is to define its name in the property, introscope.agent.agentName, in the IntroscopeAgent.profile. Use this method if you have one Agent profile for each Agent already set up. You may also use automatic Agent Naming, which is enabled by default for WebLogic. To fully configure WebLogic to use automatic Agent naming, see Additional Configuration Options, page 104, and for more information on automatic Agent naming, see Agent Naming Options, page 169.
Page 103
Property
introscope.agent.enterprisemanager.transport .tcp.host.DEFAULT
introscope.enterprisemanager.por t.agentlistener in the introscopeEnterpriseManager.prop erties file for each matching Enterprise
Note: This property name should be on one
Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover.
For information on Agent Failover, see Agent Failover, page 173. introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. introscope.agent.customProcessName Enter name for process being monitored.
Page 104
com.wily.introscope.api.weblogic.IntroscopeStartupClass
7. Click Create. The Target and Deploy tab is shown. 8. 9. Check the box(es) for the server(s) youd like to make this startup class available to. Click Apply. This startup class is implemented in WebAppSupport.jar, so be sure to add the location of the WebAppSupport.jar to the application startup classpath.
Page 105
Agent.jar IntroscopeAgent.profile
WebAppSupport.jar connectors/CreateAutoProbeConnector.jar Several .pbd and .pbl files (ProbeBuilder Directives and List files) Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 106
Page 107
ProbeBuilder Configuration Options If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. TABLE 12. ProbeBuilder Configuration Options Table
JVM
JVM AutoProbe Sun IBM HP JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108 JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108 JVM AutoProbe With WebSphere Using HP HotSpot JVM, page 110
Application Server AutoProbe any Manual ProbeBuilder any WebSphere 4.0 JVM AutoProbe Sun IBM HP JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108 JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108 JVM AutoProbe With WebSphere Using HP HotSpot JVM, page 110 Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebSphere 6.0/5.1/5.0, page 111
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebSphere 4.0 (Distributed), page 112
ProbeBuilder Configuration Options run the AutoProbe Connector by modifying the classpath with the location of the AutoProbe connector, Agent, and ProbeBuilder The following section details how to configure JVM AutoProbe.
wily/connectors/AutoProbeConnector.jar
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:<pathto-Agent.jar>
3. 4. 5. Click OK. Apply the changes in the Administrators Console. Restart the Web Application Server.
Page 109
ProbeBuilder Configuration Options 6. Proceed to the section, Configuring Basic Agent Settings on WebSphere, page 113 to configure the Agent profile.
// permissions for Introscope AutoProbe grant codeBase "file:${was.install.root}/-" { permission java.io.FilePermission "${was.install.root}${/}wily${/}-", "read"; permission java.net.SocketPermission "*", "connect,resolve"; permission java.lang.RuntimePermission "setIO"; permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.RuntimePermission "modifyThread"; permission java.lang.RuntimePermission "modifyThreadGroup"; permission java.lang.RuntimePermission "loadLibrary.*"; permission java.lang.RuntimePermission "accessClassInPackage.*"; permission java.lang.RuntimePermission "accessDeclaredMembers"; }; grant { permission java.util.PropertyPermission "*", "read,write"; };
Note: Make sure each permission statement is on one line (does not break across lines).
wily/connectors/AutoProbeConnector.jar:<path-to-Agent.jar>
4. 5. 6. Apply the changes in the Administrators Console. Restart the Web Application Server. Proceed to the section, Configuring Basic Agent Settings on WebSphere, page 113 to configure the Agent profile.
Page 110
ProbeBuilder Configuration Options 1. 2. Install HP Hotspot JVM 1.2.2.08 or higher. This can be obtained from http:// www.hp.com/products1/unix/java. Add the following command-line options to the JVM command line:
-Xprepcom/wily/introscope/api/hp/HPAutoProbeFactory -Xbootclasspath/a:<path-to-Agent.jar>
3. Proceed to the section, Configuring Basic Agent Settings on WebSphere, page 113 to configure the Agent profile.
-Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api .websphere.WASAutoProbe -Dcom.wily.introscope.agentProfile=<path to IntroscopeAgent.profile> OR -Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api .websphere.WASAutoProbe -Dcom.wily.introscope.agentResource=<path to Resource containing IntroscopeAgent.profile> Note: Although the examples above break across lines, make sure that your
argument does not have any breaks. 4. Apply the changes in the Administrators Console. Page 111
ProbeBuilder Configuration Options 5. 6. Restart the Web Application Server. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 113.
//permissions for Introscope AutoProbe grant codeBase "file:${was.install.root}/-" { permission java.io.FilePermission "${was.install.root}${/ }wily${/}-", "read"; permission java.net.SocketPermission "*", "connect,resolve"; permission java.lang.RuntimePermission "setIO"; permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.RuntimePermission "modifyThread"; permission java.lang.RuntimePermission "modifyThreadGroup"; permission java.lang.RuntimePermission "loadLibrary.*"; permission java.lang.RuntimePermission "accessClassInPackage.*"; permission java.lang.RuntimePermission "accessDeclaredMembers"; }; grant { permission java.util.PropertyPermission "*", "read,write"; };
Configuring Basic Agent Settings on WebSphere Name: com.ibm.websphere.classloader.plugin Value: com.wily.introscope.api.websphere.WASAutoProbe Name: com.wily.introscope.agentProfile Value: <path-to-IntroscopeAgent.profile> 4. 5. 6. Apply the changes in the Administrators Console. Restart the Web Application Server. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 113.
#TurnOn: HTTPServletTracing
4. Turn on the HTTPAppServerAutoProbeServletTracing Tracer group by removing the pound sign from the beginning of the line, as in the following example:
TurnOn: HTTPAppServerAutoProbeServletTracing
5. 6. Repeat steps 2-4 for <WebSphere home>/wily/toggles-typical.pbd Proceed to the section, Configuring Basic Agent Settings on WebSphere, page 113 to configure the Agent profile.
com.wily.introscope.agentProfile
Page 113
Configuring Basic Agent Settings on WebSphere if com.wily.introscope.agentProfile is not defined, (or the Agent profile is not found in the defined location), it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory.
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log.
See AutoProbe ProbeBuilder Log, page 201.
Agent Naming
The standard method to name an Agent is to define its name in the property, introscope.agent.agentName, in the IntroscopeAgent.profile. Use this method if you have one Agent profile for each Agent already set up. You may also use automatic Agent Naming, which is enabled by default for WebSphere 5.0 and higher. To fully configure WebSphere to use automatic Agent naming, see Additional Configuration Options, page 115. For more information on automatic Agent naming, see Agent Naming Options, page 169.
Note: Automatic Agent Naming is enabled by default but not supported on WebSphere
4.0. If you are using WebSphere 4.0.x, disable this feature using the instructions in the next section. Page 114
Property
introscope.agent.enterprisemanager.t ransport.tcp.host.DEFAULT
Note: This property name should be on one line. Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover. For information on Agent Failover, see Agent Failover, page 173.
introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. introscope.agent.customProcessName Enter name for process being monitored.
Page 115
com.wily.introscope.api.websphere.IntroscopeCustomService
5. In the Display Name field, enter:
<WebSphere home>/wily/WebAppSupport.jar
7. 8. Click OK. Restart the application server.
Page 116
IntroscopeAgentInstall6.0.1websphere.zOS.tar
3. Extract the installer file into the Java systems working directory, commonly the Web Application Servers installation directory. Agent files are located in a newly-created /wily directory. The following files in this directory are referenced in configuration instructions in this chapter:
Agent.jar IntroscopeAgent.profile
WebAppSupport.jar connectors/CreateAutoProbeConnector.jar Several .pbd and .pbl files (ProbeBuilder Directives and List files)
Page 117
Page 118
ProbeBuilder Configuration Options If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. TABLE 13. ProbeBuilder Configuration Options Table
JVM
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS, page 122
ProbeBuilder Configuration Options To create the AutoProbe connector: 1. 2. Change the working directory to wily/connectors under the installation directory. Run the Create AutoProbe Connector tool using one of the following commands: specifying the JVM using the JVM running the tool:
wily/connectors/AutoProbeConnector.jar
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:<pathto-Agent.jar>
5. Click on Custom Properties and add the following two name value pairs: define the Agent profile location
Page 120
ProbeBuilder Configuration Options 7. Check that all newly created Introscope files and directories within the ./wily directory are read-accessible by the WebSphere process. In addition, all *.log files (written by the Introscope Agent and ProbeBuilder) in the ./wily folder should be granted write-access to the WebSphere process. Restart WebSphere. Proceed to the section, Configuring Basic Agent Settings for WebSphere, page 124 to configure the Agent profile.
8. 9.
// permissions for Introscope AutoProbe grant codeBase "file:${was.install.root}/-" { permission java.io.FilePermission "${was.install.root}${/ }wily${/}-", "read"; permission java.net.SocketPermission "*", "connect,resolve"; permission java.lang.RuntimePermission "setIO"; permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.RuntimePermission "modifyThread"; permission java.lang.RuntimePermission "modifyThreadGroup"; permission java.lang.RuntimePermission "loadLibrary.*"; permission java.lang.RuntimePermission "accessClassInPackage.*"; permission java.lang.RuntimePermission "accessDeclaredMembers"; }; grant { permission java.util.PropertyPermission "*", "read,write"; };
Page 121
Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS
The following instructions work with WebSphere 5.0.x on z/OS: 1. 2. 3. 4. In WebSphere, start the Administrators Console, and go to the JVM Settings section for the application server you want to modify. Select Application Servers > <your server> > Process Definition. You should see two items, Control and Servant. Click Servant, then JavaVirtualMachine. Set the Generic JVM Argument field to specify the classloader plugin, and the location of the IntroscopeAgent.profile file. You will set EITHER the com.wily.introscope.agentProfile, OR com.wily.introscope.agentResource. The argument will then have the following value (there are several properties set in one argument):
-Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api .websphere.WASAutoProbe -Dcom.wily.introscope.agentProfile=<path to IntroscopeAgent.profile> OR -Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api .websphere.WASAutoProbe -Dcom.wily.introscope.agentResource=<path to Resource containing IntroscopeAgent.profile> Note: Although the examples above breaks across lines, make sure that your
argument does not have any breaks. 5. Place the Agent.jar file in the <WebSphere Instance dir>/lib/ext directory.
Note: Do not place the Agent.jar file in the WebSphere installation directory.
The following shows examples of the wrong and right directory: NO: /usr/lpp/zWebSphere/V5R0M0/lib/ext YES: /WebSphere/V5R0M0/AppServer/lib/ext 6. The default for file encoding for WebSphere 5.x and 6.0 on z/OS is now ASCII, but Introscope expects EBCDIC file format. Click on Custom Properties and add the name value pair:
Page 122
ProbeBuilder Configuration Options 7. Check that all newly created Introscope files and directories within the ./wily directory are read-accessible by the WebSphere process. In addition, all *.log files (written by the Introscope Agent and ProbeBuilder) in the ./wily folder should be granted write-access to the WebSphere process. These include: all the Introscope files and directories the Introscope files inside <WAS instance dir>/lib/ext 8. 9. Restart WebSphere application server. When WebSphere says open for e-business, open the Administrators Console. Metrics should start reporting.
10. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 124.
// permissions for Introscope AutoProbe grant codeBase "file:${was.install.root}/-" { permission java.io.FilePermission "${was.install.root}${/ }wily${/}-", "read"; permission java.net.SocketPermission "*", "connect,resolve"; permission java.lang.RuntimePermission "setIO"; permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.RuntimePermission "modifyThread"; permission java.lang.RuntimePermission "modifyThreadGroup"; permission java.lang.RuntimePermission "loadLibrary.*"; permission java.lang.RuntimePermission "accessClassInPackage.*"; permission java.lang.RuntimePermission "accessDeclaredMembers"; }; grant { permission java.util.PropertyPermission "*", "read,write"; };
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 123
#TurnOn: HTTPServletTracing
4. Turn on the HTTPAppServerAutoProbeServletTracing Tracer group by removing the pound sign from the beginning of the line, as in the following example:
TurnOn: HTTPAppServerAutoProbeServletTracing
5. 6. Repeat steps 2-4 for <WebSphere home>/wily/toggles-typical.pbd Proceed to the section, Configuring Basic Agent Settings for WebSphere, page 124 to configure the Agent profile.
Agent Naming
The standard method to name an Agent is to define its name in the property, introscope.agent.agentName, in the IntroscopeAgent.profile. Use this method if you have one Agent profile for each Agent already set up. Introscope also provides additional methods for the Agent to find its name automatically. Automatic Agent Naming is enabled by default for WebSphere 5.0 and higher. To fully configure WebSphere to use automatic Agent naming, see Additional Configuration Options, page 126, and for more information on automatic Agent naming, see Agent Naming Options, page 169.
Note: Automatic Agent Naming is enabled by default but not supported on WebSphere
4.0. If you are using WebSphere 4.0.x, disable this feature using the instructions in the next section.
Page 124
Disabling Automatic Agent Naming for WebSphere 5.x and 6.0 for z/OS
To disable Automatic Agent Naming: 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. Set the value of the property, introscope.agent.agentAutoNamingEnabled, to false. Value and Description
The host setting should be either the host name or IP address of a machine with an Enterprise Manager on it.
Property
introscope.agent.enterprisemanager.tra nsport.tcp.host.DEFAULT
line.
Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover. For information on Agent Failover, see Agent Failover, page 173.
introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. introscope.agent.customProcessName Enter name for process being monitored.
Page 125
log4j.appender.console.encoding=IBM-1047 log4j.appender.logfile.encoding=IBM-1047
If these properties are not present in your existing IntroscopeAgent.profile, then you need to add them. In addition, a new property has been added for z/OS WebSphere Version 5.0 and above, which is used to eliminate any startup timing window exposures that can occur with the Introscope logging facilities. The following property should be added to your IntroscopeAgent.profile:
introscope.agent.logger.delay=100000
The delay value is in expressed in milliseconds, so the default delay in this case is 100 seconds.
Page 126
com.wily.introscope.api.websphere.IntroscopeCustomService
7. In the Display Name field, enter:
<WebSphere home>/wily/WebAppSupport.jar
9. Click OK. 10. Restart the application server.
Page 127
Note: For Sun ONE version 7.0, the following are the minimum Sun ONE versions
required for Introscope integration: Sun ONE AS Platform Edition 7.0.0_01 (update 1) Sun ONE AS Standard Edition 7.0.0_01 (update 1) To download the appropriate application server versions, see the Sun website at http://wwws.sun.com/software/download/app_servers.html. 2. Find the Sun ONE installer file for your platform:
IntroscopeAgentInstall6.0.1sunoneas.unix.tar IntroscopeAgentInstall6.0.1sunoneas.windows.zip
3. Extract the installer file into the Sun ONE 7.0 Application Server installation directory,
Agent.jar
Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 128
IntroscopeAgent.profile
connectors/CreateAutoProbeConnector.jar Several .pbd and .pbl files (ProbeBuilder Directives and List files)
Page 129
ProbeBuilder Configuration Options Sun JVM you would use the instructions in the section, JVM AutoProbe With Sun ONE 7.0 Using Sun JVM, page 130. If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. TABLE 14. ProbeBuilder Configuration Options Table
JVM
Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With Sun ONE 7.0, page 131
wily/connectors/AutoProbeConnector.jar
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:<pathto-Agent.jar>
5. Proceed to the section, Configuring Basic Agent Settings for SunONE, page 133, to configure the Agent profile.
Page 131
Note: The use of ... in the .xml examples below denotes that there is additional
1. 2.
information in the .xml code (not relevant to the example) that is not shown.
In order to add Introscope information to startup scripts for Sun ONE 7.0, you must be logged in as Administrator or Root. Open the server.xml file, located at:
com.wily.introscope.api.sun.appserver.SunONEAutoProbe. For
example:
Page 132
Configuring Basic Agent Settings for SunONE 6. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 133.
#TurnOn: HTTPServletTracing
4. Turn on the HTTPAppServerAutoProbeServletTracing Tracer group by removing the pound sign from the beginning of the line, as in the following example:
TurnOn: HTTPAppServerAutoProbeServletTracing
5. 6. Repeat steps 2-4 for <Sun ONE home>/wily/toggles-typical.pbd Proceed to the section, Configuring Basic Agent Settings for SunONE, page 133 to configure the Agent profile.
com.wily.introscope.agentProfile
if com.wily.introscope.agentProfile is not defined (or the Agent profile is not found in the defined location) it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory
Page 133
Configuring Basic Agent Settings for SunONE define a system property on the Java command line with the -D option to specify the full path to the location of the IntroscopeAgent.profile file: com.wily.introscope.agentProfile
Make the Agent profile (IntroscopeAgent.profile) available in a resource on the classpath. Set com.wily.introscope.agentResource to specify the path
to the Resource containing the Agent profile.
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log.
See AutoProbe ProbeBuilder Log, page 201.
Page 134
introscope.agent.enterprisemanager.transpor t.tcp.host.DEFAULT
The host setting should be either the host name or IP address of a machine with an Enterprise Manager on it.
Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover. For information on Agent Failover, see Agent Failover, page 173.
introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. introscope.agent.customProcessName Enter name for process being monitored.
Page 135
IntroscopeAgentInstall6.0.1oracleas.unix.tar IntroscopeAgentInstall6.0.1oracleas.windows.zip
3. Extract the installer file into the Oracle Application Server 10g installation directory, <Oracle 10g home>. Agent files are located in a newly-created /wily directory. The following files in this directory are referenced in configuration instructions in this chapter:
Agent.jar IntroscopeAgent.profile connectors/CreateAutoProbeConnector.jar Several .pbd and .pbl files (ProbeBuilder Directives and List files)
Page 136
JVM
wily/connectors/AutoProbeConnector.jar
Page 138
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:<pathto-Agent.jar>
2. Proceed to the section, Configuring Basic Agent Settings for Oracle 10g, page 140 to configure the Agent profile.
#TurnOn: HTTPServletTracing
4. Turn on the HTTPAppServerAutoProbeServletTracing Tracer group by removing the pound sign from the beginning of the line, as in the following example:
TurnOn: HTTPAppServerAutoProbeServletTracing
5. 6. Repeat steps 2-4 for <Oracle 10g home>/wily/toggles-typical.pbd Proceed to the section, Configuring Basic Agent Settings for Oracle 10g, page 140 to configure the Agent profile.
Page 139
com.wily.introscope.agentProfile
if com.wily.introscope.agentProfile is not defined (or the Agent profile is not found in the defined location) it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log. See AutoProbe ProbeBuilder Log, page 201.
Page 140
Configuring Basic Agent Settings for Oracle 10g Process Name Property
introscope.agent.enterprisemanager. transport.tcp.host.DEFAULT
line.
introscope.agent.enterprisemanager. transport.tcp.port.DEFAULT
The value should be the port on which the Enterprise Manager listens for Agent connections. Default setting is 5001. The port specified in this setting must match the port defined in the setting, introscope.enterprisemanager.port.agentlist ener in the introscopeEnterpriseManager.properties file for each matching Enterprise Manager. See Uninstalling Introscope, page 54.
Note: This property name should be on one line. Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover. For information on Agent Failover, see Agent Failover, page 173.
introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. introscope.agent.customProcessName Enter name for process being monitored.
Page 141
Operating System
Windows Solaris HP-UX AIX Linux
Installer Filename
IntroscopeAgentInstall6.0.1netweaver.windows.zip IntroscopeAgentInstall6.0.1netweaver.unix.tar
Page 142
IntroscopeAgentInstall6.0.1netweaver.unix.SAP.tar
2.
Extract the installer file into the Java systems working directory, commonly the Java Applications installation directory. Agent files are located in a newly-created /wily directory. The following files in this directory are referenced in configuration instructions in this chapter:
Agent.jar IntroscopeAgent.profile
Several .pbd and .pbl files (ProbeBuilder Directives and List files). connectors/CreateAutoProbeConnector.jar 3. If you want to use any custom .pbd files, add them to the /wily directory.
Choose a ProbeBuilder configuration option: If using JVM AutoProbe, locate the JVM you are running, and use the instructions associated with that JVM If using Manual ProbeBuilder, use the instructions associated with that option.
Page 143
ProbeBuilder Configuration Options If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. TABLE 16. ProbeBuilder Configuration Options Table
Application Server
JVM
Note: You will have to re-create the AutoProbe connector if you update the JVM that is
used for the SAP J2EE nodes, even if you just change the patch level, e.g., from 1.4.2_04 to 1.4.2_05! For this reason it is also important that you specify exactly the same JVM that is actually used by the SAP J2EE nodes.
wily/connectors/AutoProbeConnector.jar
<drive>:\usr\sap\<J2EE_ENGINE_ID>\j2ee\j2ee_<INSTANCE>\cluster\ server\cmdline.properties
2. Append the following commands to JavaParameters:
Page 145
ProbeBuilder Configuration Options 3. In the Java Parameters field, add the following new java parameters:
-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>;<path-toAgent.jar> -Dcom.wily.introscope.agentProfile=<path-toIntroscopeAgent.profile> For example: -Xbootclasspath/p:D:/usr/sap/ccms/wily/connectors/ AutoProbeConnector.jar;D:/usr/sap/ccms/wily/Agent.jar -Dcom.wily.introscope.agentProfile=D:/usr/sap/ccms/wily/ IntroscopeAgent.profile Note: Note that for NetWeaver 6.40 on Windows, the slashes for these java
parameters must go forwards. 4. 5. 6. 7. Click the disk button to save. Repeat steps 2 - 4 for each server. Restart SAP server. To verify that Config tool changes were made, open the file:
<drive>:\usr\sap\ccms\P66\JC00\j2ee\cluster\instance.properties
8. 9. Check for a line beginning with ID<server_id>.JavaParameters, and see if it contains the lines you entered in the step above. Proceed to the section, Configuring Basic Agent Settings, page 147 to configure the Agent profile.
-Xprepcom/wily/introscope/api/hp/HPAutoProbeFactory -Xbootclasspath/a:<path-to-Agent.jar>
3. Proceed to the section, Configuring Basic Agent Settings, page 147 to configure the Agent profile.
Page 146
com.wily.introscope.agentProfile
if com.wily.introscope.agentProfile is not defined, (or the Agent profile is not found in the defined location), it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory.
com.wily.introscope.agentProfile
Make the Agent profile (IntroscopeAgent.profile) available in a resource on the classpath. Set com.wily.introscope.agentResource to specify the path to the Resource containing the Agent profile.
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log.
See AutoProbe ProbeBuilder Log, page 201.
Page 147
Property
introscope.agent.enterprisemanager .transport.tcp.host.DEFAULT
Note: This property name should be on one line. Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover.
For information on Agent Failover, see Agent Failover, page 173. introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. introscope.agent.customProcessNa me Enter name for process being monitored.
Page 148
ProbeBuilder Configuration Options Agent files are located in a newly-created /wily directory. The following files in this directory are referenced in configuration instructions in this chapter:
Agent.jar IntroscopeAgent.profile
Several .pbd and .pbl files (ProbeBuilder Directives and List files). connectors/CreateAutoProbeConnector.jar 3. If you want to use any custom .pbd files, add them to the /wily directory.
Page 150
JVM
JVM AutoProbe Using Java 5.0 JVM, page 151 JVM AutoProbe Using Sun or IBM JVM, page 151 JVM AutoProbe Using Sun or IBM JVM, page 151 JVM AutoProbe Using HP HotSpot JVM, page 152
-javaagent:<path-to-Agent.jar>
2. Proceed to the section, Configuring Basic Agent Settings, page 152 to configure the Agent profile.
Page 151
wily/connectors/AutoProbeConnector.jar
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:<pathto-Agent.jar>
2. Proceed to the section, Configuring Basic Agent Settings, page 152 to configure the Agent profile.
-Xprepcom/wily/introscope/api/hp/HPAutoProbeFactory -Xbootclasspath/a:<path-to-Agent.jar>
3. Proceed to the section, Configuring Basic Agent Settings, page 152 to configure the Agent profile.
com.wily.introscope.agentProfile
if com.wily.introscope.agentProfile is not defined, (or the Agent profile is not found in the defined location), it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 152
com.wily.introscope.agentProfile
Make the Agent profile (IntroscopeAgent.profile) available in a resource on the classpath. Set com.wily.introscope.agentResource to specify the path to the Resource containing the Agent profile.
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log.
See AutoProbe ProbeBuilder Log, page 201.
Property
introscope.agent.enterprisemanager .transport.tcp.host.DEFAULT
Note: This property name should be on one line. Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover.
For information on Agent Failover, see Agent Failover, page 173.
Page 153
introscope.agent.agentName
Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character.
introscope.agent.customProcessNa me
Page 154
Configuring Java Applications With ProbeBuilder Wizard perform a full Introscope installation Introscope-enable the application code using ProbeBuilder Wizard configure basic Introscope Agent settings
Installing Introscope
A full Introscope install is required to install the ProbeBuilder Wizard and obtain the correct .pbd directory structure. 1. 2. Install Introscope using the instructions found in Chapter 3, Installing Introscope Components. Proceed to Installing Introscope Agent, page 156.
IntroscopeAgentInstall6.0.1weblogic.unix.tar IntroscopeAgentInstall6.0.1weblogic.windows.zip IntroscopeAgentInstall6.0.1weblogic.zOS.tar IntroscopeAgentInstall6.0.1weblogic.os400.zip IntroscopeAgentInstall6.0.1websphere.unix.tar IntroscopeAgentInstall6.0.1websphere.windows.zip IntroscopeAgentInstall6.0.1websphere.zOS.tar IntroscopeAgentInstall6.0.1websphere.os400.zip IntroscopeAgentInstall6.0.1hpjvm.hpux.tar IntroscopeAgentInstall6.0.1sunoneas.unix.tar IntroscopeAgentInstall6.0.1sunoneas.windows.zip IntroscopeAgentInstall6.0.1oracleas.unix.tar IntroscopeAgentInstall6.0.1oracleas.windows.zip IntroscopeAgentInstall6.0.1netweaver.windows.zip IntroscopeAgentInstall6.0.1netweaver.unix.tar
If you are not using one of the above application servers, use one of the following Agent installers for your platform:
IntroscopeAgentInstall6.0.1default.unix.tar IntroscopeAgentInstall6.0.1default.windows.zip
Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 156
IntroscopeAgentInstall6.0.1default.zOS.tar IntroscopeAgentInstall6.0.1default.os400.zip
2. Extract the installer file into the Java systems working directory, commonly the Java Applications installation directory. Agent files are located in a newly-created /wily directory. The following files in this directory are referenced in configuration instructions in this chapter:
config/custompbd directory.
Locate the bytecode to modify. Launch the ProbeBuilder Wizard located in the <Introscope home> directory. Read the Welcome screen. Click Next.
Page 157
5.
Enter your bytecode directory or click Browse to pick one, then click Next. To browse: a. b. Double-click until you reach your directory. Single-click the desired directory.
Note: You can also select .jar files or individual .class files.
Page 158
Configuring Java Applications With ProbeBuilder Wizard c. Click Select Java Bytecode to enter your desired directory and click Next.
6.
Enter the name and location for the new directory to contain the Introscope-enabled code, or click Browse to select a location. The default name is the original directory with the suffix isc.
Page 159
Configuring Java Applications With ProbeBuilder Wizard If you select a directory that already exists, ProbeBuilder Wizard will display the following dialog:
Click Overwrite to overwrite existing files as necessary, or click Cancel to go back to the previous dialog to select another location. 7. Click Next if you didnt overwrite an existing directory.
8.
In the System Directives window, locate the set of system Directives which correspond to your environment (if your application server isnt listed, use the Default Java selection). Note that you now have a choice of either using system directives files in which most Tracer groups are turned on (FULL) or only a subset of Tracer groups are turned on (TYPICAL). For more information on full and typical system directives files and the what kind of information they provide, see Full and Typical ProbeBuilder Directives Sets, page 215.
Page 160
If you installed custom Directives files in your config/custompbd directory, they appear in this window. The above screenshot shows an example where a user has installed two custom .pbd files. In the Custom Directives window, check the box next to any custom Directives that you want to use with this bytecode.
Note: For information on creating custom Directives, see Chapter 17, ProbeBuilder
Directives. 10. Check the box for any custom .pbd files you want to use, then click Add Probes. 11. Introscope adds Probes to the specified bytecode. This operation may take several minutes. 12. When the Finished screen appears, click Exit or Add Additional Probes to add Probes to another directory.
Page 161
Configuring Java Applications With Command-Line ProbeBuilder 2. Edit the classpath in the application startup script to include the path to the <Introscope home>/lib/Agent.jar. For example, you might edit a classpath that looks like this:
Note: If you are processing a very large .jar file, you may need to increase the memory
in your JVM memory settings. Consult your JVM documentation for instructions. Example:
Page 163
Result
Displays a help screen REQUIRED: a comma-separated list of ProbeBuilder Directives files (.pbd), ProbeBuilder list files (.pbl), or directories to scan. Select either a full or typical .pbl file, depending on how much information you want gathered (see Full and Typical ProbeBuilder Directives Sets, page 215). If you used the default Agent installer, you will see all possible default .pbd and .pbl files in the \wily directory. However, if you used an application-server specific Agent installer, you will only see .pbd and .pbl files specific to that application server.
Select one set of the next three pairs to specify your original code location and your Introscope-enabled code destination, using either directories, jar files, or classes. -origdir directory -destdir directory -origjar file -destjar file -origclass file -destclass file -skipitems Specifies the original directory (including subdirectories) Specifies the destination directory Specifies the original archive, including .jar, .zip, .war, .rar and .ear archives Specifies the destination archive Specifies the original class Specifies the destination class Skips any files that are not Java bytecode files or archive files (.jar and .zip files). If -skipitems is not set, the non-Java bytecode files are copied to the destination, unchanged. Turns on an interactive text UI when problems arise.
-prompt
2.
com.wily.introscope.agentProfile
if com.wily.introscope.agentProfile is not defined (or the Agent profile is not found in the defined location) it looks in the location defined in
com.wily.introscope.agentResource
if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory
com.wily.introscope.agentProfile
Make the Agent profile (IntroscopeAgent.profile) available in a resource on the classpath. Set com.wily.introscope.agentResource to specify the path to the Resource containing the Agent profile.
Page 165
Property
introscope.agent.enterprisemanager.transp ort.tcp.host.DEFAULT
Note: This property name should be on one line. Note: The DEFAULT segment of the two settings above is used in configuring Agent Failover. For information on Agent Failover, see Agent Failover, page 173.
introscope.agent.agentName Enter a name for the application server the Agent is monitoring. The Agent Name value MUST start with an alphabetical character, and cannot contain a % character. If an Agent is not named in the Agent profile, the default name is Unknown Agent. introscope.agent.customProcessName Enter name for process being monitored.
Page 166
Switching Back to Your Non-Introscope-enabled Code If only part of the applications code was Introscope-enabled, in the classpath, you could place the Introscope-enabled code paths before the original-code paths (prepend). If you do this, Introscope-enabled code load and reports performance data. NonIntroscope-enabled code still loads and works normally, but does not report performance data. Place Introscope-enabled code in original classpath. Use this method when classpaths are set in many places, or to conduct an evaluation. Be careful of using this method in a production environment, as with this method it is easy to forget whether you are using the original or the Introscope-enabled code. Move the original code to a new location. Leave the classpaths unchanged. Then move the Introscope-enabled code to the original location. On a UNIX machine, you could also create a symbolic link from the current location of the Introscope-enabled code to the original location.
Page 167
Page 168
in past Introscope versions. Use this option if you already have an Agent profile for every application. The following sections describe how to configure each of the Agent naming options.
On the Java command line, specify an Agent name using the following Java system property:
Page 169
com.wily.introscope.agent.agentName
introscope.agent.agentNameSystemPropertyKey Note: If the Java system property specified here doesnt exist, this property will be
ignored. 3. Restart the application server.
Page 170
Agent Naming Options When the Agent locates naming information, Introscope edits the information to make the Agent name compliant with Introscope Agent naming rules. Agent names on supported application servers are comprised of several pieces of information, which differ per application server. For WebLogic, the Agent name is comprised of: Domain (data center) + cluster + instance (of WLS) For WebSphere, the Agent name is comprised of: cell (domain) + process (instance of WAS) When information is obtained, segments are separated by forward slashes, as in the following example:
medrec/MyCluster/MedRecServer
If there are any forward slashes within the segment names, they will be converted to underscores. For example, if a Domain is named Petstore/West, it will be converted to Petstore_West.
Note: If the renamed Agent had data being saved to a flatfile or database, there will be
no automatic correlation of data between the old and renamed Agents. See the section, Advanced Automatic Naming Options, page 172, for information on configuring Automatic Agent Naming properties for Enterprise Manager connection delay, and rename checking interval time. Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 171
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds
Page 172
Agent Failover
Agent Failover
Agent Failover allows you to define a list of Enterprise Managers for the Agent to connect to if the Agent cant connect to its default Enterprise Manager, or if the connection is lost. If the Agent cannot connect to its default Enterprise Manager, it will cycle through the Enterprise Managers in the order defined in the connection order property, attempting to connect. If it goes through the list without connecting to an Enterprise Manager, it will wait 10 seconds before cycling through the list again. Configuring Agent Failover consists of specifying: Enterprise Manager locations and names Enterprise Manager connection order
introscope.agent.enterprisemanager.tcp.host and
Page 173
Agent Failover
as seen here:
4.
introscope.agent.enterprisemanager.connectionorder=<EM1>,<EM2>,<...> Note: The first Enterprise Manager defined in this list is considered the primary
Enterprise Manager. For example, using the Enterprise Manager list shown in the previous step, the connection order could look like this:
introscope.agent.enterprisemanager.connectionorder=MainEM,BackupEM1, BackupEM2
7. Configure Configuring Automatic Agent Failback to Primary Enterprise Manager, if desired, or save your changes and restart the application.
Page 174
introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds.
3. 4. 5. By default, the reconnect attempt interval is 120 seconds. Change if desired. Save your changes. Restart the application.
Page 175
Multiple Agent Options 3. In the introscope.autoprobe.directivesFile property, enter the name of the appropriate <appserver>-typical.pbl file. For example, if using WebLogic, you the property may look like the following example:
introscope.autoprobe.directivesFile=weblogic-typical.pbl
4. Restart the managed application.
Scenario
If you have four Agents, all named AgentX, the Enterprise Manager may name them AgentX, AgentX%475, AgentX%476 and AgentX%477. If for some reason AgentX%475 disconnects, when it comes back, it will be renamed another random number, such as AgentX%845. With the Agent cloning property turned on, in this same situation, the Agents in this example would be named AgentX-1, AgentX-2, AgentX-3 and AgentX-4. If Agents AgentX-2 and AgentX-3 disconnected, and another Agent with the same name (AgentX) came back on, it would be given the name AgentX-2. With this naming, you will never have more Agent names in the database than the number of Agents originally cloned. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 176
introscope.agent.clonedAgent=true
3. Restart your managed application.
<AgentName>%<randomNumber1>
This uniquely generated name is only used while the Agent is connected. Subsequent reconnects will generate yet another unique name. As you can see, this situation could make it difficult to track that Agent when doing queries.
Page 177
Agent Logging Options 1. AutoProbe looks for any custom directives files in the directory that contains the For ease of use, you can place custom directives files (.pbds and/or .pbls) in the <appserver home>/wily directory. 2.
In the file, wily/IntroscopeAgent.profile, modify the property, introscope.autoprobe.directivesFile, to include the names of any new directives files, separated by commas. In the following example, a directives file named acme.pbd has been added:
introscope.autoprobe.directivesFile=default.pbl,acme.pbd Note: Do not remove any ProbeBuilder list files (.pbl) already listed in the property.
For more information on creating and modifying ProbeBuilder Directive files, see the chapter, ProbeBuilder Directives, page 212.
define the following system property on the Java command line with the -D option:
com.wily.probebuilder.removeLineNumbers=true
Page 178
AutoProbe20040416-175024.log
Once the Agent name becomes available, the logfile will be renamed, as in:
AutoProbeDOM1_ACME42.log
You can disable this automatic log naming. See Advanced Automatic Naming Options, page 172.
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
3. Save changes.
Page 179
Platform Monitors For example, if you wanted the Agent to report in verbose mode to a logfile, the property would look like this:
log4j.logger.IntroscopeAgent=VERBOSE#com.wily.util.feedback.Log4 JSeverityLevel,logfile
3. If desired, change the name and/or location of the Introscope Agent logfile in the property, log4j.appender.logfile.File.
Platform Monitors
Platform monitors enable the Agent to report platform Metrics, including CPU statistics, to the Enterprise Manager. Operating systems that Introscope can monitor are: Solaris Windows Server 2003 Windows 2000 Professional/Server/Advanced Server/Datacenter Server Windows XP Professional AIX Red Hat Enterprise Linux 2.1 RedHat Enterprise Linux 3.0 The platform Metrics generated are: ProcessID Processor Count - the number of CPUs Utilization % (process) - for the Agent process, what percentage of total capacity of all processors this process is using. No matter how many processors there are, this Metric generates only one number. Utilization % (aggregate) - for this processor, its total utilization (as a percentage) by all processes in the system. Each processor is shown as a Resource in the Explorer tree. For example, in the following screenshot, statistics are being shown for two processors:
Page 180
Platform Monitors Platform monitors are included with the Introscope Agent installers.
Note: Restart your machine to ensure the patches have taken effect.
Solaris Windows
Server 2003 all Windows 2000 platforms XP Professional
Page 181
Page 182
JMX Filters For Obtaining Advanced Performance Data Introscope only polls the RuntimeServiceMBean, because it's the only one that supports local access (an efficiency issue), and it contains most of the data we expect to be relevant.
<Domain>|<Host>|<Process>|<Agent>|JMX|
There are two methods Introscope uses to convert JMX MBean information to Introscope Metrics: primary keys method default method
introscope.agent.jmx.primarykeys property.
The following example shows the syntax used for the primary keys conversion method:
<Domain>|<Host>|<Process>|<Agent>|JMX|<domain name>|<value1>|<value2>:<metric>
Page 183
JMX Filters For Obtaining Advanced Performance Data For example, if an MBean has the following attributes: Domain name
WebLogic
Key/Value Pairs
category=server, type=jdbc
Metric Names
connections
introscope.agent.jmx.primarykeys=type,category
The MBean attributes in the table above would be converted to the following Introscope Metric:
<Domain>|<Host>|<Process>|<Agent>|JMX|Weblogic|jdbc|server:connectio ns
<Domain>|<Host>|<Process>|<Agent>|JMX|<domain name>|<key1>=<value1>|<key2>=<value2>:<metric>
For example, if an MBean has the following attributes: Domain name
WebLogic
Key/Value Pairs
category=server, type=jdbc
Metric Names
connections
and the user didnt define any primary keys, the MBean attributes in the table above would be converted to the following Introscope Metric:
<Domain>|<Host>|<Process>|<Agent>|JMX|Weblogic|category=server|type= jdbc:connections
Note that the key/value pairs are displayed alphabetically in the Introscope Metric.
JMX Filters
Defining JMX filters determines what JMX MBean information will be collected and displayed in Introscope. If no filters are set, ALL JMX MBean information will be reported by the Agent to the Enterprise Manager, potentially creating a lot of system overhead.
Page 184
JMX Filters For Obtaining Advanced Performance Data Filters are set in the introscope.agent.jmx.name.filter property in the Agent profile file, IntroscopeAgent.profile. Filters are keywords, entered as comma-separated strings in the property. Introscope tries to match the filter strings in JMX-generated Introscope Metrics. If it finds a match, the Metrics that contain the strings will be reported to Introscope.
properties:
Under the JMX Configuration heading, make sure the properrty, introscope.agent.jmx.enable, is uncommented and has a value of true. For WebSphere 6.0, uncomment the following property lines:
Page 185
<Domain>|<Host>|<Process>|<Agent>|JMX
The screenshot below shows an example of JMX Metrics in the Explorer tree.
Page 187
WebLogic Diagnostic Framework Data WLDF is a new feature in WebLogic 9.0. In previous releases of WebLogic Server, access to diagnostic data by monitoring agentswhich were developed by customers or thirdparty tools vendorswas limited to JMX attributes, and changes to monitoring agents required server shutdown and restart. However, WLDF enables dynamic access to server data through standard interfaces, and the volume of data accessed at any given time can be modified without shutting down and restarting the server. For more information on WLDF, see http://e-docs.bea.com/wls/docs90/wldf_configuring/ index.html.
Metric Conversion
Introscope WLDF Metric conversion is similar to that in JMX metric conversion. Where JMX MBeans have multiple Attributes (metrics), WLDF has a set of Data Accessors, each with multiple Columns (metrics). Introscope converts WLDF Columns to Introscope Metrics. Information in Data Accessors is defined by a domain name and one or more key/value pairs. Introscope converts this WLDF information into Introscope-specific Metric format and displays it in the Explorer under the following Resource:
<Domain>|<Host>|<Process>|<Agent>|WLDF|
Introscope converts Data Accessor Columns using the following method: key and value information is displayed key/value pairs are placed in alphabetical order in the Introscope-generated Metrics. The following example shows the syntax used:
<Domain>|<Host>|<Process>|<Agent>|WLDF|<domain name>|<key1>=<value1>|<key2>=<value2>:<metric>
For example, this table shows the information for the BYTECOUNT Column from the HTTPAccessLog Data Accessor:
Domain name
WebLogic
Key/Value Pairs
Name=HTTPAccessLog, Type=WLDFDataAccessRuntime=Accessor, WLDFRuntime=WLDFRuntime
Metric Names
BYTECOUNT
The Data Accessor information in the table above would be converted to the following Introscope Metric:
<Domain>|<Host>|<Process>|<Agent>|WLDF|Weblogic|Name=HTTPAccessLog |Type=WLDFDataAccessRuntime=Accessor|WLDFRuntime=WLDFRuntime:BYTECOUNT
Note that the key/value pairs are displayed alphabetically in the Introscope Metric.
Page 188
// permissions for Introscope PMI support grant codeBase "file:${was.install.root}/-" { permission java.security.AllPermission; };
Page 189
Advanced WebSphere Performance Data 1. 2. 3. Open the WebSphere Administrative Console. Select the server you'd like to configure. Click the Services tab.
Page 190
Advanced WebSphere Performance Data 4. Select Performance Monitoring Settings in the list, then click Edit Properties.
5. 6.
Check the checkbox for Enable performance counter monitoring. The Counter Settings section will become available. Click a category under the Performance tree, and click a radio button to select a monitoring level.
Note: A "low" level usually collects just enough data without creating a lot of system
overhead. 7. 8. 9. Repeat to set monitoring levels for each desired Metric category. Click OK. On the Services Tab, click Apply.
10. To enable PMI information, you will also need to configure a Custom Service in WebSphere. See Configuring a Custom Service in WebSphere, page 116.
Page 191
Advanced WebSphere Performance Data 3. 4. Locate the property, introscope.agent.pmi.enable, under the WebSphere PMI Configurations heading, and enter a value of true. Introscope can report data from the following high-level PMI Metric categories. These categories are represented by commented-out properties under the WebSphere PMI Configuration heading. Three of the categoriesconnectionPool, threadPool, and servletSessionsare set to true by default. WebSphere 5.0.x PMI Categories
introscope.agent.pmi.enable.threadPool=true introscope.agent.pmi.enable.servletSessions=true introscope.agent.pmi.enable.connectionPool=true introscope.agent.pmi.enable.bean=false introscope.agent.pmi.enable.transaction=false introscope.agent.pmi.enable.webApp=false introscope.agent.pmi.enable.jvmRuntime=false introscope.agent.pmi.enable.jvmpi=false introscope.agent.pmi.enable.system=false introscope.agent.pmi.enable.cache=false introscope.agent.pmi.enable.orbPerf=false introscope.agent.pmi.enable.j2c=false introscope.agent.pmi.enable.webServices=false introscope.agent.pmi.enable.wlm=false
5.
For each high level Metric category you want to report, enter a value of true.
Note: Do not enable the j2c module. Certain metrics in this module cause the
Enterprise Manager to run out of memory. 6. 7. Save the changes. Restart the managed application.
<Domain>|<Host>|<Process>|<Agent>|WebSpherePMI
Page 192
Enterprise Manager Database Recording The following screenshot shows an example of WebSphere PMI Metrics in the Explorer tree.
constantly captures Introscope data. A database is not required if you only want to view historical data. SmartStor can be used concurrently with Persistent Collections (either sent to a flatfile or a database), as its data collection is unrelated to any external data store.
Page 193
Run the database script for your database from those in the <Introscope home>/ examples/database directory. Oracle: oracle.sql Sybase: sybase.sql DB2: db2.sql DB2 on z/OS (OS/390): db2_zOS.sql
Note: DB2: If you run the DB2 script through the DB2 Command Center, make
sure the statement termination character is set to semicolon. generic: generic.sql Generic scripts can be used as a template to create a database creation script for your specific database version, if you are not using Oracle, DB2, or Sybase.
Note: While a generic script provides all necessary database schema, you may
need to make specific script syntax modifications to make it run on your particular database. Please contact your Wily sales representative for more assistance.
Page 194
IntroscopeEnterpriseManager.properties.
In the Database Settings section, set these variables to correspond with any variables required to access your database: Database URL Database driver Database user name and password Configurations will differ slightly depending on your database type. The following table shows configuration examples for Oracle, DB2, Sybase and Microsoft Access for the database properties in the IntroscopeEnterpriseManager.properties file: TABLE 6. Database Properties in IntroscopeEnterpriseManager.properties file Database Type
Oracle with Oracle driver
Sample Configurations
introscope.enterprisemanager.db.driver=oracle.jdbc.driver.OracleDriver introscope.enterprisemanager.db.url=jdbc:oracle:thin:@myDB:PortID:SID introscope.enterprisemanager.db.username=myUser introscope.enterprisemanager.db.password=myPassword introscope.enterprisemanager.db.driver=com.sybase.jdbc2.jdbc.SybDriver introscope.enterprisemanager.db.url=jdbc:sybase:Tds:myHost:PortID/database introscope.enterprisemanager.db.username=myUser introscope.enterprisemanager.db.password=myPassword
Sybase
Microsoft Access
4. 5.
Remove the pound signs at the start of these four lines (URL, driver, user ID, password), so that these commented-out properties become active. Save changes.
Page 195
Database Type
Oracle with Oracle driver Sybase DB2
Sample Configurations
C:\\oracle\\ora81\\jdbc\\lib\\classes12.zip C:\\sybase\\jConnect-5_5\\classes\\jconn2.jar /sw/opt/IBMdb2/V7.1/java12/db2java.zip
For Enterprise Managers configured as Windows Services, open the EMService.conf file. Under the Wrapper Properties heading, section, add or comment in the following line to the Java classpath properties:
wrapper.java.classpath.5=C:\classes12.zip Note: The value of this property is the location of your database driver. You do not
need to escape the backslashes. 8. 9. Save changes. Restart the Enterprise Manager for the changes to take effect.
The Enterprise Manager can record historical data to an external target (either a database or flat file). In order to specify data to be sent to an external data store, set up Persistent Collections as described in the section, Sending Introscope Data to External Data Store With Persistent Collections, in the chapter, Configuring Monitoring Logic, in the Introscope 6.0.1 Workstation Guide.
Note: Microsoft Access is not supported by Wily for use with the Enterprise Manager in a
production deployment. The sample Microsoft Access database is provided for demonstration and training purposes only.
To use the sample Microsoft Access database, you must set it up as an ODBC DSN to make it available to Suns JDBC ODBC bridge. On Windows 2000, use Start > Settings > Control Panel > Administrative Tools > Data Sources (ODBC). Name the data source WILY01.
Page 196
Command
iscopedebugpolling [true | false] [delay in seconds] iscopehelp iscopeshutdown
Result
Periodically reports debugging information to the log Display help screen Shuts down the Enterprise Manager
<name>.YYYYMMDD-HH.zip
For example, if a file named AcmeWestdata was saved on April 30, 2004, at 7:00 a.m., the flat file would look like the following example:
AcmeWestdata.20040430-07.zip
if the archive filename already exists (for example, if the size boundary was already reached that day), Introscope will append a number to the filename (starting with 2) until it finds an unused one:
<name>.YYYYMMDD-HH.#.zip
Page 197
IntroscopeEnterpriseManager.properties.
Under the Flat File Recording heading, uncomment the property,
introscope.enterprisemanager.flatfile.maxTimeInHours.
The default value is 24 (hours). Edit the value to the desired number of hours between flat file archiving. Save changes to the file and restart the Enterprise Manager. manually archive in-progress flat files, to avoid out of order data, or data outside of the expected time range.
Note: If you change the system clock, or adjust the duration of archiving, you should
Page 198
Workstation Options
IntroscopeEnterpriseManager.properties.
Under the Database Settings section, set the qualifier provided by your DBA. The following are some examples: If using Oracle:
introscope.enterprisemanager.db.tablequalifier=wilyuser.
If using DB2 or Sybase:
introscope.enterprisemanager.db.tablequalifier=wilydb.wilyuser. Note: You must enter a trailing table qualifier separator after the specified table
qualifier (in the above examples, the separator is a period). Contact your DBA for the proper separator.
5. 6.
Workstation Options
Workstation Logging Options
The following sections describe Workstation logging options.
Optional ProbeBuilder Configurations 2. In the property, log4j.logger.Workstation, replace INFO with the following:
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
3. Save changes.
logfile.
For example, if you wanted the Workstation to report in verbose mode to a logfile, the property would look like this:
log4j.logger.Workstation=VERBOSE#com.wily.util.feedback.Log4JSev erityLevel,logfile
3. 4. If desired, change the name and/or location of the Workstation logfile in the property,
log4j.appender.logfile.File.
Save changes.
introscope.enterprisemanager.workstation.disableSecureConnection property to true. However, if you disable the secure port, usernames and passwords will
be sent unencrypted over the network.
Miscellaneous Installation Options 1. 2. 3. Compile classes. Run the ProbeBuilder. Perform qualification tests.
This ensures that all qualification need only be done once on the Introscope-enabled code. In automated build environments, invoke the Command Line ProbeBuilder in sequence with other steps to Introscope-enable the proper classes and place the Introscopeenabled classes in the appropriate place.
ProbeBuilder Log
The ProbeBuilder creates a log file that contains ProbeBuilder Directives used and Probes added to the Java Application. The location of the ProbeBuilder log file is determined by where you specify Java classes with the ProbeBuilder Wizard or the with the Command-Line ProbeBuilder. For a directory, the log file is located inside the destination directory. For a file, the log file is located next to the destination file. The ProbeBuilder log file is called:
<original-directory-or-original-file>.probebuilder.log
<original-directory> or <original-file> is the Java class location that you specify with the ProbeBuilder Wizard or with the Command-Line ProbeBuilder. Only the most recent log is kept. Any prior log file is overwritten.
introscope.autoprobe.logfile=AutoProbe.log
The default value is AutoProbe.log.
Page 201
examples/database.
Page 202
Page 203
Database Tables
Database Tables
This document describes the underlying format used for database recording. The version table maps a database schema version (not to be confused with an Introscope version) to the corresponding index table. The index table for a specific schema version maps logical names for the schema version into the actual names of the tables in the database. Each table has a unique index created for the fields listed in bold. The view, WT_METRIC_VIEW, should always be used when accessing Metric data from the database. Wily makes every effort to maintain the view with each release. The raw tables are more likely to change between releases and should not be used directly for accessing Metric data.
Version Table
The name for the version table is WT_VERSIONLIST. The version table has two columns: SCHEMA_VERSION (INTEGER) INDEX_NAME (VARCHAR) For each schema version there is an entry mapping the version number to the name of the index table for that schema version. You may want multiple schemas to support compatibility between Introscope versions.
Index Table
The default name for the index table is WT_INDEX. The index table has two columns: LOGICAL_NAME (VARCHAR) ACTUAL_NAME (VARCHAR) The primary purpose of the index table is to map logical names to the actual table names used in the database. The logical names and the default actual names for this schema version are shown in the following table.
Logical Name
propertytable agenttable resourcetable metricnametable metrictable resourcemetrictable
Page 204
Database Tables
Logical Name
recordtypetable metadatatable tempquerytable_1 tempquerytable_2 tempquerytable_3 tempquerytable_4 tempquerytable_5
Property Table
The default name for the property table is WT_ PROPERTY. The property table has two columns: PROPERTY_NAME (VARCHAR) PROPERTY_VALUE (VARCHAR) The property table is a mapping of assorted name-value pairs which we wish to keep persistent in the database. Current entries in the properties table include: varchar limits for each of the above tables with variable length string fields generated unique Agent IDs when non-unique Fully-Qualified Agent names are encountered whether the database supports large integer values
Agent Table
The default name for the Agent table is WT_AGENT. The Agent table has the following columns: AGENT_ID (INTEGER) HOST (VARCHAR) PROCESS (VARCHAR) FIRST_METRIC_TS (TIMESTAMP) LAST_METRIC_TS (TIMESTAMP) AGENT_NAME (VARCHAR) DOMAIN_NAME (VARCHAR) The Agent table maps each distinct Domain, host, process and Agent name combination to a unique ID. The Agent Name is the name given by a user for a Fully-Qualified Agent. Several Agent IDs may be associated with a single Agent Name.
Page 205
Database Tables
Resource Table
The default name for the resource table is WT_RESOURCE. The resource table has three columns: RESOURCE_ID (INTEGER) SEGMENT_INDEX (INTEGER) SEGMENT_TEXT (VARCHAR) The resource table maps the variable length segments of the Metric into a list, one segment per entry. All entries with the same resource ID can be combined (ordered by segment index) to generate the associated variable length resource.
Metadata Table
The default name for the metadata table is WT_METADATA. The metadata table has three columns: AGENT_ID (INTEGER) RESOURCE_ID (INTEGER) METRIC_NAME_ID (INTEGER) The metadata table saves the Metric and Agent structure for Metrics whose values have been persisted to the value table.
Metric Table
The name for the Metric table is WT_METRIC. The Metric table has 24 columns: AGENT_ID (INTEGER) RESOURCE_ID (INTEGER) METRIC_NAME_ID (INTEGER) RESOURCE_METRIC_ID (INTEGER) RECORD_TYPE_ID (INTEGER) PERIOD (INTEGER) INTENDED_END_TS (TIMESTAMP) ACTUAL_START_TS (TIMESTAMP) Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 206
Database Tables ACTUAL_END_TS (TIMESTAMP) VALUE_COUNT (BIGINT) VALUE_TYPE (INTEGER) INTEGER_VALUE (BIGINT) INTEGER_MIN (BIGINT) INTEGER_MAX (BIGINT) FLOAT_VALUE (FLOAT) FLOAT_MIN (FLOAT) FLOAT_MAX (FLOAT) STRING_VALUE (VARCHAR) DATE_VALUE (TIMESTAMP) INTERVAL_COUNTER (INTEGER) SYS_VALUE_COUNT (VARCHAR) SYS_LONG_VALUE (VARCHAR) SYS_LONG_MIN (VARCHAR) SYS_LONG_MAX (VARCHAR) The Metric table contains the actual collected data. There is one record for every data point written to the database.
RESOURCE_METRIC_ID (INTEGER)
The Resource Metric ID references the associated record in the WT_RESOURCE_METRIC table.
RECORD_TYPE_ID (INTEGER)
The Record Type ID references the associated record in the WT_RECORD_TYPE table.
PERIOD (INTEGER)
The period is the interval at which this collection is recorded in seconds.
INTENDED_END_TS (TIMESTAMP)
The intended end timestamp is the master clock time at which this record was scheduled to be written.
Page 207
Database Tables The actual stop timestamp is when the collection actually stopped aggregating data points.
VALUE_COUNT (BIGINT)
The value count is the number of data points accumulated in the record only relevant for numeric data that can be accumulated. If the database does not support large integral values (large integral values refer to 8-byte signed integers), the count is stored in the SYS_VALUE_COUNT field. VALUE_TYPE (INTEGER) The value type is the actual underlying type of the data. Unlike the Metric type which encodes all the possible type information about a piece of data, the value type is one of six values: Integer = 1, Long = 2, Float = 3, Double = 4, String = 5, and Date = 6.
STRING_VALUE (VARCHAR)
The string value stores the actual data for string types.
DATE_VALUE (TIMESTAMP)
The date value stores the actual value for timestamps.
INTERVAL_COUNTER (INTEGER)
The interval counter assigns a unique ID to every record written in a given clock quantum.
Page 208
RESOURCE_METRIC (VARCHAR)
The resource Metric is the name of the Metric without the additional host|process|Agent information. The same string can be rebuilt from the resource and Metric name tables.
RECORD_TYPE (VARCHAR)
The record type is a simple representation of the type of the data point intended to simplify querying. For more information on record types, see Database Record Types, page 209.
MyDomain|MyHost|MyProcess|MyAgent|Servlets|MyServlet7|Average Response Time(ms) may be in the database and available to query based on the FullyIntroscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 209
Querying Introscope Database Tables Qualified Metric name as well as its parts. However, it is easier to query if there is a type like Servlet Average Response Time which can be used in query criteria. This would identify all servlets average response time records easily. Introscope comes with default database record types. You can set custom database record types in the file, <Introscope home>/config/ CustomDBRecordTypes.properties. Any record type mappings specified in this file take precedence over the defaults. For more information on custom datatypes, see LDAPAuthenticationExtension.properties, page 252.
AND
Records which hold average data have both the average and the number of values used to determine the average in the VALUE_COUNT column. This value is useful in order to weigh averages which combine Metric records. A simple average of INTEGER_VALUEs would not correctly account for the different number of values combined to calculate the average. An intermediate result of INTEGER_VALUE * VALUE_COUNT needs to be computed and added together. That sum needs to then be divided by the sum of the VALUE_COUNTs used to get the weighted average. The VALUE_COUNT on average data records can also be used to calculate rates more accurately (in floating point values) and in different units than responses/sec (like responses per hour). This can be accomplished by dividing the VALUE_COUNT by the difference between ACTUAL_START_TS and ACTUAL_END_TS. The SYS_* columns may be used in numeric calculations if the values can be converted to numbers.
Page 210
Creating Reports from Introscope Data Numeric data is stored as numbers in this release only in the INTEGER columns. Large integer values may or may not be stored in the INTEGER columns, depending on the capabilities of the database.
Introscope Reporting
Introscope provides built-in reporting capabilities, accessible directly from the Workstation. For more information on using these built-in reports, see the chapter, Introscope Reporting, in the Introscope 6.0.1 Workstation Guide.
Page 211
17 ProbeBuilder Directives
This chapter describes how to create and modify ProbeBuilder Directives. Information is provided in the following sections: Introduction to Directives Default ProbeBuilder Directives Files Modifying Default ProbeBuilder Directives Creating Custom Tracers Creating Advanced Custom Tracers Directive Keywords Updating Introscope With Modified or New ProbeBuilder Directives Files
Page 212
Introduction to Directives
Introduction to Directives
ProbeBuilder Directives tell the ProbeBuilder how to add Probes, such as timers and counters, to Java components, to create an Introscope-enabled application. Introscope includes a set of default Directives that are generic to many Java systems, as well as those that can extend support of default Tracers for WebLogic, WebSphere and SUN ONE. You can create your own custom Directives that track classes and methods unique to your application.
Components Tracked
By default, the ProbeBuilder supports tracking of the following: Oracle JDBC JSP Tag Libraries JSP IO Tag Libraries JSP DB Tag Tag Libraries Struts Servlets Java Server Pages (JSPs) Enterprise JavaBeans (EJBs) Java Database Connectivity (JDBC) Network Sockets Remote Method Invocation (RMI) Extensible Markup Language (XML) Java Transaction API (JTA) Java Naming and Directory Interface (JNDI) Java Message Service (JMS) Common Object Request Broker Architecture (CORBA) User Datagram Protocol (UDP) File Systems Threads System Logs Thrown and Caught Exceptions (off by default)
Page 213
Default ProbeBuilder Directives Files By default, Introscope traces many common Java and J2EE components using Tracer Groups. A Tracer group consists of a set of Tracers that is applied to a set of classes. For example, there are Tracer Groups which report the response times and rates for all RMI classes. You can turn Tracer Groups on or off, and/or add new classes to the set affected by the Tracer Group. See the section, Modifying Default ProbeBuilder Directives, page 215.
Page 214
Note: For instructions on switching between full and typical .PBL files, see Switching
Between Full and Typical Tracing Options, page 175.
Page 215
Modifying Default ProbeBuilder Directives The following table lists the default Tracer groups, and shows which are turned on in the full and typical toggles files. TABLE 8. Default Tracer Groups in Full and Typical Sets Default Full Setting
on on on on on on on on on on on on on on on on
Name
CorbaTracing EntityBeanTracing SessionBeanTracing MessageDrivenBeanTracing J2eeConnectorTracing JavaMailTransportTracing JDBCQueryTracing JDBCUpdateTracing JMSListenerTracing JMSConsumerTracing JMSPublisherTracing JMSSenderTracing JSPTracing RMIClientTracing RMIServerTracing HTTPServletTracing
Definition
CORBA method invocations Entity EJB method invocations Session EJB method invocations Message-driven EJB method invocations J2EE connector information Mail sending times JDBC queries JDBC updates JMS message processing times JMS message processing times JMS message broadcast times JMS message broadcast times JSP service responses RMI client method invocations RMI server method invocations HTTP servlet service responses
Note: If you are using Application Server AutoProbe, you will need to turn on the following Tracer group:
HTTPAppServerAutoProbeSer vletTracing StrutsTracing InstanceCounts Execution times of actions in the Struts framework Counts number of instances of object type identified with Tracer group. File system bytes written and read on on on on
on
off
Page 216
JAXM message sends JNDI lookup times Jakarta DB Tags custom tag library for reading and writing from a SQL database Jakarta IO custom tag library for a variety of input and output tasks Commit times using JTA EJB activity at method level Network socket bandwidth Network socket bandwidth Captures standard out text Captures standard error text Number of active threads by class Time spent parsing XML document XML transformation time Processing time of custom JSP tags
on on on
JSPIOTagLibraryTracing
on
off
JTACommitTracing EJBMethodLevelTracing SocketTracing UDPTracing SystemOutTracing SystemErrorTracing ThreadTracing XMLSAXTracing XSLTTracing JSPTagLibraryTracing
off off off off off off off off off off
Tracer Groups report information only when turned on (uncommented). Tracer groups are activated with the keyword TurnOn.
Name
Default stalled method Tracers DefaultConcurrentInvocatio nTracing Previous rate Metrics
Definition
Stalled method tracing Concurrent invocation information Metric information by rate (not interval count)
Page 217
2.
TurnOn: HTTPServletTracing Note: Any uncommented (turned on) directive for a Tracer group causes the Tracer
group to be used.
To turn a Tracer group off, change the line into a comment by placing a pound sign at the beginning of the line, as in the following example:
#TurnOn: HTTPServletTracing
Other examples of default Directives:
Exceptions
The following directives are used to turn on tracing of exceptions either where thrown or caught. They can cause performance degradation so they are not turned on by default. To turn either of these on, uncomment the appropriate line:
Page 218
Agent Initialization
The Agent Initialization instrument point directive does not cause additional overhead and is turned on by default in both full and typical PBD sets.
#InstrumentPoint: AgentInitialization
If multiple ProbeBuilder Directive files are used, any settings (such as Tracer Groups, Skips, InstrumentPoints, Custom Method Tracers) turned on in any file take effect.
Page 219
mySessionEJB implements javax.ejb.SessionBean mySessionEJBsubclass1 extends mySessionEJB mySessionEJBsubclass1a extendsmySessionEJBsubclass1 mySessionEJBsubclass1b extendsmySessionEJBsubclass1 mySessionEJBsubclass2 extends mySessionEJB
The Tracer group, SessionBeanTracing, causes the tracking of mySessionEJB: The following Tracer traces mySessionEJBsubclass1 and mySessionEJBsubclass2. IdentifyInheritedAs: mySessionEJB SessionBeanTracing The following Tracer traces mySessionEJBsubclass1a and mySessionEJBsubclass1b. IdentifyInheritedAs: mySessionEJBsubclass1 SessionBeanTracing
Note: This example does not use packages. If your code is in a package, it needs to
include the package name with the class name. See Directive Keywords, page 227.
Note: Only concrete, implemented methods can be traced and report Metric data while
running. An abstract method specified in a custom Tracer results in no Metric data being reported.
You must use a specific syntax when constructing Custom Tracers, or Introscope will not be able to recognize and process your Tracers, and wont collect the desired information. This syntax is described in the next section.
Page 220
Tracer Syntax
A Tracer is composed of a directive and information about the method or class to trace, in the following format:
<class>
<method>
<Tracer-name>
<metric-name>
The following table describes tracer names and what they trace. TABLE 10. Tracer Names Tracer Name MethodTimer What It Traces
Average method execution time in milliseconds and reports it under <metric-name> in the Metrics tree Average method execution time in milliseconds and also collects information about runtime interactions between components
BlamedMethodTimer
Page 221
Average CPU time (in milliseconds) used during method execution and reports it under <metricname> in the Metrics tree.
MethodCPUTimer
the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0).
Average CPU time (in milliseconds) used during method execution and also collects information about runtime interactions between components.
BlamedMethodCPUTimer
the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0).
PerIntervalCounter
Number of invocations per interval. This interval will change based on the view period of the consumer of the data (for example, the Preview pane in the Explorer, and the Persistent Collection that records it to a database). It is reported under <metric-name> in the Explorer tree. Number of invocations per second. An example use of this would be logins per second when tracing a method that represents a user logging into the system. It is reported under <metric-name> in the Explorer tree. Traces the same thing as MethodRateTracer and also collects information about runtime interactions between components Adds (or subtracts, respectively) one to the value of a counter specified by <metric-name> every time the Metric is traced. These two Metrics can be combined to trace complex Metrics like number of connected users, when one method is called to create a new user session, and a second method is called to end a user session. Traces the same thing as MethodTraceIncrementor and MethodTraceDecrementor, with the addition of information about runtime interactions between components. Reports as a count the number of times a method has started but not yet finished. The result is reported under <metric-name> in the Explorer tree. An example use of this Tracer would be counting the number of simultaneous database queries
MethodRateTracer
BlamedMethodRateTracer
ConcurrentInvocationCounter
Page 222
TraceOneMethodOfClass: com.sun.petstore.account.LoginEJB login MethodTraceIncrementor "Petstore|Account:Logged In Users" TraceOneMethodOfClass: com.sun.petstore.account.LogoutEJB logout MethodTraceDecrementor "Petstore|Account:Logged In Users"
Page 223
Page 224
Keyword-Based Substitution
Keyword-based substitution allows runtime substitution of values into the Metric name. The parameters in the Metric name in the Tracer are substituted at runtime for the actual values into the Metric name. This feature can be used with any directive. TABLE 11. Keyword-based Substitution Parameters Parameter
{method} {classname} {packagename} {packageandclassname}
Runtime Substitution
Name of the method being traced Runtime class name of the class being traced Runtime package name of the class being traced Runtime package and class name of the class being traced
Note: If Introscope processes a class which does not have a package, it will replace
{packagename} with the string <Unnamed Package>.
Example 1:
If the Metric name for a Tracer in the pbd file is:
Page 225
Creating Advanced Custom Tracers and the Tracer is applied to method myMethod with a runtime class of myClass that is in package myPackage, the resulting Metric name would be:
Example 2:
If a Tracer with a Metric name in the .pbd file of
"myPackage.myClass|myMethod:Response Time(ms)" Note: Note the . between the package and class instead of the | in the first example.
Metric-Name-Based Parameters
You can create a single-method Tracer that creates a Metric name based on parameters passed to a method using the TraceOneMethodWithParametersOfClass keyword. TraceOneMethodWithParametersOfClass: <class-name> <method> <trace-classshorthand-name> <name> Parameters can be used in the Metric name. This is accomplished by substituting the value of parameters for placeholder strings in the Metric name. The placeholder strings to use are {#} where # is the index of the parameter to substitute. The indices start counting at zero. Any number of parameter substitutions can be used in any order. All parameters are converted to strings before substitution into the Metric name. Object parameters other than strings should be used with caution because they are converted using the toString() method. If you are unclear about what string the parameter will be converted to, you should refrain from using it in the Metric name.
Example:
A Web site uses a class named order, with a method named process. The method has parameters for different kinds of orders, either book or music. You can create a Tracer like this:
Page 226
Directive Keywords
Skips
Certain packages and classes can be skipped by AutoProbe or ProbeBuilder by listing each package or class to skip after SkipPackage: or SkipClass: as appropriate. By default, Introscope Agent and fundamental Java classes and packages are skipped by AutoProbe or ProbeBuilder. For more information, see Directive Keywords, page 227.
TraceOneMethodOfClass user login MethodTraceIncrementor Logged-in Users TraceOneMethodOfClass user logout MethodTraceDecrementor Logged-in Users
This increments the Metric Logged-in Users when someone logs in and decrements Logged-in Users when someone logs out.
Directive Keywords
This section contains a list of Introscope Directive keywords. Specifics for using these keywords with arguments to create Directives are described in this section. Two Tracers, StalledMethodTracer and ThresholdMethodTimer use their own keywords (see Threshold ProbeBuilder Action Keywords, page 230). The table below defines parameters used in the Directive keyword syntax. TABLE 12. Directive Parameters Parameter
<package-name> <class-name>
Value
Period-separated, fully-qualified package name, such as Period-separated, fully-qualified class name, such as
java.lang.
java.lang.Object.
Page 227
Directive Keywords
<Tracer-name>
Name of Tracer to use, one of the following in this list: MethodTimer BlamedMethodTimer PerIntervalCounter MethodRateTracer BlamedMethodRateTracer MethodTraceIncrementor BlamedMethodTraceIncrementor MethodTraceDecrementor BlamedMethodTraceDecrementor ConcurrentInvocationCounter
Main([Ljava/lang/String;)V).
Main or
Valid Metric name or Resource category depending on the specific Tracer class, such as Resource|Sub-resource. Name of Tracer group to use.
Page 228
Directive Keywords Track all exceptions at the location where they are thrown. High performance impact, turned off by default. CatchException Track all exceptions at the location where they are caught. High performance impact, turned off by default. TraceAllMethodsIfInherits: <class-name> <Tracer-name> <name> Traces all methods in direct subclasses or implementers of the named interface with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. The result is a single aggregate Metric for all methods traced. To get detail results for particular methods, use one of the TraceOneMethod keywords. An abstract method specified in a Tracer results in no Metric data being reported. TraceAllMethodsOfClass: <class-name> <Tracer-name> <name> Traces all methods in the named class with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. The result is an aggregate Metric for all methods traced. To get detailed results for particular methods, use one of the TraceOneMethod keywords. An abstract method specified in a Tracer results in no Metric data being reported. TraceOneMethodOfClass: <class-name> <method> <Tracer-name> <name> Traces the specific method in the named class with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. An abstract method specified in a Tracer results in no Metric data being reported. TraceOneMethodWithParametersIfInherits: <class-name> <method> <Tracername> <name> Traces the specific method in direct subclasses or implementers of the named superclass or interface with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. An abstract method specified in a Tracer results in no Metric data being reported. The specified method name must include a signature. The Metric name can include strings like {#} that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc).
Page 229
Directive Keywords TraceOneMethodWithParametersOfClass: <class-name> <method> <Tracername> <name> Traces the specific method in the named class with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. An abstract method specified in a Tracer results in no Metric data being reported. The specified method name must include a signature. The Metric name can include strings like {#} that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). TurnOn: <Tracer-group> Enables the specified Tracer group. There is no corresponding Directive to disable a Tracer group. To disable a Tracer group, comment out the associated TurnOn Directive.
Action Keywords
TraceOneMethodWithThresholdOfClass: <class-name> <method> <Tracer-name> <name> <threshold> Traces the specific method in the named class with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. An abstract method specified in a Tracer results in no Metric data being reported. TraceAllMethodsWithThresholdOfClass: <class-name> <Tracer-name> <name> <threshold> Traces all methods in the named class with the given Tracer class and Metric name. Only concrete, implemented methods are Introscope-enabled and report Metric data while running. The result is an aggregate Metric for all methods traced. To get detailed results for particular methods, use one of the TraceOneMethod keywords. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 230
Updating Introscope With Modified or New ProbeBuilder Directives Files An abstract method specified in a Tracer results in no Metric data being reported.
Keyword Syntax
The table below defines parameters used in the keyword syntax for these specific Directives. TABLE 13. Threshold Directives Parameters Parameter
<class-name> <Tracer-name>
Value
Period-separated, fully-qualified class name, such as
java.lang.Object.
Name of Tracer to use, one of the following in this list: StalledMethodTracer ThresholdMethodTimer <method> <name> <threshold> Method name with an optional descriptor, such as
Main([Ljava/lang/String;)V).
Main or
Valid Metric name or Resource category depending on the specific Tracer class, such as Resource|Sub-resource. Length of threshold in milliseconds
Threshold Tracers
StalledMethodTracer traces the number of invocations of method which have exceeded a user-defined threshold and have not finished. This number serves as an approximation of the number of hung threads. The result is reported in the Metrics tree using the fullyqualified Metric name specified in the directives file. If desired, users can set up Alerts on this Metric. Over and Under Threshold Counter Tracers: OverThresholdPerIntervalCounter, which traces the number of invocations greater than a user-defined threshold. UnderThresholdPerIntervalCounter, which traces the number of invocations equal to or less than a user-defined threshold. Each of these Tracers produces one Metric each, which is displayed in the Explorer tree. The fully-qualified Metric name is specified in the directives file.
Page 231
Using AutoProbe
1. AutoProbe looks for any custom directives files in the directory that contains the For ease of use, you can place custom directives files (.pbds and/or .pbls) in the <appserver home>/wily directory. 2.
In the file, wily/IntroscopeAgent.profile, modify the property, introscope.autoprobe.directivesFile, to include the names of any new directives files, separated by commas. In the following example, a directives file named petstore.pbd has been added:
introscope.autoprobe.directivesFile=default.pbl,petstore.pbd Note: Do not remove any ProbeBuilder list files (.pbl) already in the property.
2.
Using AutoProbe
1. Make changes to Directives files.
Page 232
Updating Introscope With Modified or New ProbeBuilder Directives Files 2. 3. Restart the managed application. If they are not already running, start the Enterprise Manager and the Workstation.
Page 233
Note: In these files, on Windows machines, when adding a path, you must escape a
backslash (\) with another backslash (each one doubled), such as
C:\\Introscope\\lib\\Agent.jar.
Information is provided in the following sections: Introscope Agent Settings File Introscope Enterprise Manager Settings Files Introscope Workstation Settings Files Introscope WebView Settings Files Database Settings Files Extensions Settings Files
Page 234
Directives Files
The introscope.autoprobe.directivesFile property specifies the Directives files that determine how AutoProbe places Probes. This is a required parameter. If the property is not specified or the values are invalid, Introscope cannot run. You can enter Directives files (extension .pbd), Directives list files (extension .pbl), and directories. Separate multiple entries with commas. Non-absolute names are resolved relative to the location of the IntroscopeAgent.profile file.
Note: These properties are optional. If the Agent name is not defined, it will be known as
UnknownAgent.
PMI Configuration
These settings turn on the Introscope PMI data collection, and define which PMI Metrics are collected in Introscope. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 235
Introscope Agent Settings File To enable PMI collection functionality, you must first turn on Performance Monitor Settings in WebSphere (see Turning on Performance Monitor Settings in WebSphere, page 189). For each high-level Metric category you want to collect PMI data for (eight for WebSphere 4.0, 15 for WebSphere 5.0.x), you must turn on the setting for that property (change setting to true).
JMX Support
These settings turn on JMX support, and define which JMX Metrics are collected in Introscope. JMX support will only work if the Agent is running on JDK1.2 or higher. The shipped JMX configuration in the IntroscopeAgent.profile file supports WebLogic 6.1 and higher, and WebSphere 5.0.x and higher.
LeakHunter Properties
These properties are used by the Agent to communicate with LeakHunter, an add-on product.
Specifies
When option is set to false, this option turns off the automatic insertion of Probes into the applications bytecode, it does not turn off the Agent or Agent reporting. Name and location of AutoProbe log file. Specifies Directives files for AutoProbe. For more information, see Directives Files. Amount of logging detail for the Introscope Agent log Specifies the name and location of Introscope Agent logfile Enables reporting of individual Socket's Input/Output Bandwidth rate Metrics
Default Setting
true
introscope.autoprobe.logfile introscope.autoprobe.directivesFile
Page 236
This Setting
introscope.agent.extensions.directory
Specifies
Specifies the location of all extensions to be loaded by the Introscope Agent. Non-absolute names are resolved relative to the location of this properties file The connection order of backup Enterprise Managers the Agent uses if it is disconnected from its default Enterprise Manager. Items in list must be comma-separated. The host name of machine running the Enterprise Manager. The port on the Enterprise Manager machine that listens for the Agent. Network timeout value in seconds when establishing Agent connection to Enterprise Manager Number of seconds between attempts by Agent to reconnect to primary Enterprise Manager. Name for process being monitored.
Default Setting
ext
introscope.agent.enterprisemanager.con nectionorder
DEFAULT
localhost 5001
60
Commented out; set to name of application server for applicationserver specific installers UnknownProcess; may vary by installer
introscope.agent.defaultProcessName
Default name for an Agent if introscope.Agent. customProcessName is not set and the name cannot be inferred from the main class of the application. Specifies which Java system property will contain Agent name. Specifies whether Agent Autonaming will be used to obtain Agent name for supported application servers. Requires Startup Class to be specified for WebLogic; requires Custom Service to be specified for WebSphere. Specifies the amount of time in seconds the Agent waits for naming information before connecting to the Enterprise Manager.
blank commented out and false in example IntroscopeAgent.profile ; uncommented and true in Agent profile shipped with supported application servers 120
introscope.agent.agentAutoNamingMaxi mumConnectionDelayInSeconds
Page 237
This Setting
introscope.agent.agentAutoRenamingInt ervalInMinutes
Specifies
Specifies the time interval in minutes during which the Agent will check to see if it has been renamed. Specifies whether to disable automatic naming of Agent log files when using AutoNaming options. Name of Agent If you are using the Agent profile provided with AutoProbe installer (for example, with WebLogic), the default Agent name will be same as app server (e.g., WebLogic Agent) for any other installation, default Agent name will be Unknown Agent for any installation, if specified name is invalid or property is deleted, Agent name will be Unknown Agent
Default Setting
10
false
For IntroscopeAgent.prof ile file included with default installer, commented out, and provided Agent name is Unknown Agent For IntroscopeAgen.profil e included with AutoProbe installer, provided Agent name is same as application server (e.g. WebLogic Agent) Commented out; And, if unspecified, is level 5. false true true true false false false false
introscope.agent.thread. all.priority introscope.agent.pmi.enable introscope.agent.pmi.enable.threadPool introscope.agent.pmi.enable.servletSessi ons introscope.agent.pmi.enable.connection Pool introscope.agent.pmi.enable.bean introscope.agent.pmi.enable.transaction introscope.agent.pmi.enable.webApp introscope.agent.pmi.enable.jvmRuntim e
Controls the priority of Agent threads. You can set this from 1 (low) to 10 (high). Enables collection of data from WebSphere PMI. Enables collection of PMI threadPool data. Enables collection of PMI servletSessions data. Enables collection of PMI connectionPool data. Enables collection of PMI bean data. Enables collection of PMI transaction data. Enables collection of PMI webApp data. Enables collection of PMI jvm Runtime data.
Page 238
This Setting
introscope.agent.pmi.enable.jvmpi
Specifies
Enables collection of PMI jvmpi data.
Default Setting
false
introscope.agent.pmi.enable.system
WebSphere 5.0.x only; enables collection of operating system-level data. WebSphere 5.0.x only; enables collection of data about the effectiveness of WebSphere caching layers. WebSphere 5.0.x only; enables collection of performance statistics about the embedded Object Request Broker (ORB). WebSphere 5.0.x only; enables collection of J2EE connector data. WebSphere 5.0.x only; enables collection of SOAP and web services data. WebSphere 5.0.x only, enables collection of Workload Management (WLM) data on load balancing and failover of WebSphere applications. Enables collection of JMX Metrics. User-defined order of MBean information, and simplifies name conversion.
false
introscope.agent.pmi.enable.cache
false
introscope.agent.pmi.enable.orbPerf
false
false false
false
introscope.agent.jmx.enable introscope.agent.jmx.name.primarykeys
false Commented out in default IntroscopeAgent.prof ile file For WebLogic: Type,Name For WebSphere:
Page 239
This Setting
introscope.agent.jmx.name.filter
Specifies
Filtered string(s), separated by commas
Default Setting
Commented out in default IntroscopeAgent.prof ile file For WebLogic: ActiveConnectionsCur rentCount,WaitingFor ConnectionCurrentCou nt,PendingRequestCur rentCount,ExecuteThr eadCurrentIdleCount, OpenSessionsCurrentC ount For Websphere: JSR77
Note: IntroscopeAgent.profile file installed with Agent for WebLogic has the following filters defined:
introscope.agent.jmx.name.jsr77.enable
Enables the retrieval of JMX Metrics for application servers which support the JSR77 specification. Controls which (if any) JMX MBean attributes are to be ignored. A comma-separated list of desired keywords. If an MBean attribute name matches one in this list then it will be ignored. Leave empty to include all MBean attributes. Unique name for cloned Agents Name of operating system to load a platform monitor for. Enables LeakHunter functionality. Location of LeakHunter.log file. Filename is relative to the application working directory.
Present only in WebSphere Agent Profile Commented out; true Present only in WebSphere Agent Profile Commented out; server
introscope.agent.jmx.ignore.attributes
introscope.agent.leakhunter.logfile.appe nd
Specifies whether to replace log file (value of false) or append existing log file (value of true) on application restart. Sensitivity of LeakHunter (higher sensitivity will report more collections as potential leaks). Must be integer value from 1-10.
false
introscope.agent.leakhunter.leakSensitivi ty
Page 240
This Setting
introscope.agent.leakhunter.timeoutInMi nutes
Specifies
Period (in minutes) during which Introscope LeakHunter looks for new potential leaks. Must be nonnegative integer. Value of zero means no timeout. Specifies whether to collect allocation stack trace information.
Default Setting
120 minutes
introscope.agent.leakhunter.collectAlloca tionStackTraces
false
HttpServletReque st.getRemoteUser
Commented out;
HttpServletReque st.getHeader
Commented out; supplied by user Commented out;
HttpServletReque st.getValue
Commented out; supplied by user Commented out; supplied by user Commented out; supplied by user Commented out; supplied by user
Page 241
Specifies
VM to use the next time the ProbeBuilder is started. Can be set to any installed JDK or JRE version 1.3. Standard Error Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file. Standard Input. Leave blank for no input, console to read from the console window, or any path to a file to read from that file. Standard Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file.
Default Setting
Varies by operating system
lax.stderr.redirect
blank
lax.stdin.redirect
blank
lax.stdout.redirect
blank
IntroscopeEnterpriseManager.properties File
Ports
Agent listener and Workstation ports can be set to any available TCP port on the machine. Firewalls may require that non-default ports be used.
Log 4J Settings
Two properties define the level of detail in the Enterprise Manager logs and the name and location of Enterprise Manager log files. See Log4J documentation at http://jakarta.apache.org/log4j/docs/documentation.html for information on advanced Log4J functionality.
SmartStor Properties
These properties define how often SmartStor will collect Introscope Metric data, and how long the data will remain before being aged out.
Page 242
Database Properties
Database settings in this file determine whether and how performance data from managed applications is stored in a relational database. These settings must be uncommented and correctly set up for the database and historical queries to work. Consult your JDBC driver documentation for specific information related to your driver. See the example in commented lines in the <Introscope home>/config/ IntroscopeEnterpriseManager.properties file itself. Database settings are: Fully-qualified class name of the JDBC driver that works with your database Databases URL Database username and password (for use by the JDBC driver). This database login must have permission to insert into and select from tables. For other specific database settings, see Table 16 on page 244. Include the JDBC driver classes (and license classes, if any) in the classpath, set in the file, Introscope_Enterprise_Manager.lax. (See Introscope Enterprise Manager.lax File, page 247.)
SNMP Collections
Two properties, introscope.enterprisemanager.snmp.enable and introscope.enterprisemanager.snmp.agent.port, enable and define SNMP Agent functionality.
WebView
Three properties define username, password, and whether WebView can establish a connection to the Enterprise Manager.
Page 243
Introscope Enterprise Manager Settings Files TABLE 16. File: <Introscope home>/config/ IntroscopeEnterpriseManager.properties This Setting introscope.enterprisemanager.agent. metrics.limit Specifies
Number of Metrics Agent will report before it is shut off.
Default Setting
50000
introscope.enterprisemanager.workst ation.disableSecureConnection
false
Enterprise Manager machine port that communicates with Agents Amount of logging detail for the Enterprise Manager log Name and location of Enterprise Manager logfile Number of minutes the Enterprise Manager continues to track an Agent after the Agent is disconnected, in case the disconnection is temporary. After this time runs out, the Enterprise Manager releases Agent tracking resources. Enables SmartStor data collection.
introscope.enterprisemanager. autoUnmountDelayInMinutes
introscope.enterprisemanager.smart stor.enable introscope.enterprisemanager.smart stor.directory introscope.enterprisemanager.smart stor.tier1.frequency introscope.enterprisemanager.smart stor.tier1.age introscope.enterprisemanager.smart stor.tier2.frequency
true
Page 244
This Setting
introscope.enterprisemanager.smart stor.tier2.age introscope.enterprisemanager.smart stor.tier3.frequency introscope.enterprisemanager.smart stor.tier3.age introscope.enterprisemanager.transa ctionevents.storage.dir introscope.enterprisemanagter.trans actionevents.storage.max.data.age introscope.enterprisemanager.db.dri ver introscope.enterprisemanager.db.url introscope.enterprisemanager.db.use rname introscope.enterprisemanager.db.pas sword introscope.enterprisemanager.db.tab lequalifier
Specifies
Specifies the number of days after which data in second tier ages out of SmartStor. Specifies the frequency (in seconds) of data collection for the third data tier. Specifies the number of days after which data in third tier ages out of SmartStor. Specifies where to store transaction event data. Specifies (in days) how long to store transaction event data. Name of your database driver Name of your database URL. User name required for database access Password required for database access Sets explicit table qualifier, for locating database tables in locations other than default locations associated with login. This qualifier will be prepended (or appended as appropriate) directly to the table name so be sure to include any separator required by the database. Number of seconds between reconnection attempts of an Enterprise Manager to a disconnected database. A value of zero means the Enterprise Manager wont try to reconnect. Enables batch insertion of Metric values into the database. Batch inserts are a JDBC 2.0 feature; if your JDBC driver supports them, enabling this property will increase the performance of value inserts significantly. Controls the size (in row insertion count) of batch inserts, if they are enabled. Number of seconds to wait for a query to complete before giving up. A value of zero means there is no timeout for queries. Only used if supported by both the database and JDBC driver.
Default Setting
7 300 7 traces 14 days Commented out Commented out Commented out Commented out Commented out
introscope.enterprisemanager.db.rec onnect.intervalInSeconds
30
introscope.enterprisemanager.db.use BatchInserts
Commented out
Page 245
This Setting
introscope.enterprisemanager.db.ma ximumTableCacheSize
Specifies
Sets size of internal caches used to improve performance. -1 lets caches grow as much as necessary and is recommended unless the limits of system memory are being reached. The value is number of cache entries per database table so it scales linearly with memory usage. Sets number of database connections to use for running database queries. A larger number of connections consumes more system resources but allows more simultaneous database queries. If number of connections is greater than 5, you must create additional temporary Introscope tables in your database. The number of temporary tables must be the same as the number of query connections.
Default Setting
Commented out
introscope.enterprisemanager.db.qu eryConnections
Commented out
introscope.enterprisemanager.flatfile .homedir
Specifies a directory into which Introscope can record traced data to comma separated value (.csv) flat files. For more information, see Flat File Properties. Maximum size of a flat file in megabytes, above which Introscope compresses about 95% to a .zip file. The default maximum size is 100 megabytes. Time in hours after which the flat file is archived.
<Introscope>/ flatfiles
introscope.enterprisemanager.flatfile .maxFileLength
100
Disables flatfile compression to lighten performance load. If true, will move flat files to archive directory and will name files with .full.csv suffix instead of .zip.
Disables interactive console (whether console accepts input).
introscope.enterprisemanager.disabl eInteractiveMode
true
Note: On many UNIX platforms, nohup will not work if the application is trying to read from standard input. Therefore, if you choose to run in nohup mode, ensure the value of this setting is set to true. You must also change the lax.stdin.redirect property in the Introscope Enterprise Manager.lax File to <blank>. If both of these properties are not set exactly as stated above, it can either render the application unable to start up in nohup, or cause maximum CPU utilization.
Page 246
This Setting
introscope.enterprisemanager.snmp. enable introscope.enterprisemanager.snmp. agent.port introscope.enterprisemanager.webvi ew.disableLogin introscope.enterprisemanager.webvi ew.password
Specifies
Enables SNMP Agent (only relevant if you have installed SNMPServices.jar) Enterprise Manager port that communicates with the SNMP Agent Determines whether WebView can establish a connection with Enterprise Manager. Specifies password WebView users to connect to Enterprise Manager
Default Setting
false 161 false WebView
The following four properties are duplicated for each authentication extension used. introscope.enterprisemanager.authe ntication.providers introscope.enterprisemanager.authe ntication.extensionName.<Extension Name> introscope.enterprisemanager.authe ntication.controlflag.<ExtensionNam e> introscope.enterprisemanager.authe ntication.configFile.<ExtensionName > Specifies which authentication extensions are used during login Specifies extension name <Extension type> <Extension name> <control flag value> <config-file information>
Specifies
The Java classpath necessary to run this application. Can be appended with a JDBC driver and license.
Default Setting
lib/ EnterpriseManager.jar:lib /SNMPAdapter.jar:lib/ IntroscopeServices.jar:la x. jar Varies by operating system -ms128m -mx512m console
lax.nl.current.vm
VM to use the next time the Enterprise Manager is started. Can be set to any installed JDK or JRE version 1.3. Initial minimum and maximum heap sizes Standard Error Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file.
Page 247
This Setting
lax.stdin.redirect
Specifies
Standard Input.
Default Setting
console
Caution: Do not change. Note: On many UNIX platforms, nohup will not work if the application is trying to read from standard input. If you choose to run in nohup mode, change this setting to <blank>. You must also ensure that the introscope.enterprisemanager.disabl eInteractiveMode=true property in the IntroscopeEnterpriseManager.properties File: is set to true. If both of these properties are not set exactly as stated above, it will either render the application unable to start up in nohup, or cause maximum CPU utilization.
lax.stdout.redirect Standard Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file. console
EMService.conf File
The EMService.conf file contains settings used when the Enterprise Manager is run as a Windows Service.
Note: Before configuring these properties, you must deregister the Enterprise Manager
Service. After configuring properties, re-register the Enterprise Manager Service. TABLE 18. <Introscope home>/EMService.conf This Setting
wrapper.java.initmemory wrapper.java.maxmemory wrapper.logfile wrapper.logfile.maxsize wrapper.ntservice.name wrapper.ntservice.displayname
Specifies
Wrappers initial memory size in megabytes Wrappers maximum memory size in megabytes Name and location of logfile Maximum logfile size Name of the service Display name of the service
Default Setting
128 512 ./logs/EMService.log 10 MB IScopeEM Introscope Enterprise Manager
Page 248
IntroscopeWorkstation.properties File
TABLE 19. File: <Introscope home>/config/IntroscopeWorkstation.properties This Setting
log4j.logger.Workstation log4j.appender.logfile.File
Specifies
Amount of logging detail for the Workstation log Name and location of Workstation logfile
Default Setting
INFO, console IntroscopeWorkstation.log
Specifies
What command line arguments will be passed to the main method. Can use this property to supply Workstation with login values, bypassing the Login screen when starting Workstation. VM to use the next time the Workstation is started. Can be set to any installed JDK or JRE version 1.3. Other option settings for JVM Initial minimum and maximum heap sizes.
Default Setting
$CMD_LINE_ARGUM ENTS$
lax.nl.current.vm
Varies by operating system -classic -ms64m mx256m The classic setting invokes Java 2 classic VM.
lax.nl.java.option. additional
lax.stderr.redirect
Standard Error Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file. Standard Input. Leave blank for no input, console to read from the console window, or any path to a file to read from that file. Standard Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file.
blank
lax.stdin.redirect
blank
lax.stdout.redirect
blank
Page 249
IntroscopeWebView.properties File
TABLE 21. File: <Introscope home>/config/IntroscopeWebView.properties This Setting
log4j.logger.WebView log4j.appender.logfile.File introscope.webview.tcp.port introscope.webview.enterprise manager.tcp.host introscope.webview.enterprise manager.tcp.port introscope.explorer.refresh.int erval introscope.webview.password
Specifies
Amount of logging detail for the WebView log Name and location of WebView logfile Port on which WebView listens for HTTP traffic Enterprise Manager hostname to connect to Enterprise Manager port to connect to Frequency (in seconds) at which the Explorer tree refreshes. Password WebView uses to connect to the Enterprise Manager
Default Setting
INFO, console logs/ IntroscopeWebView.log 8080 localhost 4500 15 WebView Note: DO NOT CHANGE.
Specifies
The Java classpath necessary to run this application.
Default Setting
lib/WebViewServices.jar;lib/ Workstation.jar;lib/ WebViewAPI.jar;lib/ WebViewServer.jar;lib/ IntroscopeServices.jar;lax.jar $CMD_LINE_ARGUMENTS$
lax.command.line.args
What command line arguments will be passed to the main method. Can use this property to supply WebView with login values, bypassing the Login screen when starting WebView. VM to use the next time the Workstation is started. Can be set to any installed JDK or JRE version 1.3. Other option settings for JVM Initial minimum and maximum heap sizes.
lax.nl.current.vm
lax.nl.java.option. additional
-classic -ms64m -mx256m The classic setting invokes Java 2 classic VM.
Page 250
This Setting
lax.stderr.redirect
Specifies
Standard Error Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file. Standard Input. Leave blank for no input, console to read from the console window, or any path to a file to read from that file. Standard Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file.
Default Setting
blank
lax.stdin.redirect
blank
lax.stdout.redirect
blank
CustomDBRecordTypes.properties File
The default datatypes may not be sufficient to meet your needs. You can add custom datatypes by adding lines to the file, CustomDBRecordTypes.properties. You are more likely to be creating a custom datatype for use with a custom Tracer. (For more information, see Database Record Types, page 209.) Create a custom datatype with three properties: a regular expression to identify an Agent a regular expression to identify Metrics a new datatype name To assign a datatype to a Metric, the Agents name is matched against Agent regular expressions, until a match is found. Then Metric regular expressions are checked for that Agent. The Metrics name is matched against the regular expressions for custom datatypes. If no custom datatype matches, then default datatypes are checked. The Metric is assigned the first datatype whose regular expression matches the Metrics name. Each set of three lines in the table specifies a single custom datatype, corresponding to the three parts of the datatype (Agent regular expression, Metric regular expression, Name). Thus, each set of three lines is given the same index, starting with 0. Give the first set for your first custom datatype an index of 0, second custom datatype set of three gets an index of 1, and so on. Replace the # with the index in all three lines in each set. The numbering must be sequential with no gaps.
Page 251
Extensions Settings Files TABLE 23. File: <Introscope home>/config/customDBRecordTypes.properties This Setting
introscope.enterprisemanager. database.recordtypes. agentexpression.# introscope.enterprisemanager. database.recordtypes. metricexpression.# introscope.enterprisemanager.d atabase.recordtypes. typestring.#
Specifies
Identifies an Agent
Default Setting
Regular Expression
Identifies Metric
Regular Expression
Datatype name assigned to a Metric that matches both regular expressions above
Record Type
Specifies
Pathname of the username/ password file
Default Setting
config/users.xml
LDAPAuthenticationExtension.properties
This file contains the configuration properties for the LDAP authentication extension. TABLE 25. File: <Introscope home>/config/ LDAPAuthenticationExtension.properties
This Setting
authentication.extension.ldap.url=
Specifies
URL for the remote LDAP server
Default Setting
ldap://host:port
Note: If you are using SSL, the SSL LDAP port should be part of the server URL.
authentication.extension.ldap.useS SL authentication.extension.ldap.bind Name Whether to use SSL to connect to remote LDAP server Name used to bind to LDAP server. If blank, anonymous bind is used. false IntroscopeLDAPUser
Page 252
This Setting
authentication.extension.ldap.bind Password authentication.extension.ldap.bind Authentication
Specifies
Password used to bind to LDAP server. If anonymous bind is used, this property is ignored. Authentication type to use when binding. Options are: none, simple, CRAMMD5.
Default Setting
password123
simple
authentication.extension.ldap.user. nameSuffix authentication.extension.ldap.user. baseDN authentication.extension.ldap.user. scopeDepth authentication.extension.ldap.user. usernameAttribute authentication.extension.ldap.user. userObjectQuery
Suffix to append to Introscope user name for use with LDAP queries. Base distinguished name (DN) for all user object queries Search depth when querying for a user object Name of LDAP attribute that will match an Introscope username LDAP search filter used to query a user object. The token %u will be filled in with the Introscope username before the query executes. Name of certificate file. Supported certificate types are of type X.509, and base64-encoded. If not specified, default certificate authorities provided by the JVM will be used.
@dev.com
authentication.extension.ldap.serv erCertificate
blank
Page 253
BLicenses
Apache Software License, Version 1.1
Copyright (c) 1999-2000 The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. 2. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org. 5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
3.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Page 254
License for JDOM Binary Distribution This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation, please see http://www.apache.org.
3.
4.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JDOM PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the Java Document Object Model Project and was originally created by Brett McLaughlin <brett@jdom.org> and Jason Hunter <jhunter@jdom.org>. For more information on the JDOM Project, please see http://www.jdom.org.
Page 255
License for Tanuki Software Distribution Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub-license , and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Page 256
Index
A
Agent
cloned Agent naming 176 configuration other settings 177 verbose mode 179 installing on Oracle 10g 136 on other application servers 142, 149 on Sun ONE 128 on WebLogic 95 on WebSphere 106 on WebSphere on OS/390 117 naming options 169 automatic automatically from application server 170 using Java system property 169 using system property key 170 redirecting output to a file 179 resolving Agent naming conflicts 177 running Agent twice on one machine 177 verbose mode 179 with Sun ONE 131 with WebLogic 101 with WebSphere 111 with WebSphere on OS/390 121 definition 22 directives using custom 177 JVM AutoProbe with Oracle 10g 138 with other application servers 144, 151 with Sun ONE 130 with WebLogic 99 with WebSphere 108 with WebSphere on OS/390 119 properties file location on WebLogic 102
B
batch job
running Enterprise Manager as in OS/390 67
Agent Failover
Domains and User issues with 93
C
Command-Line ProbeBuilder
commands 164 configuring other Java applications 162
Agent failover
Domain/User configuration 175
AIX
platform monitors 181
audience 15 Authentication
LDAP 84 local 81
AutoProbe
Application Server AutoProbe 96 with Oracle 10g 139
Page 257
D
database
5.0 database schema 203 configuring Enterprise Manager for 193 creating reports 211 Enterprise Manager properties 195 explicit table qualifier 199 querying tables 210 record types 209 reporting 202211 sample Microsoft Access database 196 scripts creation 194 tables Agent table 205 Index table 204 Metadata table 206 Metric name table 206 Metric table 206 Property table 205 Resource table 206 Version table 204 upgrading schema tables 194
configuring database 193 new database connection 194 installing and configuring on OS/390 running as a batch job in OS/390 67 running as Windows Service 65 deregistering 66 running from command line commands 197 starting 58 OS/390 59 UNIX 58 Windows 58 stopping 59
F
firewall 32
connecting components behind 200
Domain 23 Domains
Agent mapping 78 changing 79 associating Management Modules with 78 attributes and syntax 77 creating 77, 78 creation rules 77 deleting 79 Managing Domains 76 merging 80 moving between Introscope installations 80
G
GUI mode
36 GUI installation sequence 37 launching GUI mode installer 37
I
Installation
in Console mode 49 in GUI mode 36 GUI installation sequence 37 launching GUI mode installer 37 in Silent mode 51 launching silent mode installer 52 miscellaneous options 201 planning where to install 27 preparing for 27, 32 process 33
E
Element 26 Enterprise Manager 22
Page 258
system requirements 29
Interstage
using Introscope with 94
Introscope
components defined 21 JVMs bundled with 31 supported JVM versions 31 terms defined 21
M
Managed Java Application 21 Management Module 26 Management Modules
moving 198
Introscope.EnterpriseManager.properties
database properties 195
Introscope-enabled code 21
options 166 switching back to original code 167
J
Java2 Security Policy 201 on WebSphere 5.0 110, 112 JMX support 182187
configuring 185 enabling 185 JMX filters 184, 186 Metric name conversion 183 default method 184 primary keys method 183 primary keys 183 primary keys, defining 186 viewing JMX data in Explorer 187
O
Oracle Application Server 10g
configuring with Introscope 136141 basic Agent settings 140 installing Agent on 136 ProbeBuilder configuration options 137
L
lax files
Introscope Enterprise Manager.lax 247 Introscope ProbeBuilder Wizard.lax 242 Introscope WebView.lax 250 Introscope Workstation.lax 249
License
Apache Software Version 1.1 254 JDOM Binary Distribution 255
license file
installing 58
Log4J
Agent settings 179
Page 259
OS/400
installing Introscope Agent with AutoProbe WebLogic 95
P
platform monitor 180
troubleshooting 182
ports
specifying 242
ProbeBuilder 22
Command-line ProbeBuilder 162 configuring java applications manually with 155 customizing Directives 212 integrating into build process 200 list files 214 log 201 ProbeBuilder Wizard 155
TraceOneMethodWithParametersOfClass 230 TurnOn 230 skip 228 SkipClass 228 SkipPackage 228 Threshold action 230 parameters 231 TraceAllMethodsWithThresholdOfClass 230 TraceOneMethodWithThresholdOfClass 230 Threshold Tracers OverThresholdPerIntervalCounter 231 StalledMethodTracer 231 UnderThresholdPerIntervalCounter 231 modifying 215 EJB subclass tracing 219 Tracer groups adding classes to 219 turning on or off 218 only defined methods traced 214 parameters 227 single-Metric Tracers 213 Tracer groups adding classes to 219 default 216 turning on or off 213, 218, 219 updating probes 231
Probes 21 properties
database 243 Directives files to use 235 files 234 flat file 243 introscope.autoprobe.DirectivesFile 235
properties files
CustomDBRecordTypes.properties 251 Introscope Enterprise Manager.lax 247 Introscope ProbeBuilder Wizard.lax 242 Introscope WebView.lax 250 Introscope Workstation.lax 249
Page 260
R
RedHat
platform monitor 180
redirect output
Agent 179 Enterprise Manager in 64 Workstation 200
Resource 23
Blame Technology and 224 BlamedMethodRateTracer 222 BlamedMethodTimer 221 BlamedMethodTraceDecrementor 222 BlamedMethodTraceIncrementor 222 ConcurrentInvocationCounter 222 default Tracer Groups 215 example template 223 full and typical tracing options 175 MethodCPUTimer 222 MethodRateTracer 222 MethodTimer 221 MethodTraceDecrementor 222 MethodTraceIncrementor 222 PerIntervalCounter 222 toggle files 215
S
Silent mode 51
launching silent mode installer 52
type conventions 17
SmartStor 60
and Persistent Collections 60, 193 requirements 61
U
uninstalling Introscope 54 UNIX
Enterprise Manager running in nohup mode 64 starting Enterprise Manager 58
User
modifiers and syntax 82
User permissions
creation rules 88
Users
access privileges server permissions creation rules 91 defining 81 defining a user 82 permissions 88 Domain access defining permissions 90 server access defining permissions 92 modifiers and syntax 91
T
Tracer groups
adding classes to 219
Tracers
advanced custom creating 225 advanced single-Metric 225
Page 261
V
verbose mode
running Agent in 179 running Enterprise Manager in 63 running Workstation in 199
W
WebLogic Server
configuring with Introscope 95105 basic Agent settings 102 installing Agent on 95 ProbeBuilder configuration options 96 JMX data 182
WebSphere Application Server on OS/ 390 configuring as batch job 6775 configuring with Introscope ??127
installing Agent on 117 ProbeBuilder configuration options 118
Workstation 24
connecting to Enterprise Manager behind firewall 200 installing on Windows 94
Page 262