WI 6.0.1InstallConfigGuide

Installation and Configuration Guide
Version 6 Release 6.0.1
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
Introscope 6.0.1 Installation and Configuration Guide

Copyright 2005, Wily Technology, Inc. All Rights Reserved. The following trademarked names are properties of the named companies: Introscope is a registered trademark of Wily Technology, Inc. Java, Sun MicroSystems Solaris, and Sun ONE are registered trademarks of Sun MicroSystems, Inc. AIX, AS/400, z/OS, iSeries and WebSphere are registered trademarks of International Business Machines Corporation. UNIX is a registered trademark of The Open Group. Windows, Windows 2000 Professional/Server/Advanced Server/Datacenter Server, Windows Server 2003, Windows XP and Excel are registered trademarks of Microsoft Corporation. HP-UX and HP HotSpot JVM are registered trademarks of Hewlett-Packard Company. Linux is a registered trademark of Linus Torvalds. Interstage is a registered trademark of Fujitsu Limited. WebLogic is a registered trademark of BEA Systems, Inc. Oracle and Oracle Application Server 10g are registered trademarks of Oracle Corporation. All other names used in this document are the property of their respective holders.
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
Chapter 1 Introscope Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

How Introscope Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Introscope Components and Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Managed Java Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 ProbeBuilder Wizard and Command Line ProbeBuilder . . . . . . . . . . . . . . . . 22 ProbeBuilder and Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Metric Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Blame Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 SuperDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Introscope Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Dashboard Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Management Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 2 Preparing For Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Preparing To Install Introscope . . . . . . . . . . . . . . . . . . Step 1: Plan Where To Install Introscope Components Step 2: Choose Installation Method . . . . . . . . . . . . . . Install Notes . . . . . . . . . . . . . . . . . . . . . . . . . . Introscope Installer Modes . . . . . . . . . . . . . . . . Introscope 6.0.1 Installation & Configuration Guide (9/15/05) . . . . . . . . . . . . . . . . . . . 27 . . . . . . . . . . . . . . . . . . . 27 . . . . . . . . . . . . . . . . . . . 27 . . . . . . . . . . . . . . . . . . . 28 . . . . . . . . . . . . . . . . . . . 28 Page 4
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
Chapter 3 Installing Introscope Components . . . . . . . . . . . . . . . . . . . . . . . . . 35

Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Installing Introscope In GUI Mode . . . . . . . . . . Installation in GUI mode . . . . . . . . . . . . . . . Launching GUI Mode Installer . . . . . . . . GUI Installation Sequence . . . . . . . . . . Next Steps - Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 . . . . . . . . . . . . . . . . . . . . 37 . . . . . . . . . . . . . . . . . . . . 37 . . . . . . . . . . . . . . . . . . . . 37 . . . . . . . . . . . . . . . . . . . . 49 . . . . . . . . . . . . . . . . . . . . . . . . 49 . . . . . . . . . . . . . . . . . . . 50 . . . . . . . . . . . . . . . . . . . 50 . . . . . . . . . . . . . . . . . . . 50 . . . . . . . . . . . . . . . . . . . 51
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
Chapter 4 Configuring and Running the Introscope Enterprise Manager. . . . 57

Installing License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Starting Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Windows (Enterprise Manager not configured as a Windows Service) . . . . . 58 OS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Writing Status Information to Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Running the Enterprise Manager as a Java Program . . . . . . . . . . . . . . . . . . . . . 59 Stopping Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
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
Chapter 5 Configuring Introscope Security and Permissions . . . . . . . . . . . . . 76

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Configuring and Managing Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Domain Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 6
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . 99 . . 99 . . 99 . . 99 . 100 . 100 . 101 . 101 . 101 . 101 . 102 . 102
. . . . . . . . . . . . . . . . . . . 102 . . . . . . . . . . . . . . . . . . . 102 . . . . . . . . . . . . . . . . . . . 103 . . . . . . . . . . . . . . . . . . . 103 . . . . . . . . . . . . . . . . . . . 103 . . . . . . . . . . . . . . . . . . . . . . 104 . . . . . . . . . . . . . . . . . . 105 . . . . . . . . . . . . . . . . . . 105 . . . . . . . . . . . . . . . . . . 105
Additional Configuration Options . . . . . . . . . . . . . . Creating a WebLogic Startup Class . . . . . . . . . . . Configuring a Startup Class In WebLogic 8.1 Optional WebLogic Configurations . . . . . . . . . . . .
Chapter 8 Configuring WebSphere Application Server With Introscope . . . 106

Configuring Introscope With WebSphere Overview . . . . . . . . . . . . . . . . . . . . . 106 Installing Introscope Agent on WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 107 JVM AutoProbe With WebSphere Using Sun or IBM JVM . . . . . . . . . . . . . . . . . . 108 Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 JVM AutoProbe With WebSphere Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . 110 Application Server AutoProbe With WebSphere . . . . . . . . . . . . . . . . . . . . . . . . 111 Application Server AutoProbe With WebSphere 6.0/5.1/5.0 . . . . . . . . . . . 111 Application Server AutoProbe With WebSphere 4.0 (Distributed) . . . . . . . 112 Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 113 Configuring Basic Agent Settings on WebSphere Agent Profile Location . . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . . Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 . . . . . . . . . . . . . . . . . . . 113 . . . . . . . . . . . . . . . . . . . 114 . . . . . . . . . . . . . . . . . . . 114 . . . . . . . . . . . . . . . . . . . 114
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
Chapter 9 Configuring WebSphere on z/OS With Introscope . . . . . . . . . . . 117

Configuring Introscope With WebSphere on z/OS Overview . . . . . . . . . . . . . . 117 Installing Introscope Agent on WebSphere on z/OS . . . . . . . . . . . . . . . . . . . . 117 ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
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
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. 118 . 119 . 119 . 120 . 121 . 122 . 124
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
Chapter 10 Configuring Sun ONE Application Server With Introscope . . . . 128

Configuring Introscope With Sun ONE Overview . . . . . . . . . . . . . . . . . . . . . . . 128 Installing Introscope Agent on Sun ONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 129 JVM AutoProbe With Sun ONE 7.0 Using Sun JVM . . . . . . . . . . . . . . . . . . . . . . 130 Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Application Server AutoProbe With Sun ONE . . . . . . . . . . . . . . . . . . . . . . . . . 131 Application Server AutoProbe With Sun ONE 7.0 . . . . . . . . . . . . . . . . . . . 131 Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 133 Configuring Basic Agent Settings for SunONE Agent Profile Location . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . Configuring Introscope Agent . . . . . . . . . . . Additional Configuration Options . . . . . .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 . . . . . . . . . . . . . . . . . . . 133 . . . . . . . . . . . . . . . . . . . 133 . . . . . . . . . . . . . . . . . . . 134 . . . . . . . . . . . . . . . . . . . 135
Chapter 11 Configuring Oracle Application Server 10g With Introscope . . . 136

Configuring Introscope With Oracle 10g Overview . . . . . . . . . . . . . . . . . . . . . 136 Installing Introscope Agent on Oracle 10g . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 137 JVM AutoProbe With Oracle 10g Using Sun JVM . . . . . . . . . . . . . . . . . . . . . . . 138 Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Application Server AutoProbe With Oracle Application Server 10g . . . . . . . . . . . 139 Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 139 Configuring Basic Agent Settings for Oracle Agent Profile Location . . . . . . . . . . . . . . Defining Agent Profile Location . . . . Configuring Introscope Agent . . . . . . . . . Additional Configuration Options . . . 10g .... .... .... .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 . . . . . . . . . . . . . . . . . . . 140 . . . . . . . . . . . . . . . . . . . 140 . . . . . . . . . . . . . . . . . . . 140 . . . . . . . . . . . . . . . . . . . 141
Page 9
Chapter 12 Configuring SAP NetWeaver With Introscope . . . . . . . . . . . . . . 142

Configuring Introscope With SAP NetWeaver Overview ProbeBuilder Configuration Options . . . . . . . . Choosing ProbeBuilder Configuration Option . JVM AutoProbe Using Sun or IBM JVM . . . . . Creating an AutoProbe Connector . . . . Running the AutoProbe Connector . . . . JVM AutoProbe Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 . . . . . . . . . . . . . . . . . . . 143 . . . . . . . . . . . . . . . . . . . 143 . . . . . . . . . . . . . . . . . . . 144 . . . . . . . . . . . . . . . . . . . 144 . . . . . . . . . . . . . . . . . . . 145 . . . . . . . . . . . . . . . . . . . 146 . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . 147 . . . . . . . . . . . . . . . . . . . 148
Configuring Basic Agent Settings . . . . . . . . . . . . Agent Profile Location . . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . . Additional Configuration Options . . . . . . .
Chapter 13 Configuring Other Application Servers or Applications With Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Configuring Introscope With Other Application Servers Overview . . . . . . . . . 149 Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 ProbeBuilder Configuration Options . . . . . . . . Choosing ProbeBuilder Configuration Option . JVM AutoProbe Using Java 5.0 JVM . . . . . . . JVM AutoProbe Using Sun or IBM JVM . . . . . Creating an AutoProbe Connector . . . . Running the AutoProbe Connector . . . . JVM AutoProbe Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 . . . . . . . . . . . . . . . . . . . 150 . . . . . . . . . . . . . . . . . . . 151 . . . . . . . . . . . . . . . . . . . 151 . . . . . . . . . . . . . . . . . . . 151 . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . 153 . . . . . . . . . . . . . . . . . . . 153 . . . . . . . . . . . . . . . . . . . 154
Configuring Basic Agent Settings . . . . . . . . . . . . Agent Profile Location . . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . . Additional Configuration Options . . . . . . .
Chapter 14 Configuring the Java Applications Manually With ProbeBuilder 155

Configuring Java Applications Manually Overview . . . . . . . . . . . . . . . . . . . . . . 155 Configuring Java Applications With ProbeBuilder Wizard . . . . . . . . . . . . . . . . 155 Installing Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Adding Probes to Bytecode With ProbeBuilder Wizard . . . . . . . . . . . . . . . . . . . 157 Editing the Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Configuring Java Applications With Command-Line ProbeBuilder . . . . . . . . . . 162 Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Adding Probes to Bytecode Using Command-Line ProbeBuilder . . . . . . . . . . . . . 163 Editing the Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Configuring Basic Agent Settings . . . . . . . . . . . . Agent Profile Location . . . . . . . . . . . . . . . . . . Defining Agent Profile Location . . . . . . . . Configuring Introscope Agent . . . . . . . . . . . . . Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 . . . . . . . . . . . . . . . . . . . 165 . . . . . . . . . . . . . . . . . . . 165 . . . . . . . . . . . . . . . . . . . 165 . . . . . . . . . . . . . . . . . . . 166
Page 10
Options for Running Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . 166 Switching Back to Your Non-Introscope-enabled Code . . . . . . . . . . . . . . . . . . 167
Chapter 15 Optional Introscope Configurations. . . . . . . . . . . . . . . . . . . . . . 168

Agent Naming Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Agent Name Location Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Obtaining Agent Name Using System Properties . . . . . . . . . . . . . . . . . . . . . . . 169 Specifying Agent Name Using Java System Property . . . . . . . . . . . . . . . . 169 Specifying Agent Name Using System Property Key . . . . . . . . . . . . . . . . 170 Obtaining Agent Name Automatically From Application Server . . . . . . . . . . . . . 170 Supported Application Server Versions . . . . . . . . . . . . . . . . . . . . . . . . . 170 How Automatic Agent Naming Works . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Automatic Agent Naming and Renamed Agents . . . . . . . . . . . . . . . . . . . 171 Enabling Automatic Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Advanced Automatic Naming Options . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Agent Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Configuring Agent Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Configuring Automatic Agent Failback to Primary Enterprise Manager . . . . . . . . 175 Agent Failover and Domain/User Configuration . . . . . . . . . . . . . . . . . . . . . . . . 175 Switching Between Full and Typical Tracing Options . . . . . . . . . . . . . . . . 175 Switching to Typical Tracing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Multiple Agent Options . . . . . . . . . . . . . . . . . . . . . Enabling Cloned Agent Naming . . . . . . . . . . . . . Scenario . . . . . . . . . . . . . . . . . . . . . . . . Enabling Cloned Agent Naming in the Agent Running An Application Twice On One Machine . . How Introscope Resolves Agent Naming Conflicts . . . . . . . . . . . . . . . . . . . . . . 176 . . . . . . . . . . . . . . . . . . . . . . 176 . . . . . . . . . . . . . . . . . . . . . . 176 Profile . . . . . . . . . . . . . . . . . 177 . . . . . . . . . . . . . . . . . . . . . . 177 . . . . . . . . . . . . . . . . . . . . . . 177
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
Miscellaneous Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Java2 Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Chapter 16 Database Configuration and Reporting . . . . . . . . . . . . . . . . . . . 202

Introscope 6.0.1 Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Database Tables . . . . . . . . . . . . . . . . . . . . . . . . Version Table . . . . . . . . . . . . . . . . . . . . . . . Index Table . . . . . . . . . . . . . . . . . . . . . . . . Property Table . . . . . . . . . . . . . . . . . . . . . . Agent Table . . . . . . . . . . . . . . . . . . . . . . . . Resource Table . . . . . . . . . . . . . . . . . . . . . . Metric Name Table . . . . . . . . . . . . . . . . . . . Metadata Table . . . . . . . . . . . . . . . . . . . . . . Metric Table . . . . . . . . . . . . . . . . . . . . . . . . Resource Metric Table . . . . . . . . . . . . . . . . . Record Type Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 . . . . . . . . . . . . . . . . . . 204 . . . . . . . . . . . . . . . . . . 204 . . . . . . . . . . . . . . . . . . 205 . . . . . . . . . . . . . . . . . . 205 . . . . . . . . . . . . . . . . . . 206 . . . . . . . . . . . . . . . . . . 206 . . . . . . . . . . . . . . . . . . 206 . . . . . . . . . . . . . . . . . . 206 . . . . . . . . . . . . . . . . . . 209 . . . . . . . . . . . . . . . . . . 209
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
Chapter 17 ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Introduction to Directives . . . . . . . . . . . . . . . . . Components Tracked . . . . . . . . . . . . . . . . . . Single-Metric Tracers and Tracer Groups . . . . Only Defined Methods Traced . . . . . . . . . . . . ProbeBuilder Directive Files . . . . . . . . . . . . . Default System ProbeBuilder Files . . . . . Custom ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 . . . . . . . . . . . . . . . . . . 213 . . . . . . . . . . . . . . . . . . 213 . . . . . . . . . . . . . . . . . . 214 . . . . . . . . . . . . . . . . . . 214 . . . . . . . . . . . . . . . . . . 214 . . . . . . . . . . . . . . . . . . 214
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
Using the ProbeBuilder Wizard or the Command-Line ProbeBuilder . . . . . . 233
Appendix A Introscope Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Introscope Agent Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Agent Settings with AutoProbe Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Agent Settings Common to Both AutoProbe and non-AutoProbe Installations . . . 235 Log 4J Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Enterprise Manager Connection Order . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Enterprise Manager Locations and Names . . . . . . . . . . . . . . . . . . . . . . . 235 Agent and Process Name Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Agent Thread Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 PMI Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 JMX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 LeakHunter Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Transaction Tracer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Introscope ProbeBuilder Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Introscope ProbeBuilder Wizard.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Introscope Enterprise Manager Settings Files IntroscopeEnterpriseManager.properties File Ports . . . . . . . . . . . . . . . . . . . . . . . . Log 4J Settings . . . . . . . . . . . . . . . . . SmartStor Properties . . . . . . . . . . . . . Transaction Event Database . . . . . . . . Database Properties . . . . . . . . . . . . . Flat File Properties . . . . . . . . . . . . . . SNMP Collections . . . . . . . . . . . . . . . WebView . . . . . . . . . . . . . . . . . . . . . Introscope Enterprise Manager.lax File . . . . EMService.conf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 . . . . . . . . . . . . . . . . . . . 242 . . . . . . . . . . . . . . . . . . . 242 . . . . . . . . . . . . . . . . . . . 242 . . . . . . . . . . . . . . . . . . . 242 . . . . . . . . . . . . . . . . . . . 243 . . . . . . . . . . . . . . . . . . . 243 . . . . . . . . . . . . . . . . . . . 243 . . . . . . . . . . . . . . . . . . . 243 . . . . . . . . . . . . . . . . . . . 243 . . . . . . . . . . . . . . . . . . . 247 . . . . . . . . . . . . . . . . . . . 248
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
Appendix B Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Apache Software License, Version 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 License for JDOM Binary Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 License for Tanuki Software Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
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.
Introscope 6.0.1 Installation and Configuration Guide Audience

This book is written for users who are experienced in installing and configuring application servers and systems. The book assumes that the reader knows how to install and run Java software on distributed and mainframe systems, set classpaths, and modify property files.
Introscope 6.0.1 User Guides

Introscope documentation is comprised of the following guides: Introscope 6.0.1 Upgrade Guide Introscope 6.0.1 Installation and Configuration Guide (this guide) Introscope 6.0.1 Workstation Guide Introscope 6.0.1 WebView Guide
Introscope 6.0.1 Upgrade Guide

The Introscope 6.0.1 Upgrade Guide is intended for users who are upgrading an Introscope deployment from an earlier version to Introscope 6, version 6.0.1. The Upgrade guide also describes new features introduced in Introscope version 6.0.1.
Introscope 6.0.1 Installation and Configuration Guide (this guide)

The Introscope 6.0.1 Installation and Configuration Guide is intended for those who install and configure Introscope components. This guide includes information on: Installing and configuring the Introscope Agent, Enterprise Manager, and Workstation Introscope-enabling your Java Application Configuring Domains in your deployment Configuring users, permissions and authentication settings
Introscope 6.0.1 Workstation Guide

The Introscope 6.0.1 Workstation Guide is intended for users who view management application data and configure monitoring logic in the Introscope Workstation. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 15
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
Introscope 6.0.1 WebView Guide

The Introscope 6.0.1 WebView Guide is intended for users who view management application data in WebView using a web browser.
Organization of the Introscope 6.0.1 Installation Guide

This book is organized into the following chapters and appendices: Chapter 1, Introscope Overview, introduces Introscope software, its features, and terms used in this book. Chapter 2, Preparing For Installation, discusses system requirements and information to gather to prepare for Introscope installation. Chapter 3, Installing Introscope Components, describes how to use the installer to install and perform basic configurations for Introscope components except Introscope Agent. Chapter 4, Configuring and Running the Introscope Enterprise Manager, describes how to hand-edit the properties files after installation of Introscope Enterprise Manager. Chapter 5, Configuring Introscope Security and Permissions, describes how to configure Domains, Users and permissions and local and external authentication. Chapter 6, Configuring Java Applications With Introscope, directs you to the appropriate chapter to use to Introscope-enable your applications. Chapter 7, Configuring WebLogic Server With Introscope, describes how to install and configure the Introscope Agent and Introscope-enable your Java application with WebLogic Server. Chapter 8, Configuring WebSphere Application Server With Introscope, describes how to install and configure the Introscope Agent and Introscope-enable your Java application with WebSphere Application Server. Chapter 9, Configuring WebSphere on z/OS With Introscope, describes how to install and configure the Introscope Agent and Introscope-enable your Java application with WebSphere Application Server on z/OS. Chapter 10, Configuring Sun ONE Application Server With Introscope, describes how to install and configure the Introscope Agent and Introscope-enable your Java application with Sun ONE Application Server. Chapter 11, Configuring Oracle Application Server 10g With Introscope, describes how to install and configure the Introscope Agent and Introscope-enable your Java application with Oracle Application Server 10g.
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.
Type Conventions Used in this Book

Convention Is Used For
File, directory and property names, computer output or code input examples User interface menu items and screen prompts.
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
Need Help With Installation?
Convention
# (pound sign)
Is Used For
UNIX prompt with
root login, as:
# 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:
C:\<your-applicationpath>.isc\classes; \<your-applicationpath>.isc\lib\app.jar; \Introscope\lib\Agent.jar

(space) Spaces separate words in Windows launcher application names.
Need Help With Installation?

For more help with configuring Introscope, please contact Wily Technical Support at 1888-GET-WILY or wilytech@custhelp.com.
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
How Introscope Works
How Introscope Works

Figure 1 is a simple conceptual view of how Introscope prepares a Java Application to be managed.
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
Introscope Components and Terms

Agent
The following terms relate to the Introscope Agent and managed applications.
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.
Managed Java Application

A managed Java Application (or managed application) is a running application whose code has been Introscope-enabled.
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
ProbeBuilder Wizard and Command Line ProbeBuilder

The ProbeBuilder Wizard is GUI tool for running the ProbeBuilder in a windowing environment. The Command Line ProbeBuilder runs with a command in a non-windowing environment.
ProbeBuilder and Directives

The ProbeBuilder is an Introscope utility that creates a copy of Java bytecode and adds Probes to it. ProbeBuilder Directives describe which methods, classes, and sets of classes to monitor in managed application bytecode. Introscope provides a default ProbeBuilder Directives file that tracks items in most common Java and Java 2 Enterprise Edition (J2EE) application programming interfaces (APIs), such as servlets and sockets. Additionally, custom Probes can be created to measure counts, rates, and response times of methods being invoked. For more information on ProbeBuilder Directives, see Chapter 17, ProbeBuilder Directives.
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
2 Preparing For Installation

This chapter describes the preparations you should make before installing and configuring Introscope. Information is provided in the following sections: Preparing To Install Introscope Information to Collect Before You Begin Reviewing Installation and Configuration Process
Preparing To Install Introscope

You should perform several steps before you install Introscope: Plan where to install your components Choose installation method Check system requirements to ensure your system will support Introscope Collect information required for installation Review the installation and configuration process
Step 1: Plan Where To Install Introscope Components

To maximize performance of your managed Java Application, install the Enterprise Manager, the Workstation and your Java Application with the Agent on separate machines. Your deployment may also include a connection to a database.
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.
Step 2: Choose Installation Method

The Introscope installer simplifies installation by performing most of the common Enterprise Manager and Workstation configurations automatically during the installation process.
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.
Introscope Installer Modes

The installer offers three possible interfaces (depending on platform used): GUI mode The GUI mode consists of a series of graphical windows that will collect user input, prompt the user to correct any incorrect settings, install Introscope components and summarize installation results. Console mode
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.
Supported Modes By Platform

The following table details which installer interface options are available per operating system: TABLE 1. Supported Installer Modes By Platform Interface and Platform Windows AIX Solaris HP-UX Red Hat Linux OS/400 z/OS Other GUI
Yes Yes
Console
No Yes
Silent Mode
Yes Yes
Default Mode
GUI GUI
No No Yes
Yes Yes Yes
Yes Yes Yes
none none GUI
Note: For installers without a default mode (z/OS and OS/400), you must specify an
install mode on the command line.
Step 3: Check System Requirements

The following section details the system requirements for Introscope installation.
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
Agent (managed application) WebView
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
Temporary Directory Space SmartStor
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.
8GB (with default settings)
Note: See Configuring SmartStor, page 60, for more information on

determining SmartStor storage space requirements. Transaction Event Database Storage 2GB (with default settings) Amount of space required varies depending on number of transaction events captured and how long data is stored.
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
Required Minimum Memory

128 MB 128 MB 128 MB 128 MB N/A 128 MB N/A
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.
Memory Required May Vary

While the previous table states the minimum memory required for each Introscope component, in practice, the amount of memory needed by the Enterprise Manager and the Workstation may be higher, depending on the following factors: the number of connected Agents the number of connected Workstations amount of Metrics generated monitoring logic, such as Metric Groupings, Persistent Collections, Alerts, Calculators, etc. Contact Wily Support for assistance in determining the proper amount of memory for your deployment.
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
Information to Collect Before You Begin
Windows AIX HP-UX Red Hat Linux z/OS OS/400
Sun JDK 1.4.2_03 IBM JDK 1.4.1 HP JVM 1.4.1.03 Sun JDK 1.4.1 none none
JVM Used by Installer

During install, the installer will use the JVM it was bundled with, unless the user forces an alternate JVM on the command line when invoking the installer. For any installer that does not bundle a JVM (such as OS/400), the user must specify the desired JVM (version 1.3.x or higher) on the command line when invoking the installer. Whenever possible, use a version 1.4.x JVM.
Step 4: Review Installation Notes

If you are installing the Workstation and Enterprise Manager on separate machines, synchronize the clocks on each of the machines. If clocks are not synchronized, there may be discrepancies in historical query results between Workstations and Enterprise Manager. For z/OS, the installed text files are already in EBCDIC format. For OS/400, we recommend you use QShell to install in either Console or Silent mode. To run installers on machines without video cards, or Xservers, you must force Console mode. When running WebView on AIX, X11 server must be running.
Information to Collect Before You Begin

Enterprise Manager Information
Collect host and port locations for each machine on which an Enterprise Manager is installed. Needs one port to listen for the Agent and two ports to listen for the Workstation, one of which is used for a secure connection during user authentication. The secure port is only needed for firewall configuration, and does not need to be specified in the Workstation itself. These need to be unused ports at this IP address, and should be opened in a firewall if needed.
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__________
User Name and Password on the Enterprise Manager Machine

User name (with administrative rights) and password on each Enterprise Manager machine.
User Name EM1_________________ EM2_________________ EM3_________________ EM4_________________
Password EM1_______ EM2_______ EM3_______ EM4_______
License obtained Check here when license is obtained.
Reviewing Installation and Configuration Process

After youve checked the system requirements and collected the appropriate access and configuration information for your deployment, youre ready to start installing and configuring Introscope. This process consists of the following steps: 1. Download/obtain the appropriate installer files: full platform installer (installs all core Introscope components but Agent) Agent installer file specific to your application server and operating system 2. 3. 4. Run the Introscope installer, which can install and specify basic configurations for all core Introscope components but the Agent. Install and configure the Introscope Agent. Introscope-enable your Java application(s), using either JVM AutoProbe, Application Server AutoProbe, ProbeBuilder Wizard or Command-Line ProbeBuilder.
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.
Starting the Installation Process

To start the installation process, proceed to the next chapter, Installing Introscope Components.
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
3 Installing Introscope Components

This chapter covers the installation and configuration of Introscope in the following sections: Installer Files Installing Introscope In GUI Mode Installing Introscope In Console Mode Installing Introscope In Silent Mode Uninstalling Introscope
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 Including Agent

introscope6.0.1windowsinstall.zip introscope6.0.1solarisinstall.tar introscope6.0.1hpuxinstall.tar introscope6.0.1aixinstall.tar introscope6.0.1linuxinstall.tar introscope6.0.1os400install.zip introscope6.0.1zOSinstall.tar introscope6.0.1otherinstall.tar
Installer Without Agent

introscope6.0.1windows.zip introscope6.0.1solaris.tar introscope6.0.1hpux.tar introscope6.0.1aix.tar introscope6.0.1linux.tar introscope6.0.1os400.zip introscope6.0.1zOS.tar introscope6.0.1other.tar
For SAP Support Only

Operating System
Windows
Installer Filename
introscope6.0.1windowsinstall.SAPExpertCenter.zip
Page 35
Installing Introscope In GUI Mode
Solaris HP-UX AIX Linux
introscope6.0.1solarisinstall.SAPExpertCenter.tar introscope6.0.1hpuxinstall.SAPExpertCenter.tar introscope6.0.1aixinstall.SAPExpertCenter.tar introscope6.0.1linuxinstall.SAPExpertCenter.tar
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):
#tar xvf introscope6.0.1solarisinstall.tar
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
For SAP Support Only

Operating System
Windows Solaris HP-UX AIX Linux
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

After you have extracted the installer from the installer package, decide which installer mode you are going to use, and follow the instructions in the appropriate section. Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 36
Installation in GUI mode

This section describes Introscope installation in GUI mode. The installer defaults to GUI mode on all platforms except z/OS and OS/400. GUI mode is not supported on z/OS, or OS/400. Installer must be invoked in Console mode (see Installing Introscope In Console Mode, page 49). The GUI will walk the user through a series of friendly windows that: identify which components to install collect settings for each desired component error-check the settings and prompt the user to correct them if needed install the product, displaying a progress bar summarize the install results and name the location of more detailed log(s)
Launching GUI Mode Installer

There are several ways to launch the installer in GUI mode, depending on the installer file type: For .exe files, double-click on the file, or invoke it from the command line. For example:
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:
[root:/] /usr/java/bin/java -classpath introscope6.0.1other.jar install
GUI Installation Sequence

You navigate through the installer windows using Next and Back buttons. You can use the Tab key to select your choice, and the Return key to accept the choice. The instructions shown in this section will show a complete install of all Introscope components, and will say Yes to all installation options available.
General Installation Information

1. After you launch the installer, you will see the Introduction screen.
Page 37
Installing Introscope In GUI Mode 2. Click Next.
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.
Enterprise Manager Settings

The following screens appear if you chose to install an Enterprise Manager. The Specify License screen appears.
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.
The Enterprise Manager Transaction Event Storage screen appears.
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.
The second Enterprise Manager Transaction Event Storage screen appears.
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.
Enterprise Manager As Windows Service - Windows Installs Only

The Enterprise Manager As Windows Service screen appears.
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.
14. Click Next.
Enterprise Manager Pre-Installation Summary

The Enterprise Manager Pre-Installation Summary screen appears. Review the summary of Enterprise Manager installation configurations. Go back and make corrections if necessary. 15. Click Next to continue with installation and configuration of other Introscope components.
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
Installing Introscope In Console Mode
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.
Next Steps - Installing Introscope Agent
Proceed to Chapter 6, Configuring Java Applications With Introscope.
Installing Introscope In Console Mode

To install using Console mode, you must force it on the command line. Installation using Console mode will be identical to that of the GUI mode, in that it will: Ask for the same fields as GUI mode Return the same error messages as GUI mode Present the same result summaries as GUI mode Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
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.
Launching Console Mode Installer

Using z/OS
After extracting the introscope6.0.1zOSinstall.tar file, you will see two files: introscope6.0.1zOS.jar runinstaller.sh The runinstaller.sh script will launch the installer by default in console mode, and check that there is at least 60MB of space in the /tmp directory. 1. Before running the script, check that a JAVA_HOME environment variable exists by running:
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
Using Any Other Platform

There are two ways to launch the installer in Console mode, depending on the installer file type: For .bin files, invoke the following command from the command line:
<path to installer> -i console

For example:
[root@qaserver:/sw/downloads] ./introscope6.0.1solaris.bin -i console

For .jar files (no bundled JVM), invoke it from the command line, and specify the appropriate JVM.
For example:
Installing Introscope In Silent Mode
[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.
Installing Introscope In Silent Mode

Silent mode is supported for installers on all platforms. In silent mode, the installer is run from a command line and takes input from a response file. This makes multiple installations of Introscope easy. The silent mode installer will run in the background with no feedback. See the GUI Installation Sequence, page 37, to review the information requested by the installer. After installation, you can check the results in the installer logs.
Response File Methods

There are several methods you can use to perform a silent install using a response file: use an automatically-generated response file manually configure the sample response file with the desired settings
Using an Automatically-generated Response File

Every installation creates a response file, containing the settings specified during the install process. You can use this response file for subsequent silent mode installs. The file is named with the date and time information of the last installation, and is found in the following location:
<Introscope home>/install/ autogenerated.responsefile.<year>.<month>.<day>.<hour>.<minutes> .<second>

For example, an installation done April 30, 2004 at 7:10:00 a.m. would have a response file with the following name:
<Introscope home>/install/ autogenerated.responsefile.2004.4.30.7.10.00
Using a Manually-Configured Sample Response File

You can manually configure the desired settings in the sample response file, then use this file for subsequent silent mode installs. The sample response file is found in the following location:
<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.
Launching Silent Mode Installer

Using z/OS
After extracting the introscope6.0.1zOSinstall.tar file, you will see two files: introscope6.0.1zOS.jar runinstaller.sh The runinstaller.sh script will launch the installer, check that the specified response file exists, and check there is at least 60 MB of space in the /tmp directory. 1. Before running the script, check that a JAVA_HOME environment variable exists by running:
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 -silent <absolute path to responsefile>
Using Any Other Platform

To run the installer in silent mode: For .exe or .bin files, specify the path to the installer and the absolute path to the response file:
<path to installer> -f <absolute path to responsefile>
Page 52
Installing Introscope In Silent Mode For example:
[root@qaserver:/] ./introscope6.0.1solaris.bin -f /tmp/ myResponseFile.txt

For .jar files (no bundled JVM), specify the path to the installer, the absolute path to the response file and specify the appropriate JVM. For example:
[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.
Forcing an Uninstall Mode

You force a different uninstall mode by specifying the desired uninstall mode in the uninstaller .lax file. To specify uninstall mode in the uninstaller .lax file: 1. 2. 3. Open the file, <Introscope home>/Uninstaller Data/Uninstall Introscope.lax. Find the property, lax.command.line.args=$CMD_LINE_ARGUMENTS$ -u Amend it with the flag to force the desired mode:
lax.command.line.args=$CMD_LINE_ARGUMENTS$ -u -i swing lax.command.line.args=$CMD_LINE_ARGUMENTS$ -u -i console lax.command.line.args=$CMD_LINE_ARGUMENTS$ -u -i silent

4. Save changes to the file.
Running Uninstaller
To uninstall Introscope components: 1. Locate the Introscope uninstaller for your platform: Windows: <Introscope home>/Uninstaller Data/Uninstall Introscope.exe.
Page 54
Uninstalling Introscope Unix: <Introscope home>/Uninstaller Data/Uninstall/
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:
java -classpath uninstaller.jar uninstall

The Uninstall Introscope screen appears.
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: If you were running an Enterprise Manager or WebView as a Windows Service,

be sure to deregister it before attempting to uninstall it. Select No, Keep Service to leave it untouched. 4. Click Next. The Confirm Uninstallation screen appears: Click Continue to uninstall all Introscope components that were originally installed.
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
4 Configuring and Running the Introscope Enterprise Manager

This chapter describes how to manually configure basic properties for the Enterprise Manager. You can use this chapter to: configure basic Enterprise Manager properties you didnt configure using the automatic installer configure SmartStorTM data storage options change basic Enterprise Manager property values you entered during automatic installation configure the Enterprise Manager to run as a Windows Service or an z/OS batch job Information is provided in the following sections: Installing License Starting Enterprise Manager Enterprise Manager Ports SmartStorTM Data Storage Enterprise Manager Metric Throttle Running Enterprise Manager in nohup Mode on UNIX Configuring Enterprise Manager To Run As A Windows Service Configuring Enterprise Manager To Run As a z/OS Batch Job
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.
Starting Enterprise Manager

After configuration, you can start 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
On UNIX, run Introscope_Enterprise_Manager.
Windows (Enterprise Manager not configured as a Windows Service)

If you configured the Enterprise Manager as a Windows Service during installation, the Enterprise Manager will be started upon completion of the installation process. Otherwise, start the Enterprise Manager manually as follows: from the Start menu, Introscope > Administration > Introscope Enterprise Manager. OR run Introscope Enterprise Manager.exe (located in the Introscope directory).
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.
Running OS/400 Start Script

When the Enterprise Manager is installed on OS/400, the installer will automatically generate a start script. You can invoke the start script from a QShell command prompt as follows:
nohup ./runem.sh [IHOME] &

where [IHOME] is the optionally provided Introscope root directory. In other words,
nohup ./runem.sh &
Page 58
Starting Enterprise Manager will assume that the Introscope home is the directory where you launched the script.
nohup ./runem.sh /blah &

will assume that /blah is the Introscope root directory.
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.
Writing Status Information to Logfile

As the Enterprise Manager starts and runs, it writes status information to a log, which, by default, appears in a command prompt window. See Enterprise Manager Metric Throttle, page 63 for information on configuring Enterprise Manager logging.
Running the Enterprise Manager as a Java Program

You can run the Enterprise Manager as a Java program. An example of running Enterprise Manager from the command line from the <Introscope home> directory is:
java -classpath lib/EnterpriseManager.jar;lib/ IntroscopeServices.jar;lib/SNMPAdapter.jar com.wily.introscope.api.IntroscopeEnterpriseManager

The exact syntax depends on the version of Java that used and other settings in your environment. If you are using the Enterprise Manager with a database, you will need to add the JDBC database driver to the classpath.
Stopping Enterprise Manager

To stop the Enterprise Manager:
From the Enterprise Manager terminal window, enter:
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
Enterprise Manager Ports
Enterprise Manager Ports

Designate a port on the Enterprise Manager that can be used for listening to incoming Agent connections. If you are using multiple Enterprise Managers, you must complete these steps for each Enterprise Manager. To configure Enterprise Manager ports: 1. 2. 3. Open the file, <Introscope home>/config/
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.
SmartStorTM Data Storage

SmartStorTM functions like a flight recorder. It records all application performance data (Introscope Metrics) at all times while its in production. It allows users to analyze historical data to identify root causes of application downtime or perform capacity analysis, all without the need for an external database. SmartStor is enabled by default during Introscope installation (unless you disable it). With default settings, SmartStor requires approximately 8GB of storage on the drive Introscope is installed on to accommodate historical data. SmartStor data is set to age out over time, so the data store will not get excessively large. 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.
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.
Determining SmartStor System Requirements

To help determine the system requirements that will enable SmartStor to effectively handle your Metric workload, we have provided an Excel spreadsheet, located in the following directory:
<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.
Specifying SmartStor Data Tier Values

There are three data tiers that configure SmartStor data storage. Each tier consists of a property pair: the storage frequency (in seconds) the data aging period (in days). The rules for the frequency and aging values are: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 61
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
Transaction Event Database Storage

Transaction Event data storage allows the storage and querying of Transaction Trace and other event data. This functionality is enabled by default during Introscope installation, and the installation prompts for values for the following settings: where transaction event data will be stored the data aging period (in days). You can manually change either of these settings. Note that if you increase the data aging period, there will be an increase in system overhead, and required data space (currently 2 GB).
Configuring Transaction Event Database Settings

1. 2. Open the file, IntroscopeEnterpriseManager.properties. Make the desired changes to the following properties:
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
Enterprise Manager Metric Throttle
introscope.enterprisemanagter.transactionev ents.storage.max.data.age
Specifies (in days) how long to store transaction event data.
Increasing the data aging period has overhead and storage implications.
3.
Save changes.
Enterprise Manager Metric Throttle

Occasionally a situation may arise in which an Agent is misconfigured and becomes a runaway Agent, creating thousands of Metrics in quick succession, overloading the Enterprise Manager. If this happens in production, the user often had to put up with the situation because they couldnt easily reboot the Agent or change its configuration until a change window opened. The Enterprise Manager now has a Metric throttle, which will shut off any offending Agent when its Metric output becomes excessive. The default Metric threshold is 50,000 Metrics. If an Agent generates more than the specified number of Metrics, the Enterprise Manager will shut off the Agent and generate an error message similar to the following:
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.
Configuring Enterprise Manager Metric Throttle

If not changed by the user, the default Metric throttle is 50,000 Metrics. If you want to change the Metric threshold, you will need to manually add a property to the IntroscopeEnterpriseManager.properties file. To configure the Enterprise Manager Metric throttle: 1. 2. 3. 4. Open the file, IntroscopeEnterpriseManager.properties. Add the property, introscope.enterprisemanager.agent.metrics.limit, to the file, and enter a value for the Metric throttle limit. Save changes. Restart the Enterprise Manager.
Enterprise Manager Logging Options

Running Enterprise Manager in Verbose Mode
Running the Enterprise Manager in verbose mode records details to the log, which is helpful in debugging. To run the Enterprise Manager in verbose mode: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 63
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.
Redirecting Enterprise Manager Output to a File

To redirect Enterprise Manager output to a file: 1. 2. Open the file, IntroscopeEnterpriseManager.properties. In the property, log4j.logger.Manager, replace console with logfile. For example, if you wanted the Enterprise Manager to report in Verbose mode to a logfile, the property would look like this:
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.
Running Enterprise Manager in nohup Mode on UNIX

The Introscope Enterprise Manager can be run in nohup mode on UNIX, but several properties must first be set in the Introscope properties files. 1. In the Introscope Enterprise Manager.lax file, change the value of the lax.stdin.redirect to <blank>, as in:
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.
Additional Enterprise Manager Configurations

For additional optional Enterprise Manager configurations, see Chapter 15, Optional Introscope Configurations. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 64
Configuring Enterprise Manager To Run As A Windows Service
Configuring Enterprise Manager To Run As A Windows Service

Overview
A public domain java service wrapper from wrapper.tanukisoftware.org is used with Introscope to enable running the Introscope Enterprise Manager as a Windows Service. Documentation on the tanuki wrapper can be found at http:// wrapper.tanukisoftware.org/doc/english/properties.html. Installing the Enterprise Manager as a Windows Service improves its availability. An Enterprise Manager configured as a Windows Service has the following benefits: the Enterprise Manager Service will start automatically on machine reboot if the machine containing the Enterprise Manager shuts down, the Enterprise Manager Service will be cleanly shut down The following instructions assume you are familiar with configuring applications as Windows Services, and are familiar with using the Windows Services console.
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
Configure and Register Enterprise Manager as a Windows Service

Register Enterprise Manager as a Service
To register a single Enterprise Manager on the Windows machine running with Introscope-default JVM system parameters, you need only run a script and perform a small configuration. Before you register the Enterprise Manager as a Windows Service, make sure that the Enterprise Manager is already installed and runs properly in Console mode To register an Enterprise Manager instance as a Windows Service: 1. 2. Shut down the Enterprise Manager. In the file, IntroscopeEnterpriseManager.lax make sure the following property is blank:
lax.stdin.redirect
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:
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.
Deregister Enterprise Manager(s) Running as a Windows Service

There are several situations in which you would deregister the Enterprise Manager Service: before making changes to the EMService.conf properties file. to return the Enterprise Manager instance to Console control before you uninstall the Enterprise Manager instance To deregister an Enterprise Manager Service: 1. 2. Stop the Enterprise Manager Service and shut down the Windows Services GUI. Run <Introscope home>/DeregisterEMService.bat. the service will not be deleted, but instead will be "marked for deletion. This is standard Windows service behavior, and occurs because the Windows Registry lock prevents the service from being removed. When the machine is rebooted, the service is removed.
Note: If either the Enterprise Manager Service or the Windows Services GUI are active,
Changing Windows Service Properties

If you need to change any configuration properties in the EMService.conf file, first deregister the service. Make the changes, and then re-register the service for the changes to take effect.
Page 66
Configuring Enterprise Manager To Run As a z/OS Batch Job
Running the Enterprise Manager as a Windows Service

Use the standard controls in the Windows Services GUI to start, stop, and restart the Enterprise Manager running as a Windows Service.
Connecting to a Database Configured After Enterprise Manager Service Startup

If you have configured a database after the Enterprise Manager as a Windows Service has been started, you will need to restart the Service to be able to connect to the database.

To facilitate use of Introscope in the z/OS environment, it is desirable to run the product in a manner familiar to z/OS operations and development staff either as a z/OS batch job or started task. You can also run Introscope Enterprise Manager as a shell process if desired. This section describes running the Introscope Enterprise Manager as a batch job or started task. The following list contains a brief description of each section: Overview briefly describes the z/OS environment and the BPXBATCH utility. This section describes software prerequisites, security, authorization and address space size requirements. Installation describes the tasks necessary to customize the sample JCL and other files in preparation for running the Introscope Enterprise Manager as a batch job on the z/OS platform. Running the Introscope Enterprise Manager describes the activities required to run the Introscope Enterprise Manager as a batch job or started task on the z/OS platform. DB2 Considerations discusses some of the most important considerations for deploying the Introscope Enterprise Manager database on DB2 for z/OS.
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
Security and Authorization

Authorization is determined by the RACF profile associated with a users USERID. To successfully start the Introscope Enterprise Manager, a user must have authority to access the following resources: UNIX System Services as specified by the OMVS parameter in the RACF profile Introscope Enterprise Manager DB2 Tables EXEC PGM= BPXBATCH EXEC WILYPROC It is important to understand how the user is identified in various contexts: Batch When a user submits a batch job through the TSO/E or ISPF interface, the users TSO UserID and password are propagated to the batch job. Provided the submitted Batch JOB CARD does not explicitly contain a User and Password, the batch job acquires the same access authority as the TSO user. If User and Password are coded on the Batch JOB CARD, they override the UserID and Password of the TSO/E user. Started Task If the Introscope Enterprise Manager is initiated as a started task, it runs under the authorization of the STC user ID. A Site-specific algorithm may be used to relate the name of the started PROC to a particular UserID. You must make sure that the algorithm produces a UserID with the correct authorization to run the Introscope Enterprise Manager.
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:
export STEPLIB=DSNXXX.SDSNEXIT:DSNXXX.SDSNLOAD export LIBPATH=/usr/lpp/db2/db2710/lib:$LIBPATH export LD_LIBRARY_PATH=/usr/lpp/db2/db2710/lib:$LD_LIBRARY_PATH

3. The CLASSPATH must include the JDBC and SQLJ driver classes. The classpath in the
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.
GRANT EXECUTE ON PLAN DSNACLI TO PUBLIC

3. Set DSNAOINI to point to the CLI initialization file. The CLI initialization file provides information about DB2 subsystem names and additional configuration parameters. You can place the file either in an HFS file or in an MVS data set using one of the following statements:
export DSNAOINI=/usr/lpp/db2/db2510/dsnaoini export DSNAOINI=DSNxxx.CLIINI export DSNAOINI=DSNxxx.CLIINI(CONF1)

4. Make sure that the DB2 subsystem referenced in the CLI initialization file references the DB2 subsystem that you wish to connect to. DB2 subsystem names usually take the form DB2n where n is a unique qualifier.
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
Copying and Customizing Introscope Enterprise Manager Files

IntroscopeEnterpriseManager.properties and runem.sh are UNIX files that must be copied into the Hierarchical File System (HFS) on the z/OS platform. These files will be used by UNIX System Services and the Introscope Enterprise Manager respectively. Required changes to these files should be made using a UNIX-based editor such as vi. Do not use the ISPF editor because it does not properly handle insertion of characters that increase line length. WILYPROC is a z/OS file that will be used by the JES2 component of z/OS and by DB2 for z/OS. Changes to this file should be made using the ISPF editor.
Copying the Introscope Enterprise Manager UNIX files to HFS Files

Copy the IntroscopeEnterpriseManager.properties and runem.sh files into the Introscope installation directory, as shown in the following examples, where xxxx is the UID assigned to Wily Technology.
/u/xxxx/introscope6.0.1/runem.sh /u/xxxx/introscope6.0.1/config/ IntroscopeEnterpriseManager.properties
Customizing the Introscope Enterprise Manager Properties File

1. Open the u/xxxx/introscope6.0.1/config/
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:
introscope.enterprisemanager.db.driver=COM.ibm.db2zOS.sqlj.jdbc. DB2SQLJDriver introscope.enterprisemanager.db.url=jdbc:db2zOS: introscope.enterprisemanager.db.username=myUser introscope.enterprisemanager.db.password=myPassword

Verify that the driver is the correct one for this connection to DB2.
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.
Customizing runem.sh the UNIX Shell Script

Verify the version and release of DB2. The DB2 files in the runem.sh shell script reference DB2 V7.1.
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.
Customizing the z/OS PROC That Invokes BPXBATCH

1. Edit WILYPROC using the ISPF editor: On the ISPF command line, type CAPS OFF and press Enter. On the ISPF command line, type NUM OFF and press Enter. Set the IHOME parameter equal to the fully qualified path to the directory that contains the runem.sh. 2. The following statement is coded so that the batch job and the UNIX shell script will end within 20 seconds:
// PARM='SH nohup &IHOME/runem.sh &IHOME & sleep 20

In the unlikely event that the z/OS is too busy to complete the initiation of the Introscope Enterprise Manager within 20 seconds, the Introscope Enterprise Manager will not be started. If you encounter this problem, try increasing sleep time. 3. Modify the STDERR and STDOUT file names contained in the following statements to satisfy installation naming conventions:
//STDOUT //STDERR
DD PATH='/<path>/stdout', DD PATH='/<path>/stderr',
Copy WILYPROC into an active PROCLIB
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.
Running the Introscope Enterprise Manager

Executing the z/OS PROC
Running as a Started Task from the z/OS Console or SDSF
You may run the Introscope Enterprise Manager as an MVS started task (STC). A started task is a familiar, operator-friendly environment that allows the Introscope Enterprise Manager to be started, monitored and cancelled from the MVS console. In this case, the Introscope Enterprise Manager runs under the authorization of the STC user ID, thereby allowing assignment of specific authorities to the started task.
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.
Running as a Batch Job

The Introscope Enterprise Manager can also run as a batch job.
To run the Introscope Enterprise Manager as a batch job, submit the following JCL:
//jobname ISCOPE /*
JOB EXEC
installation jobcard parameters,NOTIFY=&SYSUID WILYPROC
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.
Verifying That the Introscope Enterprise Manager Is Running

The most accurate way to determine that the Introscope Enterprise Manager has started correctly is to view the STDOUT file. To view STDOUT, you must telnet into the z/OS and view the STDOUT file defined in the WILYPROC. The last line of the file should indicate that the Introscope Enterprise Manager has started. You can also determine that the Introscope Enterprise Manager has started from SDSF by following one of the procedures below: If you started the Introscope Enterprise Manager as a started task, on the DA screen you should see at least two active started tasks whose owner is the owner associated with the Introscope Enterprise Manager PROC. If you started the Introscope Enterprise Manager by submitting a batch job from your TSO session, look for two active tasks with your TSO USERID as the owner. You may also see the job that invoked the WILYPROC as well as the OMVS shell script. These two entries will disappear from the list, once the Introscope Enterprise Manager has started. The owner of your TSO session is also your TSO/E USERID. Do not mistake your TSO/E session for one of the Introscope Enterprise Manager tasks.
Page 73
Starting the Introscope Enterprise Manager automatically

To can start the Introscope Enterprise Manager automatically when JES2 starts: 1. Place the following statement in JES2PARM:
$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
Configuring Enterprise Manager To Run As a z/OS Batch Job WT_TMP_Q_5
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.
Database Implementation Considerations

Sample database creation script is based on the assumptions listed above, particularly the assumptions related to the WT_Metric table. Review these assumptions carefully. If your environment will be substantially different, you should reevaluate associated database creation script parameters.
Customizing the db2_zOS.sql File

Using the ISPF editor, customize the database creation script provided in db2_zOS.sql.
Customizing the tablespaces and the sample CREATE TABLE statements

When customizing the tablespaces, follow these rules: The WT_Metric table data should have its own segmented tablespace. The WT_Metric_U1 index should also have its own dedicated tablespace. The WT_Metric table and its index should be placed on high-speed devices. The physical path to the data should be on a different path from the physical path to the index. These tablespaces may be defined as either DB2 managed or user managed.
Tables and indexes

All tables and indexes should be defined in the Wily database not the default database. All tables should be assigned to a specific storage group or tablespace. All CREATE INDEX statements should contain a USING clause designating either a specific storage group or VCAT.
Page 75
Configuring Introscope Security and Permissions

Introscope provides external authentication support, and granular user permissions for individual Domains and Enterprise Manager administration. This chapter gives you a summary of how to configure Introscope Domains and users in the following sections: Overview Configuring and Managing Domains Configuring User Authentication Defining User Permissions Agent Failover and Domain/User Configuration
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
Configuring and Managing Domains

A Domain in Introscope is a partition of Agents and monitoring logic. Agents are mapped to a Domain using a Perl5 regular expression in the domains.xml file.
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
Configuring and Managing Domains
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.
Domain Attributes and Syntax

The following table contains the attributes for defining a Domain: TABLE 7. Domain Attributes Modifier
name description agent mapping
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>
Domain Creation Rules

Please note the following rules about creating Domains in the domains.xml file: Domain creation must follow valid xml file rules Domain names are case sensitive any Domain must be placed inside the root XML domains element Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 77
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
Creating a Domain and Mapping Agents

1. 2. Open the file, <Introscope home>/config/domains.xml in an xml editing program. Define any Domains, using the syntax and attributes, and following the rules shown in the previous sections.
Note: All XML tags are case sensitive.

3. 4. Save and close the domains.xml file. Restart the Enterprise Manager so it can load the new Domain(s). Manager will not start.
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.
Associating Management Modules With Domains

When you create new Management Modules, you can choose which Domains will contain them. You associate Management Modules with Domains by creating directories that correspond to the names of the Domains you defined in domains.xml, then moving the Management Modules into the new directories. 1. In <Introscope home>/config/modules, create a directory that corresponds to the Domain name you created in the previous section. For example, if you created a Domain named PetstoreA, in this step, you would create a directory also named PetstoreA, as in the following example:
<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.
Adding Sample Management Module to Newly Created Domains

When you create a new Domain, it does not contain any Management Modules. If you want the newly created Domain to show the default Sample Dashboards, you will need to copy the Sample Management Module into the newly created Domain. To copy the Sample Management module into the newly created Domain: 1. In the directory, <Introscope home>/config/modules/, copy the SampleManagementModule.jar file to the appropriate modules directory in the
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
Changing the Domain Mapping of an Agent

Remapping an Agent to a different Domain, (either after deleting a Domain, or merging two Domains), has the following ramifications: If an Agent mapped to a deleted Domain is not reassigned and is still reporting, it will appear under the SuperDomain If an Agent has associated SNMP collections, the SNMP MIB will have to be republished When an Agent is moved into a different Domain, all shutoff information within that Agent is lost.
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
Configuring and Managing Domains 5. Restart the Enterprise Manager.
Merging Two Domains

Merging two Domains involves merging all Agent mapping information into one Domain, and moving any associated Management Modules under one Domain. To merge two Domains: 1. 2. 3. 4. 5. 6. Shut down the Enterprise Manager. Open the <Introscope home>/config/domains.xml file. Under the source Domain (for example, Domain A), copy the Agent mapping XML code information. Under the target Domain (for example, Domain B), paste the Agent mapping XML code information. Delete Agent mapping XML code from the source Domain (e.g., Domain A). Move any Management Modules from the source Domain (for example, Domain A) directory in <Introscope home>/config/modules/ to the target Domain (e.g., Domain B).
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.
Moving a Domain From One Introscope Installation to Another

Moving a Domain Between Installations To Clone the Domains
If the target installation Domain configuration is exactly the same as the source installation (all Domains defined in the domains.xml file are going to be exactly the same), use the following steps: 1. 2. Copy the <Introscope home>/config/domains.xml file in the source installation over to the same directory in the target installation. Copy the <Introscope home>/config/shutoff/ MetricShutoffConfiguration.xml in the source installation over to the same directory in the target installation. Copy the contents of the <Introscope home>/config/modules/<domain> directory from the source installation to the target installation. Restart the Enterprise Manager.
3. 4.
Moving a Domain Between Non-cloned Installations

If the Domain configurations between the old and new installations vary slightly, use the following steps:
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.
Configuring User Authentication

Introscope offers an extensible authentication system that can integrate with existing systems through LDAP. If you do not use an external authentication mechanism, authentication is configured locally by referencing the users stored in the users.xml file. to use local authentication, follow the instructions in this section, then proceed to Defining User Permissions, page 88, to define permissions for each user. If you will be using an external authentication mechanism, you can skip this section and use the instructions in Configuring External Authentication, page 84.
Local User Authentication Overview

Local authentication is used by default in Introscope. The authentication method used is configured in the IntroscopeEnterpriseManager.properties file. If local authentication is used, the Enterprise Manager references a local authentication properties configuration file, which then refers to users.xml where users and passwords are stored. Local authentication changes are dynamic: when a user attempts to log in, login values are compared to users.xml file each time an authentication request is made. Changes to the contents of the users.xml file do not require an Enterprise Manager restart. Introscope provides an optional mechanism for encoding passwords for use in local authentication. There are several steps involved in setting up local authentication: making sure Introscope is configured to use local authentication changing the location of the users.xml file if desired defining users in the users.xml file generating encoded passwords (optional)
Page 81
Configuring Local Authentication

Configuring Enterprise Manager to Use Local Authentication
Introscope uses local authentication by default. To check that local authentication is used: 1. 2. 3. Open the file, <Introscope home>/config/ Locate the Authentication Providers section. For the property,
IntroscopeEnterpriseManager.properties.
introscope.enterprisemanager.authentication.providers, make sure

that local authentication is used, as in the following example:
introscope.enterprisemanager.authentication.providers=local
4. Save changes to this file if necessary, and restart the Enterprise Manager.
Configuring Location or Name of Local Authentication File

Local authentication using users.xml doesnt require configuration or any shared security service at your site. By default, this file is located at <Introscope home>/ config/users.xml. However, you may wish to configure the name or location of this username/password file. Because you can specify the name and location of this file, several Enterprise Managers could share the same authentication file.
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
Here is the syntax for configuring a user:
<users> <user name="username" password="password"> </user> </users>
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.

3. 4. Repeat step two for any additional users required. Save and close the users.xml file.
Note: If there are any syntax or other errors in the users.xml file, the Enterprise
Manager will not start.
Generating Encoded Passwords (Optional)

The passwords stored in the users.xml file used by the local authentication mechanism are currently stored in clear text by default. Introscope now provides the option to generate and use encoded passwords. You can generate encoded passwords using the MD5Encoder script, now installed with Introscope. This script takes as input a clear text password and returns an encoded password, which you copy and paste as the user password in the users.xml file. When authenticating a username/password at login, the password is encoded and then checked against the encoded copy of the password stored in memory. To generate an encoded password: 1. In the users.xml file, change the md5EncodedPasswords attribute of the root users element to true, as in the following example:
<?xml version="1.0" encoding="UTF-8"?> <users xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="users0.2.xsd" version="0.2" md5EncodedPasswords="true">

Configuring External Authentication
Note: The md5EncodedPasswords attribute is an optional attribute. If it is not

specified, it defaults to false for backwards compatibility. 2. Run the following script found in the <Introscope home> directory, with the script name, a space, then the password to encode:
MD5Encoder.bat <password> for Unix, MD5encoder.sh <password>
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:
<user name="JoJoPurla" password="dfa8bd148a83a6cc5fe937e82f399d"> </user>

4. Save changes to users.xml file.
Default User Configuration

The default user configuration defines the following users: Admin, with no password Guest, with no password
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.

If you already have a system to authenticate user logins, Introscope can interface with that system through LDAP. By default, Introscope uses local authentication through the users.xml file. However, an LDAP extension is also provided, and can be used instead of local authentication, once the extension is configured for use with a specified LDAP server.
Configuring LDAP Authentication

Introscopes LDAP authentication works with the following supported v3 LDAP servers: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 84
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.
Configuring Enterprise Manager to Use LDAP Authentication

1. 2. 3. 4. Make sure the LDAP extension is present in the following location: <Introscope
home>/ext/LDAPAuthenticationExtension.jar.
Open the file, <Introscope home>/config/ Locate the Authentication Providers section. For the property,
introscope.enterprisemanager.authentication.providers, specify that

LDAP will be used as the authentication provider, as in the following example:
introscope.enterprisemanager.authentication.providers=ldap
5. Check that the following LDAP configuration properties are present and uncommented:
introscope.enterprisemanager.authentication.extensionName.ldap=WilyLDAP introscope.enterprisemanager.authentication.controlFlag.ldap=REQUIRE D introscope.enterprisemanager.authentication.configFile.ldap=config/ LDAPAuthenticationExtension.properties

6. Save changes to this file, and restart the Enterprise Manager.
Configuring LDAP Authentication Extension

Every site's LDAP server is configured uniquely, so you must obtain LDAP configuration information from the site's LDAP administrator before attempting to configure the following LDAP properties. LDAP properties are configured the file, <Introscope home>/config/ LDAPAuthenticationExtension.properties.
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
Note: If you are using SSL, the SSL

LDAP port should be part of the server URL. authentication.extension.ldap.useSSL authentication.extension.ldap.bindName authentication.extension.ldap.bindPasswo rd authentication.extension.ldap.bindAuthen tication
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.
false IntroscopeLDAPUse r password123
simple
authentication.extension.ldap.user.nameS uffix authentication.extension.ldap.user.baseD N authentication.extension.ldap.user.scope Depth authentication.extension.ldap.user.userna meAttribute authentication.extension.ldap.user.userO bjectQuery
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://
@dev.com cn=Users, dc=dev, dc=com subtree userPrincipalName (&(userPrincipalNa me=%u)(objectclas s=user))
authentication.extension.ldap.serverCertif icate
blank
java.sun.com/j2se/1.4.2/docs/ index.html).
Page 86
LDAP Configuration Examples

The following section contains examples of LDAP configurations on each of the supported LDAP Servers. Please note that the following code samples are provided for example only; every site's LDAP server is configured uniquely.
IBM Directory Server

The following example shows LDAP properties configured for use with the IBM Directory Server, using SSL.
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
SunONE Directory Server

The following example shows LDAP properties configured for use with the Sun ONE Directory Server, using SSL.
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
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
Defining User Permissions

Setting up user permissions allows you to define greater deployment security by: defining user permissions within a specific Domain defining user permissions for the Enterprise Manager User permissions determine what tasks the user can perform including configuring monitoring logic in the Workstation, or Enterprise Manager administration tasks. Permissions in Introscope are defined for Domains and the Enterprise Manager. Users can be granted permissions to either or both. Domain permissions are configured in <Introscope home>/config/
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
Domain Permissions Defined

The following table defines the Domain permissions available for users in a Domain. TABLE 9. Domain Permissions Permission
read
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
User can start a Transaction Trace Session for an Agent.
Note: This permission also requires a user to have read

permission. historical_agent_control User can mount and unmount Agent(s).

permission.
Page 89
Permission
live_agent_control
Definition
User can shut off reporting for Metrics, Resources, and Agent within Domain

permission. full User has all possible permissions for Domain.
Here is the syntax for configuring user permissions for a Domain:
<grant user="username" permission="permission">
Defining Domain Permissions

To define Domain permissions for a user: 1. 2. Open the <Introscope home>/config/domains.xml file in an xml editing program. For each Domain, define permissions for each user, with the above attributes and syntax.

3. 4. Repeat for any additional users required. Save and close the domains.xml file. Manager will not start.
Note: If there are any syntax or other errors in the domains.xml file, the Enterprise
Default Domain Configuration

In the default Domain configuration: the user, Admin has full permission in the SuperDomain the user, Guest has read (view only) permission in the SuperDomain
Configured Domain Example

The following configured Domain permissions example gives Domain permissions to the following users: bsmith, full permission in HRApplication Domain fjones, read and run_tracer permissions in HRApplication Domain jlo, write permission in SuperDomain pdiddy, read permission in SuperDomain The domains.xml file would look like the following example:
<?xml version="1.0" encoding="UTF-8"?> <domains xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="domains0.2.xsd" version="0.2">

<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>
Domain Permissions and the Explorer Tree

The Explorer tree will look different to users with different Domain permissions: User with SuperDomain permission (at least read permission) can view the contents of all defined Domains in the Explorer tree. Users with permissions for multiple Domains will see Domain information for those Domains in the Explorer tree. Users with permissions for only one Domain will not see Domain information in the Explorer tree, they will only see the folders for Metrics and Management Modules.
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
Server Permissions Rules

a user can have multiple permissions for the Enterprise Manager if a user has multiple permissions, use one line for each user/permission pair
Page 91
Server Permissions Defined

The following table defines the server permissions available. TABLE 10. Server Permissions Permission
shutdown purge_metrics publish_mib
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: In order to have a MIB to publish, a user must create a

SNMP Collection. This task requires write access to the Domain the SNMP Collection will be saved to. full User has all possible server permissions.
Here is the syntax for configuring user permissions for a server:
<grant user="username" permission="permission">
Defining Server Permissions

To define server permissions for a user: 1. 2. Open the <Introscope home>/config/server.xml file in an xml editing program. Define permissions for each user, with the above attributes and syntax.

3. 4. Repeat for any additional users required. Save and close the server.xml file. Manager will not start.
Note: If there are any syntax or other errors in the server.xml file, the Enterprise
Default Server Configuration

In the default Server configuration, the user Admin user has full permission.
Configured Server Example

In the following example, we want to give permissions to the following users: bsmith, shutdown permission tjones, purge_metrics and publish_mib permissions The server.xml file would look like the following example:
<?xml version="1.0" encoding="UTF-8"?> <server xmlns:xsi="http:// www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="users0.1.xsd" version="0.1">

<grant user="bsmith" permission="shutdown" /> <grant user="tjones" permission="purge_metrics" /> <grant user="tjones" permission="publish_mib" /> </server>
Agent Failover and Domain/User Configuration

If you want to take advantage of the Agent Failover functionality and have users and passwords defined, you must make sure that the information in the domains.xml, server.xml and users.xml files is in sync across the specified failover Enterprise Managers.
Note: For more information on Agent Failover, see Agent Failover, page 173.
Page 93
6 Configuring Java Applications With Introscope

After you have installed the Enterprise Manager and Workstation, you are ready to install and configure the Introscope Agent and Introscope-enable your Java Applications. Use the table below to direct you to the appropriate chapter for your deployment. Each of the following chapters contains instructions for: Installing Introscope Agent Choosing a ProbeBuilder configuration option Configuring Basic Agent Settings
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
Use the instructions in this chapter

Chapter 7, Configuring WebLogic Server With Introscope Chapter 8, Configuring WebSphere Application Server With Introscope Chapter 9, Configuring WebSphere on z/OS With Introscope Chapter 10, Configuring Sun ONE Application Server With Introscope Chapter 11, Configuring Oracle Application Server 10g With Introscope Please contact Wily support to obtain Japanese installation instructions. Chapter 12, Configuring SAP NetWeaver With Introscope Chapter 13, Configuring Other Application Servers or Applications With Introscope Chapter 14, Configuring the Java Applications Manually With ProbeBuilder
Page 94
7 Configuring WebLogic Server With Introscope

This section describes how to configure (Introscope-enable) Java Applications with WebLogic Server in the following sections: Configuring Introscope With WebLogic Overview Installing Introscope Agent With WebLogic ProbeBuilder Configuration Options Configuring Basic Agent Settings for WebLogic Additional Configuration Options
Configuring Introscope With WebLogic Overview

There are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager: install the Introscope Agent Introscope-enable the application code using one of the ProbeBuilder configuration options configure basic Introscope Agent settings
Installing Introscope Agent With WebLogic

To install the Introscope Agent on WebLogic: 1. 2. Make sure that the WebLogic Server version 6.1 or higher and any required patches have been installed. Find the appropriate WebLogic installer file:
IntroscopeAgentInstall6.0.1weblogic.unix.tar IntroscopeAgentInstall6.0.1weblogic.windows.zip IntroscopeAgentInstall6.0.1weblogic.zOS.tar IntroscopeAgentInstall6.0.1weblogic.os400.zip

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
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)
ProbeBuilder Configuration Options

A Java application is monitored by adding Probes to the bytecode. The Probes then report information to the Introscope Agent, and the Agent reports that information to the Enterprise Manager. The tool used to add Probes is called ProbeBuilder. There are three ProbeBuilder configuration options that can be used to install probes into the application to be monitored: JVM AutoProbe Using the JVM AutoProbe option dynamically Introscope-enables all classes loaded by the JVM. Application Server AutoProbe Using the Application Server AutoProbe option dynamically Introscope-enables all applications loaded by the application server. Manual ProbeBuilder (using either the ProbeBuilder Wizard or Command-Line Probebuilder) The Manual ProbeBuilder option is a manual process which Introscope-enables classes on disk before the application server is run. Availability of these options will differ depending on the WebLogic application server version. The JVM AutoProbe and Application Server AutoProbe options install probes dynamically into application code as it is loaded. Whenever possible, using ProbeBuilder through AutoProbe will save time and provide ease of use that Introscope-enabling an application manually does not.
Choosing ProbeBuilder Configuration Option

The following table details the ProbeBuilder options available for each WebLogic Server version and JVM combination. To find the appropriate ProbeBuilder method: 1. 2. 3. Choose the row containing your WebLogic Server version. Choose a ProbeBuilder configuration option. Locate the instructions: If using JVM AutoProbe, locate the JVM you are running, and use the instructions associated with that JVM If using Application Server AutoProbe or Manual ProbeBuilder, use the instructions associated with that option. For example, if you have the following environment, WebLogic Server version 8.1 JVM AutoProbe Sun JVM
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
Application Server Version
ProbeBuilder Configuration Option
JVM
Use the Instructions In This Section
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
JVM AutoProbe With WebLogic Using WebLogic JRockit, page 100
WebLogic 6.1SP3
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
Page 98
JVM AutoProbe Using Java 5.0 JVM

The following instructions work Java 5.0 JVM: 1. Add the following command-line option to the JVM command line:
-javaagent:<path-to-Agent.jar>
2. Proceed to the section, Configuring Basic Agent Settings for WebLogic, page 102 to configure the Agent profile.
JVM AutoProbe With WebLogic Using Sun or IBM JVM

There are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM: create an AutoProbe connector that will work with your JVM 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.
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.
Creating an AutoProbe Connector

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to run WebLogic. There are two ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool 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:
java -jar CreateAutoProbeConnector.jar -current

specifying the JVM by passing the JVM directory on the command line:
java -jar CreateAutoProbeConnector.jar -jvm <directory>

3. The output is a file with the form:
wily/connectors/AutoProbeConnector.jar
Running AutoProbe Connector

After you have created the AutoProbe Connector, you must modify the bootstrap classpath. The following instructions are valid for all other WebLogic versions: 1. Edit the bootstrap classpath in the application startup script (such as
startMedRecServer.cmd) using the following command to include the AutoProbeConnector.jar you created:
ProbeBuilder Configuration Options all JVMs but IBM JVM 1.2.x:
-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>:<path-toAgent.jar> -Xbootclasspath/p:wily/connectors/ AutoProbeConnector.jar:<path-to-Agent.jar>

for IBM JVM 1.2.x
-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.
JVM AutoProbe With WebLogic Using HP HotSpot JVM

The following instructions work with HP HotSpot JVM: 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>
JVM AutoProbe With WebLogic Using WebLogic JRockit

The following instructions work with WebLogic JRockit: 1. Start WebLogic JRockit with the following command line options: For WebLogic 9.0 with JRockit 5.0:
JAVA_VENDOR=Bea JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:<path-to-Agent.jar>

For WebLogic JRockit 8.1:
-Xbootclasspath/a:<path-to-Agent.jar> -Xmanagement:class=com.wily.introscope.api.jrockit. AutoProbeLoader Note: The above command should be all on one line.
ProbeBuilder Configuration Options For WebLogic JRockit 7.0:
-Djrockit.preprocessor.class= com.wily.introscope.api.weblogic.PreProcessor -Xbootclasspath/a:<path-to-Agent.jar>

Application Server AutoProbe With WebLogic

The following sections describe how to configure your deployment to use Application Server AutoProbe.
Application Server AutoProbe With WebLogic 8.1

The following instructions work with WebLogic 8.1: 1. 2. Edit the classpath in the application startup script (such as
startMedRecServer.cmd) to include the wily/Agent.jar file.

Also in the application startup script, set the following property on the Java command line 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.

The following instructions work with WebLogic 7.0: 1. 2. Edit the Java classpath in the WebLogic Server startup script (startWLS.cmd) to include the wily/Agent.jar file. Set the following property on the Java command line (in the same startup script
startWLS.cmd) with the -D option. This will activate Introscope AutoProbe: -Dweblogic.classloader.preprocessor= com.wily.introscope.api.weblogic.PreProcessor
Application Server AutoProbe With WebLogic 6.1 SP3

The following instructions work with WebLogic 6.1 SP3: 1. 2. Edit the Java classpath in the WebLogic startup script (such as
StartPetstore.cmd) to include the wily/Agent.jar file.

Set the following property on the Java command line with the -D option. This will activate Introscope AutoProbe: Page 101
Configuring Basic Agent Settings for WebLogic
-Dweblogic.classloader.preprocessor= com.wily.introscope.api.weblogic.PreProcessor

The following instructions work with WebLogic 6.1: 1. 2. Edit the Java classpath in the WebLogic startup script to include the wily/
Agent.jar file.
Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 102.
Configuring HTTP Servlet Tracing For Application Server AutoProbe

If you are using Application Server AutoProbe, you will need to configure some Tracer Groups in the toggles-full.pbd and toggles-typical.pbd files so servlet data will be collected. This process involves turning one Tracer Group on and turning another off. 1. 2. 3. Locate the <WebLogic home>/wily/toggles-full.pbd. Go to the HTTP Servlets Configuration section. Turn off the HTTPServletTracing Tracer group by placing a pound sign at the beginning of the line, as in the following example:
#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.
Configuring Basic Agent Settings for WebLogic

The following section details how to configure the Introscope Agent. The Agent settings are found in the file, wily/IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile file as the Agent profile.
Agent Profile Location

Introscope looks for the Agent profile in a set sequence of three locations: the location defined in the system property,
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
Defining Agent Profile Location

You can customize the location of the Agent profile, as long as you define the new location using one of the following methods: 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.
Moving IntroscopeAgent.profile and Directives Files Together

You can rename and/or move the IntroscopeAgent.profile file to another directory, such as the application directory. However, if you move the IntroscopeAgent.profile to another location, you should also move the directives files (.pbd and .pbl files), as they are referenced relative to the location of the Agent profile.
Configuring Introscope Agent

Basic Agent properties you need to set are: Enterprise Manager host and port Agent Name Process Name
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
Additional Configuration Options
Property
introscope.agent.enterprisemanager.transport .tcp.host.DEFAULT
Value and Description

The host setting should be either the host name or IP address of a machine with an Enterprise Manager on it.
Note: This property name should be on one

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,
Manager. See Uninstalling Introscope, page 54. line.
introscope.enterprisemanager.por t.agentlistener in the introscopeEnterpriseManager.prop erties file for each matching Enterprise
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.

There are several additional WebLogic configuration options. You can configure Introscope to extract WebLogic performance data through the JMX management interface, or configure the Agent to find its name automatically from the WebLogic application server instance. Introscope can also collect WLDF data from a WebLogic 9.0 application server. However, all of these options require a WebLogic startup class to be configured. Use the following instructions to configure the startup class, then view the information in the references in the next section to configure optional features that provide additional performance data. Note that only one startup class is necessary to provide access to JMX and AutoNaming capabilities.
Page 104
Creating a WebLogic Startup Class

The following section describes how to create a startup class in WebLogic 8.1. Consult your WebLogic documentation for instructions on creating a startup class in other versions, or for more information.
Configuring a Startup Class In WebLogic 8.1

1. 2. 3. 4. Open the WebLogic 8.1 Administrative Console. In the left pane, expand the Deployments folder. Click the Startup & Shutdown folder. The Startup and Shutdown page appears. Click Configure a New Startup Class. The Configuration tab is shown. 5. In the Name field, enter:
Introscope Startup Class

6. In the ClassName field, enter:
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.
10. Restart the application server.
Optional WebLogic Configurations

See the following sections for information on optional WebLogic configurations. Agent Naming Options, page 169 JMX Filters For Obtaining Advanced Performance Data, page 182 For general Introscope additional configuration options, see, Chapter 15, Optional Introscope Configurations.
Page 105
8 Configuring WebSphere Application Server With Introscope

This section describes how to configure (Introscope-enable) a Java Application in the following sections: Configuring Introscope With WebSphere Overview Installing Introscope Agent on WebSphere ProbeBuilder Configuration Options Configuring Basic Agent Settings on WebSphere
Configuring Introscope With WebSphere Overview

Installing Introscope Agent on WebSphere

To install the Introscope Agent on WebSphere: 1. 2. Make sure that the WebSphere Application Server 4.0 or higher and any required patches have been installed. Find the WebSphere installer file for your platform:
IntroscopeAgentInstall6.0.1websphere.unix.tar IntroscopeAgentInstall6.0.1websphere.windows.zip IntroscopeAgentInstall6.0.1websphere.zOS.tar IntroscopeAgentInstall6.0.1websphere.os400.zip

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

A Java application is monitored by adding Probes to the bytecode. The Probes then report information to the Introscope Agent, and the Agent reports that information to the Enterprise Manager. The tool used to add Probes is called ProbeBuilder. There are three ProbeBuilder configuration options that can be used to install probes into the application to be monitored: JVM AutoProbe Using the JVM AutoProbe option dynamically Introscope-enables all classes loaded by the JVM. Application Server AutoProbe Using the Application Server AutoProbe option dynamically Introscope-enables all applications loaded by the application server. Manual ProbeBuilder (using either the ProbeBuilder Wizard or Command-Line Probebuilder) The Manual ProbeBuilder option is a manual process which Introscope-enables classes on disk before the application server is run. The JVM AutoProbe and Application Server AutoProbe options install probes dynamically into application code as it is loaded. Whenever possible, using ProbeBuilder through AutoProbe will save time and provide ease of use that Introscope-enabling an application manually does not.

The following table details the ProbeBuilder options available for each WebSphere Application Server version and JVM combination. To find the appropriate ProbeBuilder method: 1. 2. 3. Choose the row containing your WebSphere Application Server version. Choose a ProbeBuilder configuration option. Locate the instructions: If using JVM AutoProbe, locate the JVM you are running, and use the instructions associated with that JVM If using Application Server AutoProbe or Manual ProbeBuilder, use the instructions associated with that option. For example, if you have the following environment, WebSphere Application Server version 5.0 JVM AutoProbe IBM JVM you would use the instructions in the section, JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108.
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

WebSphere 6.0/5.1/5.0
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
JVM AutoProbe With WebSphere Using Sun or IBM JVM

There are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM: create an AutoProbe connector that will work with your JVM Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 108
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.

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to run WebSphere. There are two ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool 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:


Running the AutoProbe Connector

After you have created the AutoProbe Connector, you must modify the bootstrap classpath.
JVM AutoProbe With WebSphere Version 6.0/5.1/5.0

The following instructions work with WebSphere 6.0, 5.1 or 5.0: 1. In WebSphere, start the Administrators Console, and go to the JVM Settings section for the application server you want to modify: For WebSphere 6.0: click Application Servers > <your server> > Java and Process Management > Process Definition > Java Virtual Machine. For WebSphere 5.1/5.0: click Application Servers > <your server> > Process Definition > Java Virtual Machine 2. Set the Generic JVM Arguments field to specify the bootstrap classpath:
-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.
Modifying Java2 Security Policy (optional)

If you have Java2 Security enabled, you may need to add the following permissions to your Java2 Security Policy.
Edit the file, <WebSphere home>/properties/server.policy to include the lines:
// 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).
JVM AutoProbe With WebSphere Version 4.0

The following instructions work with WebSphere 4.0: 1. 2. 3. In WebSphere, start the Administrators Console, and go to the JVM Settings section for the application server you want to modify. Click Advanced JVM Settings. A new window will open. In the Boot classpath (prepend) field, enter the following command:
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.
JVM AutoProbe With WebSphere Using HP HotSpot JVM

The following instructions work with HP HotSpot JVM: Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
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:
3. Proceed to the section, Configuring Basic Agent Settings on WebSphere, page 113 to configure the Agent profile.
Application Server AutoProbe With WebSphere

Application Server AutoProbe With WebSphere 6.0/5.1/5.0

The following instructions work with WebSphere versions 5.0, 5.1 and 6.0: 1. 2. Add the Agent.jar to the runtime extensions directory for WebSphere at <product_installation_root>/lib/ext. In WebSphere, start the Administrators Console, and go to the JVM Settings section for the application server you want to modify: For WebSphere 6.0, click Application Servers > <your server> > Java and Process Management > Process Definition > Java Virtual Machine. For WebSphere 5.0, click Application Servers > <your server> > Process Definition > Java Virtual Machine. 3. Set the Generic JVM Arguments 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 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"; };
Application Server AutoProbe With WebSphere 4.0 (Distributed)

The following instructions work with WebSphere 4.0: 1. 2. 3. Add the Agent.jar to the runtime extensions directory for WebSphere at <product_installation_root>/lib/ext. In WebSphere, start the Administrators Console, and go to the JVM Settings section for the application server you want to modify. Add the following two system properties: Page 112
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.

If you are using Application Server AutoProbe, you will need to configure some Tracer Groups in the toggles-full.pbd and toggles-typical.pbd files so servlet data will be collected. This process involves turning one Tracer Group on and turning another off. 1. 2. 3. Locate <WebSphere home>/wily/toggles-full.pbd. Go to the HTTP Servlets Configuration section. Turn off the HTTPServletTracing Tracer group by placing a pound sign at the beginning of the line, as in the following example:
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.
Configuring Basic Agent Settings on WebSphere

The following section details how to configure the Introscope Agent. The Agent configuration settings are found in the file, <WebSphere home>/wily/ IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile file as the Agent profile.

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
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.

You can customize the location of the Agent profile, as long as you define the new location using one of the following methods: if not already defined in the WebSphere console, 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.


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
Disabling Automatic Agent Naming for WebSphere 4.0

Agent automatic naming is enabled by default for all WebSphere platforms, but is not supported in WebSphere 4.0. 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
Property
introscope.agent.enterprisemanager.t ransport.tcp.host.DEFAULT
Note: This property name should be on one line.

introscope.agent.enterprisemanager.t ransport.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.agentlistene r 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.

There are several additional WebSphere configuration options. You can configure Introscope to extract WebSphere performance data through the JMX and PMI management interfaces, or configure the Agent to find its name automatically from the WebSphere application server instance. However, both of these options require a WebSphere custom service to be configured. Note that only one custom service is necessary to provide access to JMX, PMI and AutoNaming capabilities. Use the following instructions to configure the custom service, then view the information in the references in the next section to configure optional features that provide additional performance data.
Page 115
Configuring a Custom Service in WebSphere

The following section describes how to create a custom service in WebSphere 5.0. Consult your WebSphere documentation for instructions on creating a custom service in previous versions, or for more information.
Configuring a Custom Service in WebSphere 6.0/5.0

1. 2. Open the WebSphere Administrative Console. Select the server you'd like to configure, then: For WebSphere 6.0, click Administration, then Custom Services. For WebSphere 5.0, click Custom Services. 3. Click New to add a new Custom Service, then: For WebSphere 6.0, check the box for Enable service at server startup For WebSphere 5.0, check the Startup checkbox. 4. In the Classname field, enter:
com.wily.introscope.api.websphere.IntroscopeCustomService
5. In the Display Name field, enter:
Introscope Custom Service

6. In the Classpath field, enter:
<WebSphere home>/wily/WebAppSupport.jar
7. 8. Click OK. Restart the application server.
Optional WebSphere Configurations

See the following sections for information on optional WebSphere configurations. Agent Naming Options, page 169 JMX Filters For Obtaining Advanced Performance Data, page 182 Advanced WebSphere Performance Data, page 189 For general Introscope additional configuration options, see, Chapter 15, Optional Introscope Configurations.
Page 116
9 Configuring WebSphere on z/OS With Introscope

This chapter describes how to configure Introscope 6.0.1 for use with WebSphere version 5.0, 5.1 or 6.0 on the z/OS platform. It assumes that you are thoroughly familiar with configuration of WebSphere on z/OS. Information is provided in the following sections: Installing Introscope Agent on WebSphere on z/OS ProbeBuilder Configuration Options Configuring HTTP Servlet Tracing For Application Server AutoProbe
Configuring Introscope With WebSphere on z/OS Overview

There are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager: install the Introscope Agent Introscope-enable the application code using one of the ProbeBuilder configuration options configure basic Introscope Agent settings You may also choose to configure to run your Enterprise Manager as a z/OS batch job.
Installing Introscope Agent on WebSphere on z/OS

To install the Introscope Agent on WebSphere on z/OS: 1. 2. Make sure that the WebSphere Application Server 5.0 or higher and any required patches have been installed. Find the WebSphere installer file:
IntroscopeAgentInstall6.0.1websphere.zOS.tar
WebAppSupport.jar connectors/CreateAutoProbeConnector.jar Several .pbd and .pbl files (ProbeBuilder Directives and List files)
Page 117


The following table details the ProbeBuilder options available for each WebSphere Application Server version and JVM combination. To find the appropriate ProbeBuilder method: 1. 2. 3. Choose the row containing your WebSphere Application Server version. Choose a ProbeBuilder configuration option. Locate the instructions: If using JVM AutoProbe, locate the JVM you are running, and use the instructions associated with that JVM If using Application Server AutoProbe or Manual ProbeBuilder, use the instructions associated with that option. For example, if you have the following environment, WebSphere Application Server version 5.0 on z/OS JVM AutoProbe IBM JVM you would use the instructions in the section, JVM AutoProbe With WebSphere Using IBM JVM, page 119.
Page 118
JVM
WebSphere 5.x and 6.0 on z/OS

JVM AutoProbe IBM JVM AutoProbe With WebSphere Using IBM JVM, page 119
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
JVM AutoProbe With WebSphere Using IBM JVM

There are two steps required to configure and use JVM AutoProbe with IBM JVM: create an AutoProbe connector that will work with your JVM 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.

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to run WebSphere. There are several ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool When using WebSphere version 6.0 or above, you must run the CreateAutoProbeConnector.jar tool against the Java JRE that is now embedded inside the WebSphere version 6.0 distribution. For example, for WebSphere version 6.0, you would issue the following command:
java -jar CreateAutoProbeConnector.jar -jvm <Websphere_Install_directory/java>

For example:
java -jar CreateAutoProbeConnector.jar -jvm /WebSphere/V6R0M0/ AppServer/java

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:



After you have created the AutoProbe Connector, you must modify the bootstrap classpath.
JVM AutoProbe With WebSphere 5.x and 6.0 for z/OS

The following instructions work with WebSphere 5.x and 6.0 for 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 Java Virtual Machine. Set the Generic JVM Argument field to specify the bootstrap classpath:
5. Click on Custom Properties and add the following two name value pairs: define the Agent profile location
name: com.wily.introscope.agentProfile value: <path-to-IntroscopeAgent.profile>

add a property for EBCDIC conversion
name: com.wily.introscope.default.encoding value: Cp1047

6. Apply the changes in the Administrators Console.
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"; };
Application Server AutoProbe With WebSphere for z/OS

This section contains instructions specifically for configuring Application Server AutoProbe for WebSphere on z/OS.
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:
name: com.wily.introscope.default.encoding value: Cp1047
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.

// 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 for WebSphere

If you are using Application Server AutoProbe, you will need to configure some Tracer Groups in the toggles-full.pbd and toggles-typical.pbd files so servlet data will be collected. This process involves turning one Tracer Group on and turning another off. 1. 2. 3. Locate <WebSphere home>/wily/toggles-full.pbd. Go to the HTTP Servlets Configuration section. Turn off the HTTPServletTracing Tracer group by placing a pound sign at the beginning of the line, as in the following example:
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.

The following section details how to configure the Introscope Agent. Agent configuration settings are found in the file, IntroscopeAgent.profile, located in the <working directory>/wily directory. You will need to do this for each managed instance of WebSphere: Basic Agent properties you need to set are: Enterprise Manager host and port Agent Name Process Name
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
Property
introscope.agent.enterprisemanager.tra nsport.tcp.host.DEFAULT

line. introscope.agent.enterprisemanager.tra nsport.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.agentli stener in the introscopeEnterpriseManager.properties file for each matching Enterprise Manager. See Uninstalling Introscope, page 54.
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 125
New z/OS Properties

Beginning with Version 5.0, WebSphere for z/OS has changed its default encoding from EBCDIC CP1047 to ASCII ISO8859-1. Because z/OS is normally an EBCDIC machine, any logging data written by the Introscope Agent or AutoProbe must be tagged to use EBCDIC as the final output stream, rather than ASCII. Two new properties must be enabled in the IntroscopeAgent.profile to accomplish this. These two properties are:
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.

There are several additional WebSphere configuration options. You can configure Introscope to extract WebSphere performance data through the JMX and PMI management interfaces, or configure the Agent to find its name automatically from the WebSphere application server instance. However, both of these options require a WebSphere custom service to be configured. Note that only one custom service is necessary to provide access to JMX, PMI and AutoNaming capabilities. Use the following instructions to configure the startup class, then view the information in the references in the next section to configure optional features that provide additional performance data.
Using PMI with Introscope on z/OS

There are several ways to obtain additional WebSphere specific performance metrics on z/OS. One solution is to add the Wily PowerPack for z/OS WebSphere which adds additional probes and measurements that are specifically designed for key WebSphere measurements. These utilize the standard Wily tracer technology and provide a low overhead way to obtain additional WebSphere measurements, and do not require any PMI facilities to be enabled inside WebSphere for z/OS. PMI is another technique for obtaining performance measurements, with a somewhat higher impact on performance. Wily does work with the IBM WebSphere z/OS PMI associated PMI metrics toggles in the IntroscopeAgent.profile. For additional details, see the section Enabling and Defining PMI Collection, page 191. Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 126
Configuring a Custom Service in WebSphere 5.0

The following section describes how to create a custom service in WebSphere 5.0. Consult your WebSphere documentation for instructions on creating a custom service in previous versions, or for more information.
Configuring a Custom Service in WebSphere 5.0

1. 2. 3. 4. 5. 6. Open the WebSphere 5.0 Administrative Console. Select the server you'd like to configure. Click on Custom Services. Click New to add a new Custom Service. Check the Startup checkbox. In the Classname field, enter:
com.wily.introscope.api.websphere.IntroscopeCustomService
7. In the Display Name field, enter:
Introscope Custom Service

8. In the Classpath field, enter:
<WebSphere home>/wily/WebAppSupport.jar
9. Click OK. 10. Restart the application server.
Optional WebSphere Configurations

See the following sections for information on optional WebSphere configurations. Agent Naming Options, page 169 JMX Filters For Obtaining Advanced Performance Data, page 182 Advanced WebSphere Performance Data, page 189 For general Introscope additional configuration options, see, Chapter 15, Optional Introscope Configurations.
Further Installation Information

For more help with configuring Introscope for z/OS, please contact Wily Technical Support at 1-888-GET-WILY or wilytech@custhelp.com.
Page 127
10 Configuring Sun ONE Application Server With Introscope

This section describes how to configure (Introscope-enable) a Java Application with the Sun ONE Application Server in the following sections: Configuring Introscope With Sun ONE Overview Installing Introscope Agent on Sun ONE ProbeBuilder Configuration Options Configuring Basic Agent Settings for SunONE
Configuring Introscope With Sun ONE Overview

Installing Introscope Agent on Sun ONE

To install the Introscope Agent on Sun ONE: 1. Make sure that Sun ONE Application Server and any required updates have been installed.
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,
<SunONE install dir>.

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)


The following table details the ProbeBuilder options available for each Sun ONE Application Server version and JVM combination. To find the appropriate ProbeBuilder method: 1. 2. 3. Choose the row containing your Sun ONE Application Server version. Choose a ProbeBuilder configuration option. Locate the instructions: If using JVM AutoProbe, locate the JVM you are running, and use the instructions associated with that JVM If using Application Server AutoProbe or Manual ProbeBuilder, use the instructions associated with that option. For example, if you have the following environment, Sun ONE Application Server version 7.0 JVM AutoProbe
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
Sun ONE 7.0

JVM AutoProbe Sun JVM AutoProbe With Sun ONE 7.0 Using Sun JVM, page 130
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
JVM AutoProbe With Sun ONE 7.0 Using Sun JVM

There are two steps required to configure and use JVM AutoProbe with Sun JVM: create an AutoProbe connector that will work with your JVM 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.

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to run Sun ONE. There are two ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool 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:

specifying the JVM by passing the JVM directory on the command line: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 130


Use the following instructions to run the AutoProbe connector: 1. 2. 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:
<SunONE install dir>/domains/domain1/server1/config/ Note: The item separator is a colon (:).

3. Add the following line to the server.xml file:
<jvm-options> -Xbootclasspath/p:<path-to-AutoProbeConnector.jar>:<path-toAgent.jar> </jvm-options>

For example:
<jvm-options> -Xbootclasspath/p:/sw/sun/sunone7/wily/connectors/ AutoProbeConnector.jar:/sw/sun/sunone7/wily/Agent.jar </jvm-options>

4. Modify the bootstrap classpath by adding the following option to the Java command line:
5. Proceed to the section, Configuring Basic Agent Settings for SunONE, page 133, to configure the Agent profile.
Application Server AutoProbe With Sun ONE

Application Server AutoProbe With Sun ONE 7.0

The following instructions work with Sun ONE 7.0:
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:

3. Add the full path of wily/Agent.jar to the server-classpath property of the javaconfig element in the server.xml file. For example:
<java-config ... server-classpath="/sw/sun/sunone7/wily/ Agent.jar:..." ...>

4. Add the following to the java-config element: Add the bytecode-preprocessors property and set it to the value
com.wily.introscope.api.sun.appserver.SunONEAutoProbe. For
example:
<java-config ... bytecodepreprocessors="com.wily.introscope.api.sun.appserver.SunONEAutoP robe">

Add a jvm-options element to define the location of the Agent profile. Define either com.wily.introscope.agentProfile, or com.wily.introscope.agentResource. The following is an example of com.wily.introscope.agentProfile:
<java-config ...> ... <jvm-options>-Dcom.wily.introscope.agentProfile=/sw/sun/sunone7/ wily/IntroscopeAgent.profile </jvm-options> </java-config>

The following is an example of com.wily.introscope.agentResource:
<java-config ...> ... <jvm-options>-Dcom.wily.introscope.agentResource=<virtual path to>/IntroscopeAgent.profile</jvm-options> </java-config>

5. OPTIONAL: If you configured com.wily.introscope.agentResource, add the resource file to the server classpath.
Page 132
Configuring Basic Agent Settings for SunONE 6. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 133.

If you are using Application Server AutoProbe, you will need to configure some Tracer Groups in the toggles-full.pbd and toggles-typical.pbd files so servlet data will be collected. This process involves turning one Tracer Group on and turning another off. 1. 2. 3. Locate <Sun ONE home>/wily/toggles-full.pbd. Go to the HTTP Servlets Configuration section. Turn off the HTTPServletTracing Tracer group by placing a pound sign at the beginning of the line, as in the following example:
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.
Configuring Basic Agent Settings for SunONE

The following section details how to configure the Introscope Agent. The Agent configuration settings are found in the file, <Sun ONE home>/wily/ IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile file as the Agent profile.

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

You can customize the location of the Agent profile, as long as you define the new location using one of the following methods: Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
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.

Defining Agent Profile Location in Sun ONE system.xml File

After you define the Agent profile location, you must add it to the system.xml file: 1. 2. 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:

3. Add the following line to the server.xml file:
<jvm-options> -Dcom.wily.introscope.agentProfile=<Sun ONE home>/wily/ IntroscopeAgent.profile </jvm-options>

Basic Agent properties you need to set are: Enterprise Manager host and port Agent Name Process Name Property Value and Description
Page 134
Configuring Basic Agent Settings for SunONE
introscope.agent.enterprisemanager.transpor t.tcp.host.DEFAULT

line. introscope.agent.enterprisemanager.transpor t.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.agentl istener in the introscopeEnterpriseManager.properties file for each matching Enterprise Manager. See Uninstalling Introscope, page 54.

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.

For additional configuration options, see, Chapter 15, Optional Introscope Configurations.
Page 135
11 Configuring Oracle Application Server 10g With Introscope

This section describes how to configure (Introscope-enable) a Java Application with the Oracle Application Server 10g in the following sections: Configuring Introscope With Oracle 10g Overview Installing Introscope Agent on Oracle 10g Choosing ProbeBuilder Configuration Option Configuring Basic Agent Settings for Oracle 10g
Configuring Introscope With Oracle 10g Overview

Installing Introscope Agent on Oracle 10g

To install the Introscope Agent on Oracle 10g: 1. 2. Make sure that the Oracle 10g version 10.0.3 Application Server and any required updates have been installed. Find the Oracle 10g installer file for your platform:
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


The following table details the ProbeBuilder options available for each Oracle Application Server 10g version and JVM combination. To find the appropriate ProbeBuilder method: 1. 2. 3. Choose the row containing your Oracle Application Server 10g version. Choose a ProbeBuilder configuration option. Locate the instructions: If using JVM AutoProbe, locate the JVM you are running, and use the instructions associated with that JVM If using Application Server AutoProbe or Manual ProbeBuilder, use the instructions associated with that option. For example, if you have the following environment, Oracle Application Server 10g version 10.0.3 JVM AutoProbe Sun JVM you would use the instructions in the section, JVM AutoProbe With Oracle 10g Using Sun JVM, page 138. If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 137
ProbeBuilder Configuration Options TABLE 15. ProbeBuilder Configuration Options Table
JVM
Oracle 10g 10.0.3

JVM AutoProbe Sun Application Server AutoProbe any Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder Application Server AutoProbe With Oracle Application Server 10g, page 139 JVM AutoProbe With Oracle 10g Using Sun JVM, page 138
JVM AutoProbe With Oracle 10g Using Sun JVM

There are two steps required to configure and use JVM AutoProbe with Sun JVM: create an AutoProbe connector that will work with your JVM 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.

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to Oracle 10g. There are two ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool 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:


Page 138

After you have created the AutoProbe Connector, you must modify the bootstrap classpath. 1. Add the following option to the Java command line:
2. Proceed to the section, Configuring Basic Agent Settings for Oracle 10g, page 140 to configure the Agent profile.
Application Server AutoProbe With Oracle Application Server 10g

The following instructions work with Oracle 10g 10.0.3: 1. 2. 3. 4. 5. Add the Agent.jar to the Application Server classpath. Set the system property oracle.classpreprocessor.classes with the value of com.wily.introscope.api.oracle.OracleAutoProbe. Set the system property oracle.j2ee.class.preprocessing with the value of true. Restart the Oracle Application Server 10g. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server AutoProbe, page 139.

If you are using Application Server AutoProbe, you will need to configure some Tracer Groups in the toggles-full.pbd and toggles-typical.pbd files so servlet data will be collected. This process involves turning one Tracer Group on and turning another off. 1. 2. 3. Locate <Oracle 10g home>/wily/toggles-full.pbd. Go to the HTTP Servlets Configuration section. Turn off the HTTPServletTracing Tracer group by placing a pound sign at the beginning of the line, as in the following example:
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
Configuring Basic Agent Settings for Oracle 10g
Configuring Basic Agent Settings for Oracle 10g

The following section details how to configure the Introscope Agent. The Agent configuration settings are found in the file, <Oracle 10g home>/wily/ IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile file as the Agent profile.


You can customize the location of the Agent profile, as long as you define the new location using one of the following methods: 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.


Basic Agent properties you need to set are: Enterprise Manager host and port Agent Name
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.

Page 141
12 Configuring SAP NetWeaver With Introscope

This section describes how to configure (Introscope-enable) a Java Application with SAP NetWeaver in the following sections: Configuring Introscope With SAP NetWeaver Overview Installing Introscope Agent Choosing ProbeBuilder Configuration Option Configuring Basic Agent Settings
Configuring Introscope With SAP NetWeaver Overview

Installing Introscope Agent

To install the Introscope Agent: 1. Find the Agent installer file for your platform:
Operating System
Windows Solaris HP-UX AIX Linux
Installer Filename
IntroscopeAgentInstall6.0.1netweaver.windows.zip IntroscopeAgentInstall6.0.1netweaver.unix.tar
SAP Support Only

Operating System
Windows
Installer Filename IntroscopeAgentInstall6.0.1netweaver.windows.SAP.zip
Page 142
Solaris HP-UX AIX Linux
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:
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.

A Java application is monitored by adding Probes to the bytecode. The Probes then report information to the Introscope Agent, and the Agent reports that information to the Enterprise Manager. The tool used to add Probes is called ProbeBuilder. If you are using an application server not integrated with AutoProbe, there are two ProbeBuilder configuration options that can be used to install probes into the application to be monitored: JVM AutoProbe Using the JVM AutoProbe option dynamically Introscope-enables all classes loaded by the JVM. Manual ProbeBuilder (using either the ProbeBuilder Wizard or Command-Line Probebuilder) The Manual ProbeBuilder option is a manual process which Introscope-enables classes on disk before the application server is run. The JVM AutoProbe option installs probes dynamically into application code as it is loaded. Whenever possible, using ProbeBuilder through AutoProbe will save time and provide ease of use that Introscope-enabling an application manually does not.

The following table details the ProbeBuilder options available for use with SAP NetWeaver versions 6.20 and 6.40. To find the appropriate ProbeBuilder method:
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
Application Server
JVM
SAP NetWeaver v 6.20 or 6.40

JVM AutoProbe Sun IBM HP Manual ProbeBuilder any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder JVM AutoProbe Using Sun or IBM JVM, page 144 JVM AutoProbe Using Sun or IBM JVM, page 144 JVM AutoProbe Using HP HotSpot JVM, page 146
JVM AutoProbe Using Sun or IBM JVM

There are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM: create an AutoProbe connector that will work with your JVM run the AutoProbe Connector by modifying the classpath with the location of the AutoProbe connector, Agent, and ProbeBuilder
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.
The following section details how to configure JVM AutoProbe.

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to run the application server. There are two ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool 1. 2. Change the working directory to wily/connectors. Run the Create AutoProbe Connector tool using one of the following commands: specifying the JVM using the JVM running the tool:
/<jvm_path>/java -jar CreateAutoProbeConnector.jar -current

java -jar CreateAutoProbeConnector.jar -jvm<directory>

ProbeBuilder Configuration Options 3. The output is a file with the form:

After you have created the AutoProbe Connector, you must modify the boot class path by adding JVM options. Typically, you will only want to activate the Agent on the SAP J2EE server nodes, not on dispatchers and state controllers. Note that for class path and directory paths, you can use forward slashes (/) on all platforms, even on Windows. For SAP J2EE 6.40, you even cannot use backslash (\) on Windows. Furthermore, note that on the classpath, the entries are separated by a semicolon (;) on Windows, but by a colon (:)on Unix. For Agent name, we recommend you use an identifier that uniquely identifies the J2EE node in your landscape, e.g., <hostName>_<server0> or similar.
Note: The following path examples use the Windows convention.
Using SAP J2EE 6.20

1. Open the file:
<drive>:\usr\sap\<J2EE_ENGINE_ID>\j2ee\j2ee_<INSTANCE>\cluster\ server\cmdline.properties
2. Append the following commands to JavaParameters:
-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>;<path-toAgent.jar> -Dcom.wily.introscope.agentProfile=<path-toIntroscopeAgent.profile> -Dcom.wily.introscope.agent.agentName=<yourAgentName>

For example:
-Xbootclasspath/ p:C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\connectors\AutoProbeCon nector.jar;C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\Agent.jar Dcom.wily.introscope.agentProfile=C:\usr\sap\P602\j2ee\j2ee_00\c cms\wily\IntroscopeAgent.profile

3. Restart SAP server.
Using NetWeaver 04/SAP J2EE 6.40

1. 2. Run the SAP J2EE Configtool. Select the server to modify.
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.
JVM AutoProbe Using HP HotSpot JVM

The following instructions work with HP HotSpot JVM. 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:
3. Proceed to the section, Configuring Basic Agent Settings, page 147 to configure the Agent profile.
Page 146
Configuring Basic Agent Settings

The following section details how to configure the Introscope Agent. The Agent configuration settings are found in the file, <Application server home>/wily/ IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile file as the Agent profile.

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
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.

You can customize the location of the Agent profile, as long as you define the new location using one of the following methods: 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:
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 147
Property
introscope.agent.enterprisemanager .transport.tcp.host.DEFAULT


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.agentlistener 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.customProcessNa me Enter name for process being monitored.

Page 148
13 Configuring Other Application Servers or Applications With Introscope

This section describes how to configure (Introscope-enable) a Java Application in the following sections: Configuring Introscope With Other Application Servers Overview Installing Introscope Agent Choosing ProbeBuilder Configuration Option Configuring Basic Agent Settings
Configuring Introscope With Other Application Servers Overview

Introscope is tightly and easily integrated with selected Web application servers: 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 Fujitsu Interstage 6.0 (Japanese version) If your application server is not on the above list, use the instructions in this section to Introscope-enable your Java applications. There are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager: install the Introscope Agent Introscope-enable the application code using one of the ProbeBuilder configuration options configure basic Introscope Agent settings

To install the Introscope Agent: 1. Find the Agent installer file for your platform:
IntroscopeAgentInstall6.0.1default.unix.tar IntroscopeAgentInstall6.0.1default.windows.zip 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. Page 149
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:
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.

A Java application is monitored by adding Probes to the bytecode. The Probes then report information to the Introscope Agent, and the Agent reports that information to the Enterprise Manager. The tool used to add Probes is called ProbeBuilder. If you are using an application server not integrated with AutoProbe, or a stand-alone application, there are two ProbeBuilder configuration options that can be used to install probes into the application to be monitored: JVM AutoProbe Using the JVM AutoProbe option dynamically Introscope-enables all classes loaded by the JVM. Manual ProbeBuilder (using either the ProbeBuilder Wizard or Command-Line Probebuilder) The Manual ProbeBuilder option is a manual process which Introscope-enables classes on disk before the application server is run. The JVM AutoProbe option installs probes dynamically into application code as it is loaded. Whenever possible, using ProbeBuilder through AutoProbe will save time and provide ease of use that Introscope-enabling an application manually does not.

The following table details the ProbeBuilder options available when not using WebLogic, WebSphere, Sun ONE or Oracle 10g. To find the appropriate ProbeBuilder method: 1. 2. Choose a ProbeBuilder configuration option. Locate the instructions: 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. If you need help determining which ProbeBuilder option is appropriate for your deployment, contact Wily Professional Services for assistance. TABLE 17. ProbeBuilder Configuration Options Table
Page 150

JVM AutoProbe
JVM
any Java 5.0 JVM Sun IBM HP Manual ProbeBuilder any
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
Chapter 14, Configuring the Java Applications Manually With ProbeBuilder
JVM AutoProbe Using Java 5.0 JVM

The following instructions work Java 5.0 JVM: 1. Add the following command-line option to the JVM command line:
-javaagent:<path-to-Agent.jar>
JVM AutoProbe Using Sun or IBM JVM

There are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM: create an AutoProbe connector that will work with your JVM 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.

Use the CreateAutoProbeConnector.jar tool to create a connector specific to the JVM used to run the application server. There are two ways to specify the JVM: use the JVM that is running the tool pass the JVM directory on the command line to the tool 1. 2. Change the working directory to wily/connectors. Run the Create AutoProbe Connector tool using one of the following commands: specifying the JVM using the JVM running the tool:
/<jvm_path>/java -jar CreateAutoProbeConnector.jar -current

specifying the JVM by passing the JVM directory on the command line: Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
Page 151
java -jar CreateAutoProbeConnector.jar -jvm<directory>


After you have created the AutoProbe Connector, you must modify the boot classpath. 1. Add the Agent.jar and the AutoProbeConnector you created to the Application Server classpath using the following command:
JVM AutoProbe Using HP HotSpot JVM

The following instructions work with HP HotSpot JVM. 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:

The following section details how to configure the Introscope Agent. The Agent configuration settings are found in the file, <Application server home>/wily/ IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile file as the Agent profile.

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
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

You can customize the location of the Agent profile, as long as you define the new location using one of the following methods: 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:


Property
introscope.agent.enterprisemanager .transport.tcp.host.DEFAULT


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.agentlistener 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.
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
Enter name for process being monitored.

Page 154
14 Configuring the Java Applications Manually With ProbeBuilder

This section describes how to manually Introscope-enable a Java Application in the following sections: Configuring Java Applications Manually Overview Configuring Java Applications With ProbeBuilder Wizard Configuring Java Applications With Command-Line ProbeBuilder Configuring Basic Agent Settings Options for Running Introscope-enabled Code Switching Back to Your Non-Introscope-enabled Code
Configuring Java Applications Manually Overview

A Java application is monitored by adding Probes to the bytecode. The Probes then report information to the Introscope Agent, and the Agent reports that information to the Enterprise Manager. When you run ProbeBuilder manually, it Introscope-enables classes on disk before the application server is run. You can use Manual ProbeBuilder when you want to: Introscope-enable a Java system other than those integrated with AutoProbe (WebLogic, WebSphere, Sun ONE, Oracle 10g, HP HotSpot JVM) add probes to your code without using AutoProbe, even if you are using one of the above systems. Using AutoProbe offers dynamic instrumentation of bytecode. To Introscope-enable your Java application using AutoProbe, see Chapter 6, Configuring Java Applications With Introscope. There are two methods available to Introscope-enable your bytecode manually: ProbeBuilder Wizard ProbeBuilder Wizard walks you through the process of manually Introscopeenabling your application in a windowing environment. Command-line ProbeBuilder Command-line ProbeBuilder is a command-line interface for Introscope-enabling your applications manually.
Configuring Java Applications With ProbeBuilder Wizard

If your machine has a windowing environment, use the instructions in this section to add Probes to your bytecode. There are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 155
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.

1. Find the Agent installer file for your platform: If you are Introscope-enabling WebSphere, WebLogic, Sun ONE, Oracle 10g or HP HotSpot JVM with Command-line ProbeBuilder, use one of the following Agent installers:
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
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:
Agent.jar ext/ProbeBuilder.jar IntroscopeAgent.profile

Several .pbd and .pbl files (ProbeBuilder Directives and List files). If you used an Agent installer specific to an application server, you will see .pbd and .pbl files specific to that application server (for example if you used a WebLogic Agent installer, you will see a weblogic.pbl file). connectors/CreateAutoProbeConnector.jar If you want to use any custom .pbd files, add them to the /wily directory. 3. Proceed to Adding Probes to Bytecode With ProbeBuilder Wizard, page 157.
Adding Probes to Bytecode With ProbeBuilder Wizard

To add Probes to bytecode with ProbeBuilder Wizard: 1. 2. 3. 4. If you have any custom .pbds to use, add them to the <Introscope home>/
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
Configuring Java Applications With ProbeBuilder Wizard 9. Click Next.
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.
Editing the Classpath

After adding Probes to the bytecode, update the classpath of the application startup script to reflect the locations of the Introscope-enabled code and the Agent. 1. Edit the classpath of the application startup script to include locations of the directories containing the Introscope-enabled code created with the ProbeBuilder. Make sure this reference precedes the reference to the original code in the classpath.
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:
java -classpath /<your-applicationpath>/classes:/<yourapplicationpath>/lib/app.jar MainClass

to look like this:
java -classpath /<your-applicationpath>.isc/classes:/<yourapplicationpath>.isc/lib/app.jar:/Introscope/lib/Agent.jar MainClass

3. 4. 5. Save the changes. Start your application with the new startup script. Proceed to the section, Configuring Basic Agent Settings, page 165.
Configuring Java Applications With Command-Line ProbeBuilder

If your machine does not have a windowing environment, use the instructions in this section to add Probes to your bytecode. There are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager: install the Introscope Agent Introscope-enable the application code using Command-line ProbeBuilder configure basic Introscope Agent settings

1. Find the Agent installer file for your platform: If you are Introscope-enabling WebSphere, WebLogic, Sun ONE, Oracle 10g or HP HotSpot JVM with Command-line ProbeBuilder, use one of the following Agent installers:
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

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 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:
Agent.jar ext/ProbeBuilder.jar IntroscopeAgent.profile

Several .pbd and .pbl files (ProbeBuilder Directives and List files). If you used an Agent installer specific to an application server, you will see .pbd and .pbl files specific to that application server (for example if you used a WebLogic Agent installer, you will see a weblogic.pbl file). connectors/CreateAutoProbeConnector.jar If you want to use any custom .pbd files, add them to the /wily directory.
Adding Probes to Bytecode Using Command-Line ProbeBuilder

The Command-Line ProbeBuilder is activated by a command. The following code is an example of the command. This example is being run from the /wily directory, so paths are relative to the /wily directory. The syntax for the Java command depends on your Java version and other settings in your environment.
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:
java -classpath ext/ProbeBuilder.jar com.wily.introscope.api.IntroscopeProbeBuilder -directives default.pbl,stream.pbd
Page 163
-origdir /usr/myApp/classes -destdir /usr/myApp/classes.isc verbose

TABLE 4. Command Line ProbeBuilder Commands Option
-help -h -? -directives (or -pbd) comma-separated-file-list
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
Editing the Classpath

After adding Probes to the bytecode, update the classpath of the application startup script to reflect the locations of the Introscope-enabled code and the Agent. 1. Edit the classpath of the application startup script to include locations of the directories containing the Introscope-enabled code created with the ProbeBuilder. Make sure this reference precedes the reference to the original code in the classpath. Edit the classpath in the application startup script to include the path to the Agent.jar. For example, you might edit a classpath that looks like this:
2.
java -classpath /<your-applicationpath>/lib/app.jar MainClass

Configuring Basic Agent Settings to look like this:
java -classpath /<your-applicationpath>.isc/lib/app.jar:/ <appserver home>/wily/Agent.jar MainClass

3. 4. 5. Save the changes. Start your application with the new startup script. Proceed to the section, Configuring Basic Agent Settings, page 165.

The following section details how to configure the Introscope Agent. Agent configuration settings for non-AutoProbe installations are found in the file, /wily/ IntroscopeAgent.profile. Before performing any Agent configurations, you may want to copy the IntroscopeAgent.profile, and rename it to a name that identifies the Agent, such as Petstoreagent.profile. You can place it in another directory, such as the application directory. However, if you move the IntroscopeAgent.profile to another location, you should also move the directives files (.pbd and .pbl files), as they are referenced relative to the location of the Agent profile.


You can customize the locatin of the Agent profile, as long as you define the new location using one of the following methods: 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:

Basic Agent properties you need to set are: Enterprise Manager host and port
Page 165
Options for Running Introscope-enabled Code Agent Name Process Name
Property
introscope.agent.enterprisemanager.transp ort.tcp.host.DEFAULT


introscope.agent.enterprisemanager.transp ort.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.agentlis tener in the introscopeEnterpriseManager.properties file for each matching Enterprise Manager. See Uninstalling Introscope, page 54.
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.

Options for Running Introscope-enabled Code

There are three ways to point to Introscope-enabled code instead of your original code: Replace original paths in classpaths with paths to the Introscope-enabled code. In classpaths, replace original-class paths with Introscope-enabled code paths. The instructions in this chapter directed you to perform this process when you Introscope-enabled your application for the first time. Prepend paths to classpaths.
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.
Switching Back to Your Non-Introscope-enabled Code

If you want to switch back to using non-Introscope-enabled code, undo the steps of modifying classpaths to run Introscope-enabled code, as described below: If you put the paths to your Introscope-enabled code into the Java classpaths, then replace paths to the Introscope-enabled code in Java classpaths with original paths. If you added paths to the Introscope-enabled code in front of the paths to the original code, remove prepended paths to classpaths Remove the prepended portion of the classpath so that only the original classpath remains. If you put Introscope-enabled code in original classpath, then remove the Introscope-enabled code from the original path and place the original code in the original classpath. If you used symbolic links on a UNIX system, point the symbolic link to the original directory, or remove the link and move the code into the original classpath.
Page 167
15 Optional Introscope Configurations

This section describes optional Introscope configurations in the following sections: Agent Naming Options Agent Failover Switching Between Full and Typical Tracing Options Multiple Agent Options Other Optional Agent Settings Agent Logging Options Platform Monitors JMX Filters For Obtaining Advanced Performance Data Advanced WebSphere Performance Data Enterprise Manager Database Recording Optional Enterprise Manager Configurations Connecting Workstation to Enterprise Manager Behind Firewall Optional ProbeBuilder Configurations Miscellaneous Installation Options
Page 168
Agent Naming Options

Introscope allows multiple ways of specifying the Agent name, some that can pull the Agent name from a system property already set in the JVM, or in some cases, automatically from the application server. In most cases, this eliminates the need to configure individual Agent names in separate Agent profiles.
Agent Name Location Sequence

The Introscope Agent will attempt to find a name for itself through the following sequence of methods. If it finds a name using the first method, it will accept that name and connect to the Enterprise Manager. If it doesnt find a name using the first method, it will try the second method, and so on. If it doesnt find a name using any method, it will call itself Unknown Agent. 1. Name Specified in Java system property The Agent name is defined using a Java system property on the command line. Using this method will override any other Agent naming method. 2. Name specified in System Property Key in Agent Profile The Agent name is obtained from a Java system property specified in a property in the IntroscopeAgent.profile. 3. Name obtained automatically from Application Server If you are using certain versions of WebLogic or WebSphere, the Agent name can be automatically obtained from the application server using new Automatic Agent Naming functionality. You can configure a time delay, to give the Agent as much time as necessary to determine its name before connecting to the Enterprise Manager. 4. Name specified explicitly in Agent profile The Agent name is defined in the IntroscopeAgent.profile, in the property, introscope.agent.agentName. This was the standard method for naming Agents
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.
Obtaining Agent Name Using System Properties

The following sections describe how to configure Agent naming using Java system property options.
Specifying Agent Name Using Java System Property

This method is the first the Agent will use to look for its name. If this method is used, it will override Agent names specified using any other method. To specify an Agent name using the Java system property:
On the Java command line, specify an Agent name using the following Java system property:
Page 169
com.wily.introscope.agent.agentName
Specifying Agent Name Using System Property Key

This method is the second the Agent will use to look for its name. Use this method if you want the Agent to be named from the value of an existing Java system property in your deployment. To specify an Agent name using the System Property Key: 1. 2. Open the IntroscopeAgent.profile. Under the Agent Name section, specify the Java system property that will provide the Agent name in the following property:
introscope.agent.agentNameSystemPropertyKey Note: If the Java system property specified here doesnt exist, this property will be
ignored. 3. Restart the application server.
Obtaining Agent Name Automatically From Application Server

As part of Wilys constant efforts to extend the ease of Introscope implementation and usage within the enterprise, the Agent can be configured to extract the application server instance name automatically from the application server, and use that information to name itself. This eliminates the need to configure individual Agent names in a separate Agent profile file. The Agent can also rename itself if there are changes in the application server environment. In this manner, an Agent profile can be deployed across a large number of environments which may consist of a mix of application server platforms.
Supported Application Server Versions

Automatic Agent Naming is supported when you use Introscope with the following supported application server versions: WebLogic 6.1 WebLogic 7.0 WebLogic 8.1 WebSphere 6.0.x distributed WebSphere 5.0.x distributed WebSphere 5.0.x on z/OS WebSphere 5.1 distributed
How Automatic Agent Naming Works

When Automatic Agent Naming is enabled, the Agent starts up, and looks for name information from the application server. The Agent waits until an Agent name is obtained before attempting to connect to the Enterprise Manager.
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.
Name Structure Notes

When constructing the Agent name that appears in Introscope, Introscope edits the information to make the Agent name compliant with Introscope Agent naming rules. characters such as pipes, colons, or percentage signs will be replaced by underscores names that begin with any character other than a letter will have the letter A prepended to them empty names are replaced by UnnamedAgent (so as to be distinguishable from the UnknownAgent condition)
Automatic Agent Naming and Renamed Agents

Using Automatic Agent Naming, the Agent will always try to obtain the most current application-server specific Agent name. The Agent will periodically check for a new name. If a change to application server configuration results in an Agent name change, the Agent will automatically rename itself. In the Explorer tree, the Agent will appear to disconnect. The disconnected Agent will remain in the Explorer tree, and will unmount automatically after the unmount time period has elapsed, or it can be unmounted manually. The renamed Agent will reconnect to the Enterprise Manager and will appear in the Explorer tree. The Agent logs these changes.
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
Enabling Automatic Agent Naming

There are some minor configurations you need to perform to enable Automatic Agent Naming. To enable Automatic Agent Naming, make sure the following pre-requisites have been fulfilled: 1. 2. In the Agent profile, make sure that
introscope.agent.agentAutoNamingEnabled is set to true.

Application server-specific changes: For WebLogic, an Introscope Startup Class must be created. See Creating a WebLogic Startup Class, page 105. For WebSphere, an Introscope Custom Service must be created. See Configuring a Custom Service in WebSphere, page 116.
Advanced Automatic Naming Options

There are several Automatic Agent Naming configurations you can alter if desired.
Initial Enterprise Manager Connection Delay

When using the Automatic Agent Naming feature, the Agent will wait a up to a configurable amount of time before connecting to the Enterprise Manager while trying to find Agent name information. The default delay is 120 seconds. To change this delay value: 1. 2. Open the IntroscopeAgent.profile. Under the Agent Name section, configure the desired delay in the property. 3.
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds
Restart the application server.
Agent Rename Check Interval

When using the Automatic Agent Naming feature, the Agent will periodically check to see if the naming information from the application server has changed. The default interval is ten minutes. To change this interval: 1. 2. 3. Open the IntroscopeAgent.profile. Under the Agent Name section, configure the desired interval in the introscope.agent.agentAutoRenamingIntervalInMinutes property. Restart the application server.
Page 172
Agent Failover
Turning Off Agent Log File Automatic Naming

By default, when the Agent name is found automatically, either by information provided by a Java system property or application server, the log files associated with that Agent are named automatically using that same information. However, you can optionally turn off this automatic log naming, and continue to use the Agent log name specified in the IntroscopeAgent.profile. To turn off Agent log file automatic naming: 1. 2. 3. Open the Agent profile, usually IntroscopeAgent.profile. Locate the property, introscope.agent.disableLogFileAutoNaming, and enter a value of true. Restart the application server.
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
Configuring Agent Failover

In a basic Introscope configuration, you defined the host and port settings for one Enterprise Manager. To enable Agent Failover, you must define a list of Enterprise Managers that the Agent will try to connect to if it disconnects from its current Enterprise Manager. For each Enterprise Manager in the list, you will need to: set the host setting set the port setting assign it a name After defining Enterprise Manager details, you will provide a desired connection order that the Introscope Agent will use to reconnect to an Enterprise Manager if the connection to the primary Enterprise Manager is lost. 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. Locate the Enterprise Manager Locations and Names section. The default Enterprise Manager set in the
introscope.agent.enterprisemanager.tcp.host and
Page 173
Agent Failover
as seen here:
introscope.agent.enterprisemanager.tcp.port settings is named DEFAULT,
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localh ost introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001

3. Duplicate these two settings for each Enterprise Manager in your list, and set their host and port settings. The host setting should be either the host name or IP address of a machine with an Enterprise Manager on it. The port can be any unused port for this IP address, as it will listen for Agent connections. This port should be the same as the configured Agent listening port on the Enterprise Manager. You must give each host and port combination in the list a unique name to identify it in the connection order list. Replace the name DEFAULT with a unique name. For example, if you have three machines with Enterprise Managers running on them, after naming them and defining the host and port settings, your Enterprise Manager list could look like this:
4.
introscope.agent.enterprisemanager.transport.tcp.host.MainEM=enterpr ise introscope.agent.enterprisemanager.transport.tcp.port.MainEM=5001 introscope.agent.enterprisemanager.transport.tcp.host.BackupEM1=voya ger introscope.agent.enterprisemanager.transport.tcp.port.BackupEM1=5002 introscope.agent.enterprisemanager.transport.tcp.host.BackupEM2=spac e9 introscope.agent.enterprisemanager.transport.tcp.port.BackupEM2=5003

5. 6. Locate the Enterprise Manager Connection Order section. For the property, introscope.agent.enterprisemanager.connectionorder, enter the list of Enterprise Manager names separated by commas, using the following syntax:
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
Switching Between Full and Typical Tracing Options
Configuring Automatic Agent Failback to Primary Enterprise Manager

In the default Agent Failover scenario, if the Agent loses the connection to its primary Enterprise Manager (the first one defined in the Enterprise Connection order list), it will attempt to connect to the next Enterprise Manager defined in the Agent profile. You can optionally configure the Agent to periodically attempt to reconnect to the primary Enterprise Manager. To configure the Agent to attempt to reconnect to the primary Enterprise Manager: 1. 2. In the Agent profile, IntroscopeAgent.profile, locate the Enterprise Manager Failback Retry Interval section. Uncomment the property,
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.
Agent Failover and Domain/User Configuration

If you want to take advantage of Agent Failover functionality, and also have Users, Domains, and authentication settings defined, you must make sure that this information is in sync across the specified failover Enterprise Managers. For more information on Domains and user permissions, see Chapter 5, Configuring Introscope Security and Permissions.
Switching Between Full and Typical Tracing Options

In Introscope, Tracer groups cause the reporting of information about a set of classes. Tracer groups are found in PBD files, and referred to in PBL (ProbeBuilder list) files. There are two sets of PBL files available with each Agent installer: Full (default)= references PBD files in which a set of common Tracer Groups in PBD files are turned on. Introscope uses this set by default to demonstrate full Introscope functionality. Typical= references PBDs in which only a subset of Tracer Groups are turned on. The typical set includes common settings, and is the set you can customize for a particular environment. For more information on full and typical system directives files and customizing the TYPICAL settings, see Default Tracer Groups and Toggles Files, page 215.
Switching to Typical Tracing Options

To change to using a typical .pbl: 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. Locate the Directives Files section.
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.
Multiple Agent Options

You may at times run identical instances of your applications. In these situations, Introscope will attempt to resolve the identical Agent names by appending the Agent name with a character and a random number. However, it is better if you tell Introscope how to resolve the naming. The options for resolving identical Agent naming are: Tell Introscope that the Agents in question are cloned Agents by enabling cloned Agent naming (described in Enabling Cloned Agent Naming, page 176) Define unique Agent names yourself and make separate Agent profiles for each Agent (described in Running An Application Twice On One Machine, page 177) Let Introscope uniquely name each Agent using its own naming scheme (described in How Introscope Resolves Agent Naming Conflicts, page 177)
Enabling Cloned Agent Naming

if two Agents exist with the same name monitoring the same host and process and are not uniquely named by a user, the name is appended with a random number (described in the section, How Introscope Resolves Agent Naming Conflicts, page 177). With this random numbering scheme, it is not possible to track Agents in a cluster. Cloned Agent Naming allows you to correlate an Agent with a particular instance in a cluster. You are running cloned Agents if you: are running Agents that share a host, process and Agent Name with one or more other Agents OR are running two or more Agents that are using the same Agent profile
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
Other Optional Agent Settings
Enabling Cloned Agent Naming in the Agent Profile

To enable Cloned Agent naming: 1. 2. Open the Agent profile, IntroscopeAgent.profile. Set the following property:
introscope.agent.clonedAgent=true
3. Restart your managed application.
Running An Application Twice On One Machine

You may sometimes run one application twice on the same machine. In this case, ideally you should: create a separate Agent profile for each application uniquely name each Agent in the Agent profile specify which Agent profile each application should use.
How Introscope Resolves Agent Naming Conflicts

The Fully-Qualified Agent name makes each Agent unique, because it is composed of the combination of host name, process name and Agent name. Even if a user didnt uniquely name the Agent, the chances of a naming conflict is lessened, because the host name and process name are likely different. However, two Agents having the same FullyQualified Agent name could technically happen if: both resided on the same host and were monitoring the same process, and neither of them had been uniquely named by the user, or for some reason they happened to have the same Agent name. If a duplicate Fully-Qualified Agent does attempt to connect to the Enterprise Manager, it will be given a unique name by the Enterprise Manager by appending the Agent Name with a % character and a random number, using the following syntax:
<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.
Other Optional Agent Settings

Using Custom ProbeBuilder Directives Files (AutoProbe installations only)
If you have created Custom Probebuilder Directives (.pbd) files or want to use other directives files, use the following steps.
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.
IntroscopeAgent.profile file, and resolves filenames relative to this directory.
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.
Removing Line Numbers in Bytecode

When you Introscope-enable application bytecode, by default, the AutoProbe or ProbeBuilder preserves the bytecode line numbers. Preserving bytecode line number information is helpful when using debuggers, or when obtaining stack trace information. You can turn off this feature, (which will remove all line numbers when AutoProbe or ProbeBuilder Introscope-enables the application code), by adding a system property on the Java command line. To remove line numbers in bytecode when using AutoProbe or ProbeBuilder:
define the following system property on the Java command line with the -D option:
com.wily.probebuilder.removeLineNumbers=true
Turning Off Socket Input/Output Metrics

Metrics that trace per socket bandwidth have a potential for high overhead, and can be turned off if you notice that collecting network Metrics is consuming a lot of processor or I/O time. To turn off the reporting of server and client socket input and output Metrics:
In the IntroscopeAgent.profile, for the property,
introscope.agent.sockets.reportRateMetrics, enter a value of false.
Agent Logging Options

The following section describes how to run the Agent in verbose mode and set logfile details for the Agent. Introscope uses Log4J functionality for these functions. If you want to use other Log4J functionality, please see Log4J documentation at http:// jakarta.apache.org/log4j/docs/documentation.html.
Page 178
Agent Logging Options
Agent Log Files and Automatic Agent Naming

If you are using Automatic Agent Naming functionality, by default, when the Agent name is found automatically, either by information provided by a Java system property, or provided through the application server, the log files associated with that Agent are named automatically using that same information. The following examples show how the Agent logfile will be named. The examples use an Agent name of DOM1//ACME42 (where DOM1 is the WebLogic domain, and ACME42 is the instance). When an Agent log file is created (by default, named AutoProbe.log), if the Agent name is not yet available, a timestamp will be included in the filename, as in:
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.
Agent Logfile Automatic Naming Notes

The following notes apply to Agent logfile automatic naming: if the original name of the logfile does not end in .log, a period will be appended, and log added. all characters not letters or digits will be replaced by underscores if advanced Log4J functionality is used, the Agent logfile automatic naming capability may not work
Running Agent in Verbose Mode

Running the Agent in verbose mode records details to the log, which is helpful in debugging. To run the Agent in verbose mode: 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. In the property, log4j.logger.IntroscopeAgent, replace INFO with the following:
3. Save changes.
Redirecting Agent Output to a File

To redirect Agent output to a file: 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. In the property, log4j.logger.IntroscopeAgent, replace console with logfile.
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.
Enabling Platform Monitors

Platform monitors on all platforms except Windows Server 2003 and AIX are automatically enabled upon Agent installation. Windows Server 2003 and AIX platform monitors require a minimal configuration to work. The following sections describe these configurations.
Enabling Platform Monitors on Windows Server 2003

You must have admin privileges to run Platform Monitors on Windows Server 2003.
Enabling Platform Monitors on AIX

1. After Agent installation, make sure the following files are installed in the
<appserver home>/wily/ext directory:

introscopeAIXStats.jar introscopeAIXStats.so 2. Install the Perfstat Library. AIX 5: Install the patch/fix APAR IY30022 from IBM at http:// techsupport.services.ibm.com/server/aix.fixsearch51. AIX 4.3.3 and higher: A Perfstat Library has been created to work with AIX 4.3.3. Install the following packages from ftp://ftp.software.ibm.com/aix/fixes/v4/os: bos.perf.libperfstat bos.perf.perfstat AIX 4: Bring your system up to 4.3.3 and then install the above packages.
Note: Restart your machine to ensure the patches have taken effect.
Disabling Platform Monitors

To disable platform monitors on any platform, simply move the .jar file from the <appserver home>/wily/ext directory to another directory. The following table details the location of platform monitor files installed with an Agent installer. TABLE 5. Platform Monitor File Locations
<appserver home>/wily/ext/introscopeSolarisStats.jar <appserver home>/wily/ext/introscopeSolarisStats.so <appserver home>\wily\ext\introscopeWindowsStats.jar <appserver home>\wily\ext\introscopeWindowsStats.dll
Solaris Windows
Server 2003 all Windows 2000 platforms XP Professional
Page 181
JMX Filters For Obtaining Advanced Performance Data
AIX RedHat Enterprise Linux
<appserver home>/wily/ext/introscopeAIXStats.jar <appserver home>/wily/ext/introscopeAIXStats.so <appserver home>/wily/ext/introscopeRedHatStats.jar <appserver home>/wily/ext/introscopeRedHatStats.so
Platform Configuration Troubleshooting Option

In most cases, the platform monitor will successfully detect the operating system and run if the operating system is supported. In rare cases where this does not occur, you can explicitly specify your operating system in the Agent profile to ensure that the platform monitor runs. 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. Under the Platform Monitor Configuration heading, locate the introscope.agent.platform.monitor.system property and enter the value for your operating system. Available values are:
AIX Solaris Windows RedHat2.1 RedHat3.0

3. Restart the managed application.

Introscope obtains application server internal Metric information through the application servers exposed JMX management API. This functionality is called JMX support. Introscope is built to support any MBean built to the Sun JMX specification. It is configured to support implementation of JMX in WebLogic and WebSphere version 5.0. For more information on the Sun JMX specification, see http://java.sun.com/products/ JavaManagement/. To make JMX MBean information viewable as Introscope-specific Metrics, Introscope converts MBean attributes to Introscope Metrics. Users can then filter these Metrics to only display the desired Metrics.
WebLogic 9.0 MBean Source

WebLogic versions prior to WebLogic 9.0 provided only a single MBeanServer as a source of JMX metrics. WebLogic 9.0 provides three: RuntimeServiceMBean: per-server runtime metrics, including active effective configuration DomainRuntimeServiceMBean: domain-wide runtime metrics EditServiceMBean: allows user to edit persistent configuration
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.
Metric Name Conversion and Filters

Information in MBeans is defined by a domain name and one or more key/value pairs. Introscope converts this JMX information into Introscope-specific Metric format and displays it in the Explorer under the following Resource:
<Domain>|<Host>|<Process>|<Agent>|JMX|
There are two methods Introscope uses to convert JMX MBean information to Introscope Metrics: primary keys method default method
WebLogic 9.0 Metric Name Conversion

Normally a user can choose either the Primary Keys Conversion method or the default method. However, WebLogic 9.0 does not have any universally available primary keys, so WebLogic 9.0 will use the key/value pair Metric naming convention found in the Default Conversion Method described in Default Conversion Method, page 184. This also means the JMX Metric tree for WebLogic 9.0 will look different than that seen with other WebLogic versions.
Primary Keys Conversion Method

Defining primary keys provides users a way to streamline JMX Metric name conversion, and specify the order of key/value pair information in the generated Introscope-specific Metrics. In this method, a user defines primary keys in the introscope.agent.jmx.primarykeys property in the Agent profile, IntroscopeAgent.profile. A primary key defined here should uniquely identify an MBean. For example, WebLogic uses the Type key (for the kind of component or resource) and Name key (the name of the component or resource). The primary keys conversion method is used to convert MBean attributes if Introscope finds a match for one or more user-defined primary keys in an MBean. When Introscope converts MBean attributes using the primary keys method: only the value information is displayed values are ordered in the sequence defined in the
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
and a user sets the following values as primary keys:
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
Default Conversion Method

The default conversion method is used to convert an MBean if: using WebLogic 9.0 no primary keys are defined by the user, or no user-defined primary keys are found in the MBean information, or no user-defined primary keys are matched due to misspellings or incorrect case. When Introscope converts MBean attributes using the default 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 for the default conversion method:
<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.
Default JMX Filters for WebLogic

In the IntroscopeAgent.profile file shipped with WebLogic, the following keywords are already defined: ActiveConnectionsCurrentCount WaitingForConnectionCurrentCount PendingRequestCurrentCount ExecuteThreadCurrentIdleCount OpenSessionsCurrentCount
Configuring JMX Functionality

Full JMX functionality is configured through the following steps: Step 1: enable JMX Support in the Agent profile Step 2: define primary keys for converting JMX MBean information into Introscope-specific Metrics Step 3: define filters to streamline incoming JMX information For WebLogic and WebSphere there are additional steps: for WebLogic, configure a startup class for WebSphere 5.0.x and higher, configure a custom service and modify the Java2 security policy
Step 1: Enabling JMX Support

To enable JMX support, follow these steps: 1. For each application server, perform the following configuration: for WebLogic, configure a startup class. See Creating a WebLogic Startup Class, page 105. for WebSphere, configure a custom service. See Configuring a Custom Service in WebSphere, page 116. 2. 3. Shut down the managed application if it is running. Open the Agent profile, IntroscopeAgent.profile, and set the following
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
#introscope.agent.jmx.name.jsr77.enable=true #introscope.agent.jmx.name.primarykeys=J2EEServer,Application,j2 eeType,JDBCProvider,name,mbeanIdentifier #introscope.agent.jmx.name.filter=JSR77 #introscope.agent.jmx.ignore.attributes=server

4. Continue to the next step, Step 2: Defining Primary Keys.
Step 2: Defining Primary Keys

To define primary keys, use the following steps: 1. 2. Open the Agent profile, usually IntroscopeAgent.profile. Configure Primary Keys: For WebLogic 9.0: comment out the introscope.agent.jmx.primarykeys property. For all other WebLogic versions: make sure the property introscope.agent.jmx.primarykeys is uncommented. 3. Enter desired keys, separated by commas, in the property. In order for Introscope to properly match primary keys, the keys must be: spelled exactly case sensitive If a key is misspelled, or differs in case from its intended match, that key will not be added. 4. Continue to the next step, Step 3: Defining JMX Filters.
Step 3: Defining JMX Filters

To define JMX filters, use the following steps: 1. 2. 3. Open the Agent profile, IntroscopeAgent.profile. Make sure the property, introscope.agent.jmx.name.filter, is uncommented. Enter desired strings, separated by commas, in the property. In order for Introscope to properly match filtered strings, the strings must be: spelled exactly case sensitive 4. 5. Save changes. Restart the managed application.
Modifying Java 2 Security Policy (WebSphere 5.0.x only)
Edit the file <WebSphere home>/properties/server.policy to include the lines:
// permissions for Introscope JMX support grant codeBase "file:${was.install.root}/-" {

WebLogic Diagnostic Framework Data
permission com.tivoli.jmx.MBeanServerPermission "*"; permission com.tivoli.jmx.MBeanPermission "*"; permission com.tivoli.jmx.AllMBeanPermission "*"; };
Viewing JMX Data In Explorer

After youve enabled the JMX Support and defined the appropriate keys and filters, JMX data will be displayed in the following location in the Explorer tree.
<Domain>|<Host>|<Process>|<Agent>|JMX
The screenshot below shows an example of JMX Metrics in the Explorer tree.
WebLogic Diagnostic Framework Data

The WebLogic Diagnostic Framework (WLDF) is a monitoring and diagnostic framework that defines and implements a set of services that run within the WebLogic Server process and participate in the standard server life cycle. Using WLDF, you can create, collect, analyze, archive and access diagnostic data generated by a running server and the applications deployed within its containers. This data provides insight into the runtime performance of servers and applications and enables you to isolate and diagnose faults when they occur. Introscope 6.0.1 Installation & Configuration Guide (9/15/05)
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
Advanced WebSphere Performance Data
Obtaining WLDF Data

No additional Introscope configuration is required to obtain WLDF data. However, you do need to configure a WebLogic Startup Class in the WebLogic 9.0 Administrative Console. See Creating a WebLogic Startup Class, page 105 for more information.
Advanced WebSphere Performance Data

Introscope can provide WebSphere performance data by extracting WebSphere performance Metrics via the PMI interface provided with WebSphere 4.0 and higher. You must first enable PMI data collection in WebSphere before the data will be available to Introscope. In WebSphere, all performance monitor settings are off by default. These PMI Metrics can then be displayed as Introscope Metrics. Users can filter which Metric categories to bring into Introscope, depending on their needs. To begin collecting these Metrics, perform the following actions: turn on Performance Monitor Settings in WebSphere enable PMI settings in Introscope Agent profile configure an Introscope Custom Service in WebSphere
Turning on Performance Monitor Settings in WebSphere

Turning on Performance Monitor Settings in WebSphere 6.0/5.0.x
Please refer to the WebSphere 6.0/5.0.x documentation for instructions on enabling Performance Monitoring Settings, and enabling Performance Monitoring for each desired Metric category. To enable PMI information, you will also need to configure a Custom Service in WebSphere. See Configuring a Custom Service in WebSphere, page 116.
Modifying Java 2 Security Policy (WebSphere 6.0/5.0.x only)

If you are running WebSphere 5.0.x, you must modify the Java 2 Security Policy.
// permissions for Introscope PMI support grant codeBase "file:${was.install.root}/-" { permission java.security.AllPermission; };
Turning on Performance Monitor Settings in WebSphere 4.0 (Distributed)

To turn on WebSphere Performance Monitor Settings, perform the following steps:
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.
Enabling and Defining PMI Collection

Once you have turned on Performance Monitoring Settings in WebSphere, you must enable PMI data collection in Introscope, and enable the Metric categories youd like to see reported. To configure PMI collection, use the following steps: 1. 2. Shut down your managed application. Open the Agent profile, usually IntroscopeAgent.profile.
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
WebSphere 4.0 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
Note: For data to be provided to the
jvmpiModule, JVMPI must be turned on in WebSphere.
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.
Viewing WebSphere Agent PMI Data

After youve enabled PMI collections in Introscope, available PMI Metrics will be displayed in the following location in the Explorer tree:
<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.
Enterprise Manager Database Recording

The Enterprise Manager can send information to an external data store, either a database or a flat file. You will need to connect the Enterprise Manager to a database if you plan to send Introscope data to a database for later analysis by third-party analysis software.
Note: Historical data displayed in Historical Views is provided by SmartStor, which
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
Upgrading Database Schema Tables From Previous Versions

The database schema in Introscope 6.0.1 has not changed from version 5.0.2. If you are upgrading a database from a version previous to 5.0, please consult the Introscope 6.0.1 Upgrade Guide. Then, configure the database settings using the instructions in Setting Database Properties, page 195.
Configuring a New Enterprise Manager to Database Connection

For a new Introscope installation, follow the steps in these sections: Running Database Creation Script Setting Database Properties
Note: Database configuration is no longer performed as part of Introscope installation.

You will need the following items that you collected earlier: Database URL Appropriate database driver Database user name and password For more information on database properties that you can change, see IntroscopeEnterpriseManager.properties File, page 242.
Running Database Creation Script

This step is commonly done by a Database Administrator (DBA). If you are not the DBA for your organization, ask your DBA to complete this step. The DBA can control how database structures are set up by editing the database creation script. To create the database tables:
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
Setting Database Properties

To configure the Enterprise Manager to write to the database: 1. 2. 3. Shut down the Enterprise Manager. Open the file, <Introscope home>/config/
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
DB2 database on local machine
introscope.enterprisemanager.db.driver=COM.ibm.db2.jdbc.app.DB2Driver introscope.enterprisemanager.db.url=jdbc:db2:databasename introscope.enterprisemanager.db.username=myUser introscope.enterprisemanager.db.password=myPassword introscope.enterprisemanager.db.driver=COM.ibm.db2.jdbc.net.DB2Driver introscope.enterprisemanager.db.url=jdbc:db2:// myhost.mydomain.com:PortID/databasename introscope.enterprisemanager.db.username=myUser introscope.enterprisemanager.db.password=myPassword
DB2 database on remote machine
Microsoft Access
introscope.enterprisemanager.db.driver=sun.jdbc.odbc.JdbcOdbcDriver introscope.enterprisemanager .db.url=jdbc:odbc:WILY01 introscope.enterprisemanager.db.username=myUser introscope.enterprisemanager.db.password=myPassword
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
Configuring the Enterprise Manager Classpath

6. 7. Open the file, <Introscope home>/Introscope Enterprise Manager.lax Configure the Enterprise Manager classpath: For Enterprise Managers not running as Windows Services, edit the lax.class.path to include your JDBC driver. The following table shows examples of how different drivers are appended to the lax.class.path. TABLE 7. lax.class.path properties for the Introscope Enterprise Manager.lax file
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.
Sample Microsoft Access Database

The Introscope installation also provides a sample Microsoft Access database (located at <Introscope home>/examples/database/msaccess.mdb) which already has tables created for Introscope to use.
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
Optional Enterprise Manager Configurations

Running Enterprise Manager Commands
In the Enterprise Manager terminal window, you can enter the following commands:
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
Configuring Scheduled Export of Data

Your deployment may use a system to process data that cant access data directly from the database Introscope reports to. Introscope can perform scheduled exports of data into archived flat file. Each file is saved in a .csv format, then archived in a .zip file. The following rules apply: Archives will always start and end on the hour and any partial hours will be rounded up to a full hour. You can configure flat file archival based on both time and size. However, the following rules apply: the flat file will be archived whenever the time boundary is reached, regardless of file size if the file size limit is reached (based on the max file length property) before the time boundary, the file will be archived If you plan to change the system clock on the Enterprise Manager machine, or adjust the duration of archiving, you should manually archive the flat files before doing so. the default naming format of the flat files is:
<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
Configuring Scheduled Export of Data

To configure scheduled export of flat file data based on time: 1. 2. 3. 4. Open the file, <Introscope home>/config/
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
Adding or Moving Management Modules Between Enterprise Managers

You can add custom Management Modules or move Management Modules between Enterprise Managers. Some cautions when moving Management Modules between Enterprise Managers: Modules copied and moved to a new Enterprise Manager are not linked to the original Management Module; changes made in the original Management Module are not made in the copied Management Modules. If Management Modules contain links to Elements in other Management Modules, those Management Modules wont load unless the Management Modules containing the linked Elements are also moved. To add or move a Management Module: 1. Shut down the Enterprise Manager before adding or removing Management Modules. To add a new Management Module, place the Management Module .jar file in the <Introscope home>/config/modules directory. The Management Module .jar file must be copied into the directory manually. To remove a Management Module, take its .jar file out of the <Introscope home>/config/modules directory. To move a Management Module to a different Enterprise Manager, make a copy of the .jar file and move it to the <Introscope home>/config/modules directory in another Introscope installation. 2. Restart the Enterprise Manager for the changes in installed Management Modules to take effect.
Page 198
Workstation Options
Defining Explicit Table Qualifier

By default, the Enterprise Manager assumes that the Introscope tables are located in the tablespace associated with the username specified by the introscope.enterprisemanager.db.username property in the Enterprise
Manager properties file.

However, in some deployments the DBA may have created tables in some location other than the default schema associated with the username login. In this case, you can now define an explicit table qualifier in Introscope so that the Enterprise Manager will specify a fully-qualified table name when it accesses these tables. This step should be performed by your companys DBA. To define an explicit table qualifier: 1. 2. 3. 4. Obtain the relevant explicit table qualifier from your DBA (syntax will vary according to which database is used). If you are running the Enterprise Manager, shut it down. Open the file, <Introscope home>/config/
Under the Database Settings section, set the qualifier provided by your DBA. The following are some examples: If using Oracle:
introscope.enterprisemanager.db.tablequalifier property to the table
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.
Save changes. Restart the Enterprise Manager.
Workstation Options
Workstation Logging Options
The following sections describe Workstation logging options.
Running Workstation in Verbose Mode

Running the Workstation in verbose mode records details to the log, which is helpful in debugging. To run the Workstation in verbose mode: 1. Open the file, IntroscopeWorkstation.properties. Page 199
Optional ProbeBuilder Configurations 2. In the property, log4j.logger.Workstation, replace INFO with the following:
3. Save changes.
Redirecting Workstation Output to a File

To redirect Workstation output to a file: 1. 2. Open the file, IntroscopeWorkstation.properties. In the property, log4j.logger.Workstation, replace console with
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.
Connecting Workstation to Enterprise Manager Behind Firewall

This section describes how to connect a Workstation outside a firewall to an Enterprise Manager that is behind one. Workstations initiate connections on the Enterprise Manager port defined in the setting, introscope.enterprisemanager.port.workstation.rmi (default value is 4500) in the file, <Introscope home>/config/ IntroscopeEnterpriseManager.properties. Whichever port is defined in this property must also be opened in the firewall. Workstations also connect to an additional port in order to establish a secure connection during user authentication. This port can be configured in the property, introscope.enterprisemanager.port.workstation.rmi.secure in the IntroscopeEnterpriseManager.properties file. The default value is 4550. Whichever port is defined in this property must also be opened in the firewall. You can disable the second port by setting the
introscope.enterprisemanager.workstation.disableSecureConnection property to true. However, if you disable the secure port, usernames and passwords will
be sent unencrypted over the network.
Optional ProbeBuilder Configurations

Integrating ProbeBuilder into the Build Process
In your build cycle, you will want to run the ProbeBuilder after compiling classes and before running qualification tests, as follows: Introscope 6.0.1 Installation & Configuration Guide (9/15/05) Page 200
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.
AutoProbe ProbeBuilder Log

In addition, the AutoProbe log file name can be set in the IntroscopeAgent.profile file with the property:
introscope.autoprobe.logfile=AutoProbe.log
The default value is AutoProbe.log.
AutoProbe Logging When Using Agent Resource Configuration

The AutoProbe.log file is generated relative to the location of the IntroscopeAgent.profile file. When loading the IntroscopeAgent.profile from a resource on a classpath, AutoProbe will be unable to write to the AutoProbe.log file, because the IntroscopeAgent.profile file is located within a resource.
Miscellaneous Installation Options

Java2 Security Policy
If you are using Java2, you may need to modify the Java security policy file that is used with your managed application. If there are insufficient grants to Introscope-enabled code, you may get security exceptions and, likely, your application will not work correctly.
Page 201
16 Database Configuration and Reporting

This chapter describes the structure of Introscope database tables, how to query information, and the sample reports provided with Introscope. This chapter is intended for a DBA or a database reporting expert who is familiar with SQL and database reporting tools. Information is provided in the following sections: Introscope 6.0.1 Database Schema Database Tables Database Record Types Querying Introscope Database Tables Creating Reports from Introscope Data Other information relevant to database reporting can be found in these sections of the Introscope Installation Guide: Information on configuring your database with Introscope can be found in Enterprise Manager Database Recording, page 193. Information on upgrading your database to work with Introscope 6.0.1 can be found in the Introscope 6.0.1 Upgrade Guide. Information on sending historical data to the database can be found 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. Information on database settings can be found in: Introscope Enterprise Manager.lax File, page 247 IntroscopeEnterpriseManager.properties File, page 242 LDAPAuthenticationExtension.properties, page 252 Database creation and upgrade scripts are located in <Introscope home>/
examples/database.
Page 202
Introscope 6.0.1 Database Schema
Introscope 6.0.1 Database Schema
Note: The database schema has not changed for 6.0.1.
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
Default Actual Name

WT_PROPERTY WT_AGENT WT_RESOURCE WT_METRIC_NAME WT_METRIC WT_RESOURCE_METRIC
Page 204
Database Tables
Logical Name
recordtypetable metadatatable tempquerytable_1 tempquerytable_2 tempquerytable_3 tempquerytable_4 tempquerytable_5
Default Actual Name

WT_RECORD_TYPE WT_METADATA WT_TMP_Q_1 WT_TMP_Q_2 WT_TMP_Q_3 WT_TMP_Q_4 WT_TMP_Q_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.
Metric Name Table

The default name for the Metric name table is WT_METRIC_NAME. The Metric name table has three columns: METRIC_NAME_ID (INTEGER) METRIC_NAME (VARCHAR) METRIC_TYPE (INTEGER) The Metric name table maps each distinct Metric name and type pair to a unique ID.
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.
AGENT_ID (INTEGER) RESOURCE_ID (INTEGER) METRIC_NAME_ID (INTEGER)

The Agent ID, resource ID, and Metric name ID all reference the associated records in their corresponding tables.
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.
ACTUAL_START_TS and ACTUAL_END_TS (TIMESTAMP)

The actual start timestamp is when the collection actually started aggregating data points.
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.
INTEGER_VALUE (BIGINT) INTEGER_MIN (BIGINT) INTEGER_MAX (BIGINT)

The integer value, min and max columns store either integer or long data (Integer data consists of 4-byte signed integers while long data consists of 8-byte signed integers). If the type is long and the database does not support large integral values, the data is stored in the SYS_LONG_VALUE, SYS_LONG_MIN and SYS_LONG_MAX columns instead.
FLOAT_VALUE (FLOAT) FLOAT_MIN (FLOAT) FLOAT_MAX (FLOAT)

The float value, min and max columns store either float or double data. (Float data consists of 4-byte floating point values while double data consists of 8-byte values.)
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
Database Record Types
SYS_VALUE_COUNT (VARCHAR) SYS_LONG_VALUE (VACHAR) SYS_LONG_MIN (VARCHAR) SYS_LONG_MAX (VARCHAR)

The SYS_* columns are used to store long integral values as strings in order to support databases which do not have a corresponding datatype. (Microsoft Access is the main database which does not support 8-byte integer values.)
Resource Metric Table

The default name for the Resource Metric table is WT_RESOURCE_METRIC. The Resource Metric table has three columns: RESOURCE_METRIC_ID (INTEGER) RESOURCE_METRIC (VARCHAR) METRIC_TYPE (INTEGER) The Resource Metric Table saves the Metric structure of every Agent that connects, regardless of what data gets stored to the database. This data is used primarily for mounting historical Agents.
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 Table

The default name for the Record Type table is WT_RECORD_TYPE. The Record Type Table has two columns: RECORD_TYPE_ID (INTEGER) RECORD_TYPE (VARCHAR) The Record Type Table stores record type descriptors used by each WT_METRIC data row.
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.
Database Record Types

Introscope includes database record types. This makes querying and reporting on the historical data easier by identifying records as being of a type, in addition to being records for a particular Metric. For example, the Metric
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.
Querying Introscope Database Tables

This section contains information on querying Introscope database tables. The view used for queries is typically WT_METRIC_VIEW. Queries should always include a value for PERIOD, as the same Metric may have different records written with different PERIODs that cover the same interval of time (e.g. oneand five-minute records). The RECORD_TYPE column can be useful for selecting records which are well-described by record type definitions. The RESOURCE_METRIC column can be useful for selecting records based on their simple Metric name. The INTENDED_END_TS should be used to compare values from different Metrics against other ones, since it is an ideal, exact, rounded time, whereas the ACTUAL_END_TS may be slightly different. When considering data over an interval of time, generally the WHERE conditions around the INTENDED_END_TS values should be similar to the following so that data for the interval is accurately queried. Be sure to include the end time and exclude the start time.
AND
INTENDED_END_TS > start_time_of_interval INTENDED_END_TS <= end_time_of_interval
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.
Creating Reports from Introscope Data

To create database reports from Introscope data, you can use: SQL your databases report tools third-party database reporting software Once you create reports, you can use data and numerical analysis tools to analyze your data.
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)
Single-Metric Tracers and Tracer Groups

In a Directives file, each line that causes the reporting of Metrics is called a Tracer. Tracers can track methods, classes, and sets of classes. A single-Metric Tracer causes the reporting of a specific Metric for a specific method. The smallest unit that Introscope can track is a method.
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.
Only Defined Methods Traced

Introscope can only track methods in classes that are seen by Introscope and that are explicitly defined (not inherited). There are two ways that you can ensure that a method is tracked: Explicitly define the method in the class (it can be a simple wrapper around the inherited method) Trace the superclass that contains the method.
ProbeBuilder Directive Files

There are two kinds of files used to specify ProbeBuilder Directives. You specify one or more of these files to tell the ProbeBuilder where to find the Directives to use. ProbeBuilder Directive files (.pbd files) A ProbeBuilder Directives file contains ProbeBuilder Directives. ProbeBuilder List files (.pbl files) A ProbeBuilder list file contains a list of ProbeBuilder Directives files. Different .pbl files can reference the same .pbd files. Multiple ProbeBuilder Directive files can be specified and are all used together.
Default System ProbeBuilder Files

If you are using AutoProbe, the relevant .pbd and .pbl files for your specific application server are placed in the <appserver home>/wily directory when you install AutoProbe. Introscope provides basic system ProbeBuilder Directives files. These files should generally not be edited, but there are some modifications you can perform. See Modifying Default ProbeBuilder Directives, page 215.
Custom ProbeBuilder Directives Files

While system ProbeBuilder Directives files track basic information, you can customize Introscope to track any classes or methods to obtain specific information about your application. See Creating Custom Tracers, page 220 and Creating Advanced Custom Tracers, page 225.
Default ProbeBuilder Directives Files

Introscope provides a set of ProbeBuilder directives files that gather basic system information. ProbeBuilder directives files included with the Agent for a specific application server will contain ProbeBuilder directives files specific to that application server.
Page 214
Modifying Default ProbeBuilder Directives
Full and Typical ProbeBuilder Directives Sets

Tracer groups cause the reporting of information about a set of classes. Tracer groups are found in PBD files, and referred to in PBL (ProbeBuilder list) files. There are two sets of PBL files available with each Agent installer: Full (default)= references PBD files in which most Tracer Groups in PBD files are turned on. Introscope uses this set by default to demonstrate full Introscope functionality. Typical= a subset of Tracer Groups in the referenced PBD files are turned on. The typical set includes common settings, and is the set you can customize for a particular environment.
Note: For instructions on switching between full and typical .PBL files, see Switching
Between Full and Typical Tracing Options, page 175.

The ProbeBuilder Directive files included with Introscope generally should not be edited. However, the Tracer Groups in the files can be modified in the toggles.pbd files (explained in the following section) by: turning off Tracer Groups to save on system overhead (and turn back on) adding Classes to a Tracer Group
Default Tracer Groups and Toggles Files

The <appserver>-full.pbl and <appserver>-typical.pbl files reference toggles-full.pbd and toggles-typical.pbd files. The Tracer groups are turned on or off within the toggles-full.pbd or toggles-typical.pbd files. In the toggles-full.pbd file, most of the Tracer groups are turned on by default. In the toggles-typical.pbd file, only a subset of Tracer groups are turned on.
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
Default Typical Setting

on on on on on on on on on on on on on on on on
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
Note: Nothing will be traced

until classes are identified with this Tracer group. FileSystemTracing
on
off
Page 216
JAXMListenerTracing JNDITracing JSPDBTagsTagLibraryTracing
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
off off off
JSPIOTagLibraryTracing
on
off
JTACommitTracing EJBMethodLevelTracing SocketTracing UDPTracing SystemOutTracing SystemErrorTracing ThreadTracing XMLSAXTracing XSLTTracing JSPTagLibraryTracing
on on on on off off on on on off
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.
Turning on Toggles To Gather Additional Metric Information

The following three toggles, when turned on, will collect additional Metrics across all APIs.
Name
Default stalled method Tracers DefaultConcurrentInvocatio nTracing Previous rate Metrics
Definition
Stalled method tracing Concurrent invocation information Metric information by rate (not interval count)
Default Full Setting

on on off
Default Typical Setting

on off
Page 217
Turning Tracer Groups On or Off

Turning a Tracer Group On or Off
To turn a Tracer Group on: 1. Locate the toggles-full.pbd or toggles-typical.pbd file (depending on which file type (<appserver>-full.pbl or <appserver>-typical.pbl is in use by AutoProbe or Agent). These files are found within the <appserver home>/wily directory or <Introscope home>/config/systempbd directory. Locate the Tracer group to turn on, and uncomment the line by removing the pound sign from the beginning of the line. The directive in the following example is turned on, and will cause the tracing of all HTTP Servlets.
2.
TurnOn: HTTPServletTracing Note: Any uncommented (turned on) directive for a Tracer group causes the Tracer
group to be used.
Turning a Tracer Group Off
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:
Other examples of default Directives:
TurnOn: SessionBeanTracing TurnOn: EntityBeanTracing TurnOn: SystemOutTracing TurnOn: SystemErrorTracing
Turning On InstrumentPoint Directives

There are two types of directives identified by the keyword, InstrumentPoint: those that trace Exceptions, and one that causes Agent Initialization when the application starts up (instead of when the first Probe is run).
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:
#InstrumentPoint: ThrowException #InstrumentPoint: CatchException
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.
Adding Classes to a Tracer Group

You can turn on tracing for a particular class by adding the class to an existing Tracer group. To identify a class as being part of a Tracer group, use one of the Identify keywords. For example, to add the class, com.myCo.ejbentity.myEJB1, to the Tracer group, EntityBeanTracing:
IdentifyClassAs: com.myCo.ejbentity.myEJB1 EntityBeanTracing

The Identify keywords are: IdentifyInheritedAs IdentifyClassAs IdentifyCorbaAs For details on the Identify keywords, see Directive Keywords, page 227.
EJB Subclass Tracing

By default, entity and session EJB-related Directives add Probes only for EJBs that directly and explicitly implement the entity, session, or message-driven EJB interfaces. Often, an applications EJBs are subclasses of classes which directly and explicitly implement the entity or session EJB interface. These are not tracked by default by Introscope. For EJB subclasses to be tracked by Introscope, they must be added to the appropriate Tracer group. To do this, add entries that refer to the direct ancestors of the EJB subclasses to be tracked. From these models, replace <entity.bean.ancestor.class> or <session.bean.ancestor.class> with the fully-qualified class name of the immediate ancestor of the EJBs to be Introscope-enabled. For entity EJBs:
IdentifyInheritedAs: <entity.bean.ancestor.class> EntityBeanTracing

For session EJBs:
IdentifyInheritedAs: <session.bean.ancestor.class> SessionBeanTracing

The examples below are based on this class hierarchy:
Page 219
Creating Custom Tracers
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.

Custom Tracers are constructed using a specific syntax and keywords. This section describes how to construct custom Tracers. Choose methods to trace carefully. More methods traced means more overhead. Custom Tracers must be saved in a custom Directives file (.pbd). Introscope includes an example file with Custom Tracers in it, located in <Introscope home>/examples/ CustomTracerExample.pbd. You can use this file as a template for your own custom .pbd file.
Custom Tracers and Keywords

To construct a Tracer, you must define: which method or class to trace information to collect about the method or class There are four directives available for custom tracing: TraceOneMethodOfClass - traces a specified method in the specified class. TraceAllMethodsOfClass - traces all methods in the specified class. TraceOneMethodIfInherits - traces one method in all direct subclasses or direct interface implementations of the specified class or interface. TraceAllMethodsIfInherits - traces all methods in all direct subclasses or direct interface implementations of the specified class or interface.
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:
<directive>: <class> <method> <Tracer-name> <metric-name>

TABLE 9. Tracer Components Tracer component Definition
A fully qualified class or interface name to trace. Fully qualified means it includes the full package of the class as well as the name, for example, com.mycompany.mypackage.MyClass. The simplest method specifier is the name of the method to trace. If just the name of the method is given, all instances of the method are traced, regardless of signature. If a signature is also given, only the instance with that signature will be traced. (See also Signature Differentiation, page 225.) Specifies how the method is to be traced. See Table 10 on page 221 for descriptions of tracer names. To use these Tracers with Blame Technology, use the Tracers with names prefixed with Blamed. (See Custom Tracers in Blame Technology, page 224.) Controls how the collected data is displayed in the Workstation. The following examples describe the three ways to specify the name and location of a Metric at different levels of the Metrics tree. metric-name The Metric appears immediately inside the Agent. resource:metric-name The Metric appears inside one Resource (folder) below the Agent. resource|sub-resource|sub-sub-resource:metric-name The Metric appears more than one Resource (folder) level deep below the Agent, use pipe characters (|) to separate the Resources.
<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.
Note: This tracer requires a platform monitor on
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.
Note: This tracer requires a platform monitor on
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
MethodTraceIncrementor and MethodTraceDecrementor
BlamedMethodTraceIncrementor and MethodTraceDecrementor
ConcurrentInvocationCounter
Page 222
Custom Method Tracer Examples

The following are Tracer examples found in the CustomTracerExample.pbd file. Quotes are used around the Metric names in these examples because of spaces in the Metric names.
Example Average Tracer

This Tracer tracks the average execution time of the given method in milliseconds.
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlamedMethodTimer "Petstore|Catalog|search:Average Method Invocation Time (ms)"
Example Rate Tracer

This Tracer counts the number of times the method is called per second, and report this rate under the specified Metric name.
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlamedMethodRateTracer "Petstore|Catalog|search:Method Invocations Per Second"
Example Per Interval Counter Tracer

This method Tracer counts the number of times the method is called per interval, and reports the per interval count under the specified Metric name. The interval is determined by the monitoring logic in the Enterprise Manager, such as the Persistent Collection frequency or Graph frequency. The preview pane in the Explorer defaults to 15 second intervals.
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search PerIntervalCounter "Petstore|Catalog|search:Method Invocations Per Interval"
Example Counter Tracer

This Tracer counts the total number of times the method is called.
TraceOneMethodOfClass: com.sun.petstore.cart.ShoppingCart placeOrder BlamedMethodTraceIncrementor "Petstore|ShoppingCart|placeOrder:Total Order Count"
Example Combined Counter Tracers

These Tracers combine incrementor and decrementor Tracers to keep a running count.
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
Custom Tracers in Blame Technology

Introscopes Blame Technology works in a managed Java Application to enable you to identify component interactions and component resource usage. Blame Technology tracks components that you specify in custom Blamed Tracers and classes that are part of Tracer groups, including classes you add. Blame Technology uses the concepts of consumers and resources. Consumers request some activity; resources perform the activity. A component can be both a consumer and a resource, depending on the context. In the Explorer tree, the word Called designates a resource. This resource is a resource (a subresource) of the parent component, which is the consumer. For example, under the consumer Servlets, there may be a subresource Called EJB. Introscope shows only one level of consumer-resource interaction, even if there are several levels to the interaction. If there are several levels, each component is shown as a consumer with its immediate resources. For example, if a servlet is a consumer of network sockets and is also a consumer of an EJB which is a consumer of JDBC, the tree might look like the following: Sockets Input Bandwidth Output Bandwidth Servlets Average Response Time Responses Per Second Responses Per Interval Main Servlet Average Response Time Responses Per Second Called EJB MyEJB Average Method Invocation Time Method Invocations Per Interval Called Sockets Input Bandwidth Output Bandwidth EJB Average Method Invocation Time Method Invocations Per Interval MyEJB Called JDBC Average Response Time Responses Per Second JDBC Average Query Time Queries Per Second
Page 224
Creating Advanced Custom Tracers
Creating Advanced Custom Tracers

This section describes advanced custom Tracers: Advanced Single-Metric Tracers Signature Differentiation Metric-Name-Based Parameters Skips Combining Custom Tracers
Advanced Single-Metric Tracers

Signature Differentiation
Tracers can be applied to a method based on the method signature. To trace a single instance of a method with a specific signature, append the signature to the method name (including return type) specified using the internal method descriptor format. For example, myMethod(Ljava/lang/String;)V traces the instance of the method with a string argument and void return type. For complete information about this format, see the Sun Java Virtual Machine Specification, section 4.3.3, Method Descriptors, and section 4.3.2, Field Descriptors, http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html.
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:
"{packagename}|{classname}|{method}:Response Time (ms)"
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:
"myPackage|myClass|myMethod:Response Time (ms)"
Example 2:
If a Tracer with a Metric name in the .pbd file of
"{packageandclassname}|{method}:Response Time (ms)"

was applied to the same method, the resulting Metric name would be
"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:
TraceOneMethodWithParametersOfClass: order process(LJava/lang/ string;)V MethodTimer Order|{0}Order:Average Response Time (ms)

This Tracer produces Metrics like these: Order BookOrder Average Response Time (ms) MusicOrder Average Response Time (ms) You can also use the TraceOneMethodWithParametersIfInherits keyword. For more information on both keywords, see Directive Keywords, page 227.
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.
Combining Custom Tracers

You can use multiple Tracers that affect the same Metric, in effect combining them. This is most commonly used with incrementors and decrementors. Example: This example creates a Metric named Logged-in Users. With a class user and methods login and logout, create the following Tracers:
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.
Counting Object Instances

The new Tracer Group, InstanceCounts, counts the number of instances of the particular object types associated with it (for information on associating object types with the InstanceCounts Tracer Group using the standard IdentifyClassAs and IdentifyInheritedAs directives, see Adding Classes to a Tracer Group, page 219). Any instances explicity allocated in your code will be counted. Subtypes will also be counted. Objects created through different mechanisms, such as deserialization or cloning, might not be counted. Tracing using this Tracer Group could potentially incur incremental performance (and memory) impact, depending on the number of instances counted.
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
<method> <name> <Tracer-group>
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. Name of Tracer group to use.
ProbeBuilder Skip Keywords

The two Skip keywords cause the ProbeBuilder to skip over a class or a package. SkipClass: <class-name> Prevents the listed class from being Introscope-enabled. Only the specific class is skipped. SkipPackage: <package-name> Prevents the listed package from being Introscope-enabled. All classes in the listed package are skipped.
ProbeBuilder Action Keywords

The keywords below cause the ProbeBuilder to take action: IdentifyClassAs: <class-name> <Tracer-group> Adds the specific class to the specified Tracer group. IdentifyCorbaAs: <Tracer-group> Adds all CORBA classes to the specified Tracer group. IdentifyInheritedAs: <class-name> <Tracer-group> Adds all direct subclasses or interfaces to the specified Tracer group. If a class is specified, it adds all direct subclasses. If an interface class name is specified, it adds all direct implementers of that interface. InstrumentPoint: <ThrowException> or <CatchException> ThrowException
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.
Threshold ProbeBuilder Action Keywords

The following directives, TraceOneMethodWithThresholdOfClass, and TraceAllMethodsWithThresholdOfClass, only work with the following Tracers: StalledMethodTracer OverThresholdPerIntervalCounter UnderThresholdPerIntervalCounter
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.
Updating Introscope With Modified or New ProbeBuilder Directives Files

After youve created your Custom Directives files, you must mark them for usage when you Introscope-enable your bytecode, and then update the probes in Introscope to use the new directives.
Page 231
Updating Introscope With Modified or New ProbeBuilder Directives Files
Adding New Custom ProbeBuilder Directives Files

After youve created your Custom Directives files, you must specify which ones to use when you Introscope-enable your bytecode. Custom-created Directives files or Directives list files (.pbl) must be placed in a certain directory for Introscope to recognize them.
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.
IntroscopeAgent.profile file, and resolves filenames relative to this directory.
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.
Using ProbeBuilder Wizard

1. 2. 3. Place custom directives files in the <Introscope home>/config/custompbd directory. The files you placed in the <Introscope home>/config/custompbd directory will appear in the Custom Directives screen during the ProbeBuilder Wizard process. On the Custom Directives screen, select the custom directives files to use (see Adding Probes to Bytecode With ProbeBuilder Wizard, page 157).
Using Command-line ProbeBuilder

1. The Command-line ProbeBuilder looks for any custom directives files in the same directory where the ProbeBuilder is run from, and resolves filenames relative to this directory. For ease of use, place the custom .pbd and .pbl files in the <Introscope home>/config/custompbd directory. When running the Command-line ProbeBuilder, refer to the custom .pbd and .pbl files in the command line (see Adding Probes to Bytecode Using Command-Line ProbeBuilder, page 163).
2.
Applying Changes To ProbeBuilder Directives Files

Whether you create new custom Directives files or modify existing Directives files, you must update the probes in Introscope by rerunning the ProbeBuilder or relaunching your managed application with AutoProbe. Specifically:
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.
Using the ProbeBuilder Wizard or the Command-Line ProbeBuilder

1. 2. 3. 4. 5. Make changes to Directives files. Stop your managed application. Run the ProbeBuilder (through the ProbeBuilder Wizard or Command-line ProbeBuilder). Start the managed application. If they are not already running, start the Enterprise Manager and the Workstation.
Page 233
A Introscope Properties Files

This appendix describes the properties files and settings you can customize in your Introscope deployment.
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
Introscope Agent Settings File

Agent configuration is done in the IntroscopeAgent.profile file. The properties found in this file may differ, depending on whether the Introscope Agent is configured for use with AutoProbe and a specific application server, or without AutoProbe, and used with ProbeBuilder Wizard or command-line ProbeBuilder. The table at the end of this section details all possible properties that may be found in this file.
Agent Settings with AutoProbe Installation

If you are using AutoProbe, the file, IntroscopeAgent.profile will be installed by your Agent installer by default in the <appserver home>/wily directory. Use this file to set configuration information for AutoProbe and the Agent. Change the AutoProbe settings according to your deployment: If the Web Application Server and the Enterprise Manager are on the same computer, no changes to the IntroscopeAgent.profile file are necessary. If they are on different computers (recommended for production), edit the IntroscopeAgent.profile file and change the Enterprise Manager host name and port. If other changes are desired, edit the IntroscopeAgent.profile file as necessary. If you edit the IntroscopeAgent.profile file, edit the version that is used by the managed application (located by default in the wily directory in the Web Application Server or Virtual Machine directory).
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.
Agent Settings Common to Both AutoProbe and non-AutoProbe Installations

Log 4J Settings
Two properties define the level of detail in the Agent logs and the name and location of Introscope Agent log files. See Log4J documentation at http://jakarta.apache.org/log4j/docs/documentation.html for information on advanced Log4J functionality.
Enterprise Manager Connection Order

This setting defines the order in which the Agent will attempt to connect to the Enterprise Managers listed in the Enterprise Manager Locations and Names section.
Enterprise Manager Locations and Names

These settings define the host, port, and unique names of the Enterprise Managers the Agent can connect to.
Agent and Process Name Settings

These properties specify details on the Agent name and how it will be obtained. The Agent and Process names used as part of the Fully-Qualified Agent Name (Domain | host | process | Agentname) to track information of a single Agent over multiple Agent sessions.
Note: These properties are optional. If the Agent name is not defined, it will be known as
UnknownAgent.
Agent Thread Priority

The Agent, by default, uses an average priority TCP/IP connection. This setting is usually sufficient. However, if you know your managed application is designed to complete its work as fast as possible (take highest priority), you should then set the introscope.agent.thread.all.priority property to the same or higher priority as the managed application, to prevent data starvation (where data never gets sent to the Enterprise Manager).
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).
Note: Any time-related Metric collections are recorded in microseconds (1/1,000,000th

of a second), instead of milliseconds (1/1,000th of a second), which is the usual Introscope time period.
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.
Transaction Tracer Properties

These properties are used by the Agent to communicate with the Transaction Tracer. TABLE 14. File:<Introscope home>/examples/IntroscopeAgent.profile This Setting
introscope.autoprobe.enable
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
AutoProbe.log varies by installer
log4j.logger.IntroscopeAgent log4j.appender.logfile.File introscope.agent.sockets.reportRateMetr ics
INFO, console IntroscopeAgent.log true
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
introscope.agent.enterprisemanager.tran sport.tcp.host.DEFAULT introscope.agent.enterprisemanager.tran sport.tcp.port.DEFAULT introscope.agent.enterprisemanager.tran sport.tcp.socketReadTimeoutInSecond introscope.agent.enterprisemanager.failb ackRetryIntervalInSeconds introscope.agent.customProcessName
localhost 5001
60
Commented out; 120
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.
introscope.agent.agentNameSystemProp ertyKey introscope.agent.agentAutoNamingEnabl ed
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
introscope.agent.disableLogFileAutoNam ing introscope.agent.agentName
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
Note: For data to be provided to

this module, JVMPI must be turned on in WebSphere.
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
introscope.agent.pmi.enable.j2c introscope.agent.pmi.enable.webService s introscope.agent.pmi.enable.wlm
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:
J2EEServer,Applica tion,j2eeType,JDBC Provider,name,mbea nIdentifier
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.clonedAgent introscope.agent.platform.monitor.syste m introscope.agent.leakhunter.enable introscope.agent.leakhunter.logfile.locati on
Commented out; false Commented out; Solaris true LeakHunter.log
Note: If property is commented

out or left blank, no log file will be written.
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
Note: Turning on this option has

the potential to create higher system overhead, in CPU usage and memory. introscope.agent.sqlagent.sql.useblame introscope.agent.transactiontracer.userid .method introscope.agent.transactiontracer.userid .method introscope.agent.transactiontracer.userid .key introscope.agent.transactiontracer.userid .method introscope.agent.transactiontracer.userid .key introscope.agent.transactiontracer.para meter.httprequest.headers introscope.agent.transactiontracer.para meter.httprequest.parameters introscope.agent.transactiontracer.para meter.httpsession.attributes Specifies whether SQL Agent will generate blame Metric data. Specifies the HttpServletRequest.getRemote User method to specify User IDs. Specifies the HttpServletRequest.getHeader method to specify User IDs. User-defined key string Specifies the HttpServletRequest.getValue method to specify User IDs. User-defined key string Specifies (in comma-separated list) httprequest header data to capture. Comma separated list. Specifies (in comma-separated list) httprequest parameter data to capture. Specifies (in comma-separated list) http session attribute data to capture. Commented out; true Commented out;
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
Introscope ProbeBuilder Settings File
Introscope ProbeBuilder Settings File

Introscope ProbeBuilder Wizard.lax File
TABLE 15. File: <Introscope home>/Introscope ProbeBuilder Wizard.lax This Setting
lax.nl.current.vm
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
Introscope Enterprise Manager Settings Files

The files described in the following sections contain settings for the Introscope Enterprise Manager. The Introscope Enterprise Manager reads these files at startup. If you make changes, you must restart the Enterprise Manager for these changes to take effect.
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
Transaction Event Database

These properties define the directory the Enterprise Manager uses to store transaction events (including transaction traces and error information), and how long to store them.
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.)
Flat File Properties

Flat files are plain-text comma-separated value (.csv) files. Introscope can write to flat files, but cannot read from them. You can analyze flat files with numerical analysis tools. Flatfile recording is enabled by default and directed to the <Introscope home>/ flatfiles directory. You can also specify that these files reside in a directory outside of the Introscope directory. Note that for Windows paths, you must escape backslashes (\) with another backslash (doubled), such as: C:\\Introscope\\FlatFileDir.
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
Note: This property is not present in the

EM properties file, it must be typed in manually. introscope.enterprisemanager.port.w orkstation.rmi introscope.enterprisemanager.port.w orkstation.rmi.secure Enterprise Manager machine port that communicates with Workstations. Additional Enterprise Manager machine port used for secure (SSL) connection with Workstations. Port defined in this property must also be opened in the firewall. Disables the secure Workstation port. 4500 4550
introscope.enterprisemanager.workst ation.disableSecureConnection
false
Note: If this property is used, usernames

and password information will be sent unencrypted over the network.
introscope.enterprisemanager. port.agentlistener log4j.logger.Manager log4j.appender.logfile.File
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.
5001 INFO, console IntroscopeEnt erpriseManage r.log 60
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
Note: SmartStor does not interfere with
data being sent to Persistent Collections. data
Specifies the directory SmartStor will use.
Note: Do not touch this.

Specifies the frequency (in seconds) of data collection for the first data tier. Specifies the number of days after which data in first tier ages out of SmartStor. Specifies the frequency (in seconds) of data collection for the second data tier. 15 1 60
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
introscope.enterprisemanager.db.bat chInsertSize introscope.enterprisemanager.db.qu eryTimeoutInSeconds
Commented out 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
introscope.enterprisemanager.flatfile .maxTimeInHours introscope.enterprisemanager.flatfile .disableCompression
Commented out; 24 false
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 control flag
Specifies name and location of extension configuration file
Introscope Enterprise Manager.lax File

TABLE 17. File: <Introscope home>/Introscope Enterprise Manager.lax This Setting
lax.class.path
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.
lax.nl.java.option. additional lax.stderr.redirect
Page 247
Introscope Workstation Settings Files
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

The files described in the following sections contain settings for the Introscope Workstation.
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
Introscope Workstation.lax File

TABLE 20. File: <Introscope home>/Introscope Workstation.lax This Setting
lax.command.line.args
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
Introscope WebView Settings Files
Introscope WebView Settings Files

The files described in the following sections contain settings for Introscope WebView.
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.
Introscope WebView.lax File

TABLE 22. File: <Introscope home>/Introscope WebView.lax This Setting
lax.class.path
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
Varies by operating system
lax.nl.java.option. additional
-classic -ms64m -mx256m The classic setting invokes Java 2 classic VM.
Page 250
Database Settings Files
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
Database Settings Files

The file described in the following section contains settings related to database usage with Introscope.
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
Extensions Settings Files

LocalAuthenticationExtension.properties
This file contains the configuration properties for the local authentication extension. TABLE 24. File: <Introscope home>/config/ LocalAuthenticationExtension.properties This Setting
authentication.extension.lo cal.userFile
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
Extensions Settings Files
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
cn=Users, dc=dev, dc=com subtree userPrincipalName (&(userPrincipalNam e=%u)(objectclass= user))
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.
License for JDOM Binary Distribution

Copyright (C) 2000 Brett McLaughlin & Jason Hunter. 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, the disclaimer that follows these conditions, and/or other materials provided with the distribution. The names "JDOM" and "Java Document Object Model" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact license@jdom.org. Products derived from this software may not be called "JDOM", nor may "JDOM" appear in their name, without prior written permission from the JDOM Project Management (pm@jdom.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.
License for Tanuki Software Distribution

Copyright (c) 1999, 2003 TanukiSoftware.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
Blame Technology 23 blamed tracers 221, 222
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
Console 24 Console mode

49
AutoProbe
Application Server AutoProbe 96 with Oracle 10g 139
custom Tracers. See ProbeBuilder Directives
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
flat file properties 243 Fujitsu Interstage

using Introscope 5.0 with 94
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
Domains and Users

overview 76 with Agent Failover 93
E
Element 26 Enterprise Manager 22
Page 258
system requirements 29
Interstage
using Introscope with 94
Enterprise Manager settings 63, 64 Workstation settings 199, 200
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
message URL http

//wrapper.tanukisoftware.org/doc/english/ properties.html 65
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
Metric 23 Metric Grouping 23
O
Oracle Application Server 10g
configuring with Introscope 136141 basic Agent settings 140 installing Agent on 136 ProbeBuilder configuration options 137
organization of book 15 OS/390

base structure for Java 67 customizing UNIX shell script 71 DASD 70 DB2 68 DB2 considerations on 74 Enterprise Manager OS/390 files and partitioned dataset 71 installing Enterprise Manager on 70 JDBC 69 PROC customizing 72 executing 72 running Enterprise Manager as a batch job in 67 running Enterprise Manager as started task 72 running Enterprise Manager on 72 security and authorization 68 software prerequisites for Java 67
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
starting Enterprise Manager 59 starting Enterprise Manager automatically on 74
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
ProbeBuilder Directives 212

applying changes to 232 components tracked 213 components tracked in 213 custom Tracers 220 combining 227 creating 220 examples template 223 files custom 161, 214 updating Introscope with 232 system 160, 214 keywords 227 action 228 IdentifyClassAs 228 IdentifyCorbaAs 228 IdentifyInheritedAs 228 InstrumentPoint 228 TraceAllMethodsIfInherits 229 TraceAllMethodsOfClass 229 TraceOneMethodOfClass 229 TraceOneMethodWithParameterIfInherits 229
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
ProbeBuilder Wizard 22, 155161

adding Probes to bytecode with 157
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
IntroscopeEnterpriseManager.properties 242 IntroscopeWebView.properties 250 IntroscopeWorkstation.properties 249
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
Transaction Event Database

configuration during GUI installation 41 settings 62, 243
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
SNMP Collections 243 Sun ONE Application Server

configuring with Introscope 128135 basic Agent settings 133 installing Agent on 128 ProbeBuilder configuration options 129
User
modifiers and syntax 82
SuperDomain 23 system requirements

Introscope 29 JVM 31 memory 31
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 6.0 109 Websphere 6.0 111 WebSphere Application Server

configuring custom service for 116, 127 configuring with Introscope 106116 basic Agent settings 113 installing Agent on 106 ProbeBuilder configuration options 107 PMI data 189193 enabling and defining 191 viewing 192 WebSphere 4.0 disabling automatic Agent naming for 115
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

WI 6.0.1InstallConfigGuide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

WI 6.0.1InstallConfigGuide

Încărcat de

Drepturi de autor:

Formate disponibile

Installation and Configuration Guide

Version 6 Release 6.0.1

Introscope 6.0.1 Installation and Configuration Guide

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

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Chapter 5 Configuring Introscope Security and Permissions . . . . . . . . . . . . . 76

. . 99 . . 99 . . 99 . . 99 . 100 . 100 . 101 . 101 . 101 . 101 . 102 . 102

Chapter 8 Configuring WebSphere Application Server With Introscope . . . 106

Chapter 9 Configuring WebSphere on z/OS With Introscope . . . . . . . . . . . 117

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

. 118 . 119 . 119 . 120 . 121 . 122 . 124

Chapter 10 Configuring Sun ONE Application Server With Introscope . . . . 128

Chapter 11 Configuring Oracle Application Server 10g With Introscope . . . 136

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

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

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Chapter 15 Optional Introscope Configurations. . . . . . . . . . . . . . . . . . . . . . 168

Miscellaneous Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Java2 Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Chapter 16 Database Configuration and Reporting . . . . . . . . . . . . . . . . . . . 202

Chapter 17 ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Using the ProbeBuilder Wizard or the Command-Line ProbeBuilder . . . . . . 233

Appendix A Introscope Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Appendix B Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

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 Guide (this guide)

Introscope 6.0.1 Workstation Guide

Introscope 6.0.1 WebView Guide

Organization of the Introscope 6.0.1 Installation Guide

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Type Conventions Used in this Book

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Need Help With Installation?

root login, as:

C:\<your-applicationpath>.isc\classes; \<your-applicationpath>.isc\lib\app.jar; \Introscope\lib\Agent.jar

Need Help With Installation?

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

How Introscope Works

How Introscope Works

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Components and Terms

Managed Java Application

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Components and Terms

ProbeBuilder Wizard and Command Line ProbeBuilder

ProbeBuilder and Directives

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Components and Terms

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Components and Terms

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Components and Terms

Introscope 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Components and Terms

2 Preparing For Installation

Preparing To Install Introscope

User Name EM1_________ EM2_ EM3_ EM4_________

Password EM1___ EM2_ EM3_ EM4___