installation and configuration guide - the content...

Installation and Configuration Guide

Version 6 Release 6.0.1

Wily Technology, Inc.8000 Marina Boulevard, Suite 700Brisbane, 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 GuideCopyright © 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 MicroSys-tems, Inc.AIX, AS/400, z/OS, iSeries and WebSphere are registered trademarks of International Busi-ness 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 Corpora-tion.

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)

Contents - Detailed

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Introscope 6.0.1 Installation and Configuration Guide Audience . . . . . . . . . . . 15

Introscope 6.0.1 User Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Introscope 6.0.1 Upgrade Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15Introscope 6.0.1 Installation and Configuration Guide (this guide) . . . . . . . . . . .15Introscope 6.0.1 Workstation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15Introscope 6.0.1 WebView Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Organization of the Introscope 6.0.1 Installation Guide . . . . . . . . . . . . . . . . . . 16

Need Help With Installation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 1 Introscope Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19How Introscope Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Introscope Components and Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21Managed Java Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21Probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21ProbeBuilder Wizard and Command Line ProbeBuilder . . . . . . . . . . . . . . . .22ProbeBuilder and Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22Metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Metric Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Blame Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23SuperDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24Introscope Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Dashboard Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Management Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Chapter 2 Preparing For Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Preparing To Install Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Step 1: Plan Where To Install Introscope Components . . . . . . . . . . . . . . . . . . .27Step 2: Choose Installation Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Install Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Introscope Installer Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28


Supported Modes By Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Step 3: Check System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Bundled JVMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31JVM Used by Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Step 4: Review Installation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Information to Collect Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Enterprise Manager Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Reviewing Installation and Configuration Process . . . . . . . . . . . . . . . . . . . . . . . 33Starting the Installation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Chapter 3 Installing Introscope Components . . . . . . . . . . . . . . . . . . . . . . . . . 35Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Installing Introscope In GUI Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Installation in GUI mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Launching GUI Mode Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37GUI Installation Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37Next Steps - Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . .49

Installing Introscope In Console Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Launching Console Mode Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

Using z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50Using Any Other Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50Next Steps - Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . .51

Installing Introscope In Silent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Response File Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Using an Automatically-generated Response File . . . . . . . . . . . . . . . . . . .51Using a Manually-Configured Sample Response File . . . . . . . . . . . . . . . . .51

Launching Silent Mode Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Using z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Using Any Other Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Next Steps - Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . .53

Uninstalling Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Uninstall Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Forcing an Uninstall Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54Running Uninstaller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

Chapter 4 Configuring and Running the Introscope Enterprise Manager. . . . 57Installing License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Starting Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58Windows (Enterprise Manager not configured as a Windows Service) . . . . .58OS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Writing Status Information to Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59Running the Enterprise Manager as a Java Program . . . . . . . . . . . . . . . . . . . . .59Stopping Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59


Enterprise Manager Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

SmartStorTM Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Configuring SmartStor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

Enabling SmartStor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Determining SmartStor System Requirements . . . . . . . . . . . . . . . . . . . . .61Specifying SmartStor Data Tier Values . . . . . . . . . . . . . . . . . . . . . . . . . .61

Transaction Event Database Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Configuring Transaction Event Database Settings . . . . . . . . . . . . . . . . . . . . . . .62

Enterprise Manager Metric Throttle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Configuring Enterprise Manager Metric Throttle . . . . . . . . . . . . . . . . . . . . . . . .63

Enterprise Manager Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Running Enterprise Manager in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . .63Redirecting Enterprise Manager Output to a File . . . . . . . . . . . . . . . . . . . . . . . .64

Running Enterprise Manager in nohup Mode on UNIX . . . . . . . . . . . . . . . . . . . . 64Additional Enterprise Manager Configurations . . . . . . . . . . . . . . . . . . . . . . . . . .64

Configuring Enterprise Manager To Run As A Windows Service . . . . . . . . . . . . . 65Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65Configure and Register Enterprise Manager as a Windows Service . . . . . . . . . . .65

Register Enterprise Manager as a Service . . . . . . . . . . . . . . . . . . . . . . . .65Deregister Enterprise Manager(s) Running as a Windows Service . . . . . . . . . . . .66Changing Windows Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66Running 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 . . . . . . . . . . . . . . 67Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Overview of Installation Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Copying and Customizing Introscope Enterprise Manager Files . . . . . . . . . .70Customizing the Introscope Enterprise Manager Properties File . . . . . . . . .70Customizing runem.sh – the UNIX Shell Script . . . . . . . . . . . . . . . . . . . . .71Copying Introscope Enterprise Manager z/OS files to a z/OS Partitioned Dataset (PDS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71Customizing the z/OS PROC That Invokes BPXBATCH . . . . . . . . . . . . . . . .72

Running the Introscope Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . .72Executing the z/OS PROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Starting the Introscope Enterprise Manager automatically . . . . . . . . . . . . .74

DB2 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Database Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . .75

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

Configuring and Managing Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Domain Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76


SuperDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76User-defined Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Creating Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77Domain Attributes and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77Domain Creation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77Creating a Domain and Mapping Agents . . . . . . . . . . . . . . . . . . . . . . . . .78Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78

Associating Management Modules With Domains . . . . . . . . . . . . . . . . . . . . . . .78Adding Sample Management Module to Newly Created Domains . . . . . . . . .79

Changing the Domain Mapping of an Agent . . . . . . . . . . . . . . . . . . . . . . . . . . .79Deleting a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79Merging Two Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80Moving a Domain From One Introscope Installation to Another . . . . . . . . . . . . . .80

Moving a Domain Between Installations To Clone the Domains . . . . . . . . . .80Moving a Domain Between Non-cloned Installations . . . . . . . . . . . . . . . . .80

Configuring User Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Local User Authentication Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Configuring Local Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Configuring Enterprise Manager to Use Local Authentication . . . . . . . . . . .82Configuring Location or Name of Local Authentication File . . . . . . . . . . . . .82

Defining a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82User Configuration Modifiers and Syntax . . . . . . . . . . . . . . . . . . . . . . . . .82Defining a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83Generating Encoded Passwords (Optional) . . . . . . . . . . . . . . . . . . . . . . . .83Default User Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

Configuring External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Configuring LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

Configuring Enterprise Manager to Use LDAP Authentication . . . . . . . . . . .85Configuring LDAP Authentication Extension . . . . . . . . . . . . . . . . . . . . . . .85LDAP Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

Defining User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Permissions Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Domain Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88Domain Access Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88Domain Permissions Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89Defining Domain Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90Domain Permissions and the Explorer Tree . . . . . . . . . . . . . . . . . . . . . . .91

Server Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91Server Permissions Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91Server Permissions Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92Defining Server Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92

Agent Failover and Domain/User Configuration . . . . . . . . . . . . . . . . . . . . . . . . .93

Chapter 6 Configuring Java Applications With Introscope . . . . . . . . . . . . . . . 94

Chapter 7 Configuring WebLogic Server With Introscope . . . . . . . . . . . . . . . 95Configuring Introscope With WebLogic Overview . . . . . . . . . . . . . . . . . . . . . . . 95

Installing Introscope Agent With WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . .96


JVM AutoProbe Using Java 5.0 JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99JVM AutoProbe With WebLogic Using Sun or IBM JVM . . . . . . . . . . . . . . . . . . . .99

Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99Running AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

JVM AutoProbe With WebLogic Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . . 100JVM AutoProbe With WebLogic Using WebLogic JRockit . . . . . . . . . . . . . . . . . . 100Application Server AutoProbe With WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . 101

Application Server AutoProbe With WebLogic 8.1 . . . . . . . . . . . . . . . . . . 101Application Server AutoProbe With WebLogic 7.0 . . . . . . . . . . . . . . . . . . 101Application Server AutoProbe With WebLogic 6.1 SP3 . . . . . . . . . . . . . . . 101Application Server AutoProbe With WebLogic 6.1 . . . . . . . . . . . . . . . . . . 102Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 102

Configuring Basic Agent Settings for WebLogic . . . . . . . . . . . . . . . . . . . . . . . . 102Agent Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Defining Agent Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Configuring Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Creating a WebLogic Startup Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Configuring a Startup Class In WebLogic 8.1 . . . . . . . . . . . . . . . . . . . . . 105Optional WebLogic Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

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

Installing Introscope Agent on WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 107JVM AutoProbe With WebSphere Using Sun or IBM JVM . . . . . . . . . . . . . . . . . . 108

Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

JVM AutoProbe With WebSphere Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . 110Application Server AutoProbe With WebSphere . . . . . . . . . . . . . . . . . . . . . . . . 111

Application Server AutoProbe With WebSphere 6.0/5.1/5.0 . . . . . . . . . . . 111Application Server AutoProbe With WebSphere 4.0 (Distributed) . . . . . . . 112Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 113

Configuring Basic Agent Settings on WebSphere . . . . . . . . . . . . . . . . . . . . . . . 113Agent Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113


Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Configuring a Custom Service in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . 116

Configuring a Custom Service in WebSphere 6.0/5.0 . . . . . . . . . . . . . . . . 116Optional WebSphere Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

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

Installing Introscope Agent on WebSphere on z/OS . . . . . . . . . . . . . . . . . . . . 117

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118


Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 118JVM AutoProbe With WebSphere Using IBM JVM . . . . . . . . . . . . . . . . . . . . . . . 119


Application Server AutoProbe With WebSphere for z/OS . . . . . . . . . . . . . . . . . 121Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS . . . . . 122Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 124

Configuring Basic Agent Settings for WebSphere . . . . . . . . . . . . . . . . . . . . . . . 124Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124New z/OS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Using PMI with Introscope on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Configuring a Custom Service in WebSphere 5.0 . . . . . . . . . . . . . . . . . . . . . . 127

Configuring a Custom Service in WebSphere 5.0 . . . . . . . . . . . . . . . . . . 127Optional WebSphere Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Further Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

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

Installing Introscope Agent on Sun ONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 129JVM AutoProbe With Sun ONE 7.0 Using Sun JVM . . . . . . . . . . . . . . . . . . . . . . 130


Application Server AutoProbe With Sun ONE . . . . . . . . . . . . . . . . . . . . . . . . . 131Application Server AutoProbe With Sun ONE 7.0 . . . . . . . . . . . . . . . . . . . 131Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 133

Configuring Basic Agent Settings for SunONE . . . . . . . . . . . . . . . . . . . . . . . . . 133Agent Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133


Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

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

Installing Introscope Agent on Oracle 10g . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 137JVM AutoProbe With Oracle 10g Using Sun JVM . . . . . . . . . . . . . . . . . . . . . . . 138


Application Server AutoProbe With Oracle Application Server 10g . . . . . . . . . . . 139Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 139

Configuring Basic Agent Settings for Oracle 10g . . . . . . . . . . . . . . . . . . . . . . . 140Agent Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140




Chapter 12 Configuring SAP NetWeaver With Introscope . . . . . . . . . . . . . . 142Configuring Introscope With SAP NetWeaver Overview . . . . . . . . . . . . . . . . . 142

Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 143JVM AutoProbe Using Sun or IBM JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144


JVM AutoProbe Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Configuring Basic Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Agent Profile Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147



Chapter 13 Configuring Other Application Servers or Applications With Intro-scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Configuring Introscope With Other Application Servers Overview . . . . . . . . . 149

Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 150JVM AutoProbe Using Java 5.0 JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151JVM AutoProbe Using Sun or IBM JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151


JVM AutoProbe Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152




Chapter 14 Configuring the Java Applications Manually With ProbeBuilder 155Configuring Java Applications Manually Overview . . . . . . . . . . . . . . . . . . . . . . 155

Configuring Java Applications With ProbeBuilder Wizard . . . . . . . . . . . . . . . . 155Installing Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Adding Probes to Bytecode With ProbeBuilder Wizard . . . . . . . . . . . . . . . . . . . 157Editing the Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Configuring Java Applications With Command-Line ProbeBuilder . . . . . . . . . . 162Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Adding Probes to Bytecode Using Command-Line ProbeBuilder . . . . . . . . . . . . . 163Editing the Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164





Options for Running Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . 166

Switching Back to Your Non-Introscope-enabled Code . . . . . . . . . . . . . . . . . . 167

Chapter 15 Optional Introscope Configurations. . . . . . . . . . . . . . . . . . . . . . 168Agent Naming Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Agent Name Location Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Obtaining Agent Name Using System Properties . . . . . . . . . . . . . . . . . . . . . . . 169

Specifying Agent Name Using Java System Property . . . . . . . . . . . . . . . . 169Specifying Agent Name Using System Property Key . . . . . . . . . . . . . . . . 170

Obtaining Agent Name Automatically From Application Server . . . . . . . . . . . . . 170Supported Application Server Versions . . . . . . . . . . . . . . . . . . . . . . . . . 170How Automatic Agent Naming Works . . . . . . . . . . . . . . . . . . . . . . . . . . 170Automatic Agent Naming and Renamed Agents . . . . . . . . . . . . . . . . . . . 171Enabling Automatic Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Advanced Automatic Naming Options . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Agent Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Configuring Agent Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Configuring Automatic Agent Failback to Primary Enterprise Manager . . . . . . . . 175Agent Failover and Domain/User Configuration . . . . . . . . . . . . . . . . . . . . . . . . 175

Switching Between “Full” and “Typical” Tracing Options . . . . . . . . . . . . . . . . 175Switching to “Typical” Tracing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Multiple Agent Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Enabling Cloned Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Enabling Cloned Agent Naming in the Agent Profile . . . . . . . . . . . . . . . . . 177

Running An Application Twice On One Machine . . . . . . . . . . . . . . . . . . . . . . . . 177How Introscope Resolves Agent Naming Conflicts . . . . . . . . . . . . . . . . . . . . . . 177

Other Optional Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Using Custom ProbeBuilder Directives Files (AutoProbe installations only) . . . . . 177Removing Line Numbers in Bytecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Turning Off Socket Input/Output Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Agent Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Agent Log Files and Automatic Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . 179

Agent Logfile Automatic Naming Notes . . . . . . . . . . . . . . . . . . . . . . . . . 179Running Agent in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Redirecting Agent Output to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Enabling Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Enabling Platform Monitors on Windows Server 2003 . . . . . . . . . . . . . . . 181Enabling Platform Monitors on AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Disabling Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Platform Configuration Troubleshooting Option . . . . . . . . . . . . . . . . . . . . . . . . 182

JMX Filters For Obtaining Advanced Performance Data . . . . . . . . . . . . . . . . . . 182WebLogic 9.0 MBean Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Metric Name Conversion and Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Primary Keys Conversion Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Default Conversion Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184JMX Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Configuring JMX Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Step 1: Enabling JMX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185


Step 2: Defining Primary Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Step 3: Defining JMX Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Viewing JMX Data In Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

WebLogic Diagnostic Framework Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Metric Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Obtaining WLDF Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Advanced WebSphere Performance Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Turning on Performance Monitor Settings in WebSphere . . . . . . . . . . . . . . . . . 189

Turning on Performance Monitor Settings in WebSphere 6.0/5.0.x . . . . . . 189Turning on Performance Monitor Settings in WebSphere 4.0 (Distributed) . 189

Enabling and Defining PMI Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Viewing WebSphere Agent PMI Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Enterprise Manager Database Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Upgrading Database Schema Tables From Previous Versions . . . . . . . . . . . . . . 194Configuring a New Enterprise Manager to Database Connection . . . . . . . . . . . . 194

Running Database Creation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Setting Database Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Sample Microsoft Access Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Optional Enterprise Manager Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 197Running Enterprise Manager Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Configuring Scheduled Export of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Configuring Scheduled Export of Data . . . . . . . . . . . . . . . . . . . . . . . . . . 198Adding or Moving Management Modules Between Enterprise Managers . . . . . . . 198Defining Explicit Table Qualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Workstation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Workstation Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Running Workstation in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 199Redirecting Workstation Output to a File . . . . . . . . . . . . . . . . . . . . . . . . 200

Connecting Workstation to Enterprise Manager Behind Firewall . . . . . . . . . . . . 200

Optional ProbeBuilder Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Integrating ProbeBuilder into the Build Process . . . . . . . . . . . . . . . . . . . . . . . . 200ProbeBuilder Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

AutoProbe ProbeBuilder Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

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

Chapter 16 Database Configuration and Reporting . . . . . . . . . . . . . . . . . . . 202Introscope 6.0.1 Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Version Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Index Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Property Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Agent Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Resource Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Metric Name Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Metadata Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Metric Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Resource Metric Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Record Type Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Database Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209


Querying Introscope Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Creating Reports from Introscope Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Introscope Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Chapter 17 ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Introduction to Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Components Tracked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Single-Metric Tracers and Tracer Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Only Defined Methods Traced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214ProbeBuilder Directive Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Default System ProbeBuilder Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Custom ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Default ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Full and Typical ProbeBuilder Directives Sets . . . . . . . . . . . . . . . . . . . . . . . . . 215

Modifying Default ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Default Tracer Groups and Toggles Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Turning on Toggles To Gather Additional Metric Information . . . . . . . . . . 217Turning Tracer Groups On or Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Turning a Tracer Group On or Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Turning On InstrumentPoint Directives . . . . . . . . . . . . . . . . . . . . . . . . . 218

Adding Classes to a Tracer Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219EJB Subclass Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Creating Custom Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Custom Tracers and Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Tracer Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Custom Method Tracer Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Example Average Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Example Rate Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Example Per Interval Counter Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Example Counter Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Example Combined Counter Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Custom Tracers in Blame Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Creating Advanced Custom Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Advanced Single-Metric Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Signature Differentiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Keyword-Based Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Metric-Name-Based Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Skips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Combining Custom Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Counting Object Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Directive Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227ProbeBuilder Skip Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228ProbeBuilder Action Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Threshold ProbeBuilder Action Keywords . . . . . . . . . . . . . . . . . . . . . . . . 230

Updating Introscope With Modified or New ProbeBuilder Directives Files . . . . 231Adding New Custom ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . 232

Using AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Using ProbeBuilder Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Applying Changes To ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . 232Using AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232


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

Appendix A Introscope Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . 234Introscope Agent Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Agent Settings with AutoProbe Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Agent Settings Common to Both AutoProbe and non-AutoProbe Installations . . . 235Log 4J Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Enterprise Manager Connection Order . . . . . . . . . . . . . . . . . . . . . . . . . . 235Enterprise Manager Locations and Names . . . . . . . . . . . . . . . . . . . . . . . 235Agent and Process Name Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Agent Thread Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235PMI Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235JMX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236LeakHunter Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Transaction Tracer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Introscope ProbeBuilder Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Introscope ProbeBuilder Wizard.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Introscope Enterprise Manager Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . 242IntroscopeEnterpriseManager.properties File . . . . . . . . . . . . . . . . . . . . . . . . . 242

Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Log 4J Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242SmartStor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Transaction Event Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Database Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Flat File Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243SNMP Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243WebView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Introscope Enterprise Manager.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247EMService.conf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Introscope Workstation Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248IntroscopeWorkstation.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Introscope Workstation.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Introscope WebView Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250IntroscopeWebView.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Introscope WebView.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Database Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251CustomDBRecordTypes.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Extensions Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252LocalAuthenticationExtension.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252LDAPAuthenticationExtension.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Appendix B Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Apache Software License, Version 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

License for JDOM Binary Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

License for Tanuki Software Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257


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 GuidesIntroscope 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 GuideThe 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 GuideThe Introscope 6.0.1 Workstation Guide is intended for users who view management application data and configure monitoring logic in the Introscope Workstation.


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


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 BookConvention Is Used For

Courier font File, directory and property names, computer output or code input examples

bold font User interface menu items and screen prompts.

<italic font> Variable names that will be replaced with actual items. For example: Replace <filename> with the name of an actual file.

blue text A hyperlinked cross reference within an Introscope Guide (in the PDF file, when clicked, it jumps to the link destination)

purple italicized text Cross reference between Introscope Guides (not hyperlinked)

Introscope directory

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.

In UNIX Unless stated otherwise, examples in this book use conventions for UNIX machines.

/ (slash) Separates directory and file names in UNIX path names as,

/Introscope6.0.1/examples/IntroscopeAgent.profile.


Need Help With Installation?

Need Help With Installation?For more help with configuring Introscope, please contact Wily Technical Support at 1-888-GET-WILY or [email protected].

# (pound sign) UNIX prompt with root login, as:

# cd /usrDo 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:/<your-applicationpath>.isc/lib/app.jar:/Introscope6.0.1/lib/Agent.jar

_ (underscore) Separates words in UNIX launcher application names.

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

\ (backslash) Separates directory and file names in Windows path names, as C:\Introscope\bin\pdh.dll

; (semicolon) 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.

Convention Is Used For


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 application’s 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.

Introscope’s 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 application’s 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.


How Introscope Works

How Introscope WorksFigure 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 application’s 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.


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:


AgentThe 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 application’s business logic. Probes track real-time performance information, making the information available for review and action.

ProbeBuilder • Refers to ProbeBuilder Directives files to define data to be collected

• Adds Probes to Java Application

Probes • Collects data defined by ProbeBuilder Directives files• Sends collected data to Agent

Agent • Sends collected data to the Enterprise Manager

Enterprise Manager • Receives collected data from Agent

Workstation • Connects to the Enterprise Manager to view data• Configures the Enterprise Manager

Database • Receives data from the Enterprise Manager



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



• Hewlett-Packard HotSpot JVM v1.2.2.08 or higher

• WebLogic JRockit 7.0 and higher


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



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

Introscope’s 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.

WorkstationThe following terms relate to the Introscope Workstation.



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.



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.



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


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


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)


• ProbeBuilder settings:


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



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 doesn’t 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

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

Interface and Platform GUI Console Silent Mode Default Mode

Windows Yes No Yes GUI

AIXSolarisHP-UXRed Hat Linux

Yes Yes Yes GUI

OS/400 No Yes Yes none

z/OS No Yes Yes none

Other Yes Yes Yes GUI

Introscope Component Supported Platforms



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

Enterprise Manager Most major operating systems including:

• Windows 2000• Windows Server 2003• Solaris• AIX• HP-UX• z/OS

Workstation • Microsoft Windows 2000• Windows Server 2003• Windows XP

Agent (managed application) Any operating system and hardware combination supported by J2EE application server vendor

WebView Windows and Internet Explorer 6 or higher

What How Much Details

Hard Drive Space • 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

Space required for package including JVM

Temporary Directory Space

200 MB The amount of space required differs depending on the platform and installer type used.

SmartStor 8GB (with default settings) SmartStorTM records all application performance data (Introscope Metrics) at all times. SmartStor is enabled by default during Introscope installation.

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.



Memory Requirements

Table 4 shows the minimum memory each component requires.

TABLE 4. Component Requirements

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

ComponentRequired Minimum Memory

Workstation 128 MB

Enterprise Manager 128 MB

ProbeBuilder Wizard 128 MB

WebView 128 MB

AutoProbe N/A

Command Line ProbeBuilder 128 MB

Managed applications with Version 6.0.1 Agent N/A

Operating System JDK

Solaris Sun JDK 1.4.2_03


Information to Collect Before You Begin

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

Windows Sun JDK 1.4.2_03

AIX IBM JDK 1.4.1

HP-UX HP JVM 1.4.1.03

Red Hat Linux Sun JDK 1.4.1

z/OS none

OS/400 none


Reviewing Installation and Configuration Process

TABLE 6. Enterprise Manager Information To Collect

Reviewing Installation and Configuration ProcessAfter you’ve checked the system requirements and collected the appropriate access and configuration information for your deployment, you’re 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. Run the Introscope installer, which can install and specify basic configurations for all core Introscope components but the Agent.

3. Install and configure the Introscope Agent.

4. Introscope-enable your Java application(s), using either JVM AutoProbe, Application Server AutoProbe, ProbeBuilder Wizard or Command-Line ProbeBuilder.

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

5. Configure Domains and user permissions.

6. Configure authentication, either local or external.

7. Configure any optional functionality for Introscope components, such as Agent Failover, or JMX and PMI information.

8. Start up everything and see the Agent reporting.

Starting the Installation ProcessTo 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.


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

For SAP Support Only

Operating System Installer Including Agent Installer Without Agent

Windows introscope6.0.1windowsinstall.zip introscope6.0.1windows.zip

Solaris introscope6.0.1solarisinstall.tar introscope6.0.1solaris.tar

HP-UX introscope6.0.1hpuxinstall.tar introscope6.0.1hpux.tar

AIX introscope6.0.1aixinstall.tar introscope6.0.1aix.tar

Red Hat Linux introscope6.0.1linuxinstall.tar introscope6.0.1linux.tar

OS/400 introscope6.0.1os400install.zip introscope6.0.1os400.zip

z/OS introscope6.0.1zOSinstall.tar introscope6.0.1zOS.tar

Other introscope6.0.1otherinstall.tar introscope6.0.1other.tar

Operating System Installer Filename

Windows introscope6.0.1windowsinstall.SAPExpertCenter.zip


Installing Introscope In GUI Mode

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

For SAP Support Only

Installing Introscope In GUI ModeAfter 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.

Solaris introscope6.0.1solarisinstall.SAPExpertCenter.tar

HP-UX introscope6.0.1hpuxinstall.SAPExpertCenter.tar

AIX introscope6.0.1aixinstall.SAPExpertCenter.tar

Linux introscope6.0.1linuxinstall.SAPExpertCenter.tar


Windows introscope6.0.1windows.exe

Solaris introscope6.0.1solaris.bin

HP introscope6.0.1hpux.bin

AIX introscope6.0.1aix.bin

Red Hat Linux introscope6.0.1linux.bin

OS/400 introscope6.0.1os400.jar

z/OS introscope6.0.1zOS.jar

Other introscope6.0.1other.jar


Windows introscope6.0.1windows.SAPExpertCenter.exe

Solaris introscope6.0.1solaris.SAPExpertCenter.bin

HP-UX introscope6.0.1hpux.SAPExpertCenter.bin

AIX introscope6.0.1aix.SAPExpertCenter.bin

Linux introscope6.0.1linux.SAPExpertCenter.bin



Installation in GUI modeThis 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.



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.



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.



• 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 don’t have a Wily license, you can install it later. Click Next, then Skip License.

6. Click Next.



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.




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



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.


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.



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.



• 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 doesn’t exist yet (or hasn’t 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.



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



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:



— 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 command-line 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.


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


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



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>



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 doesn’t exist or the path is invalid, the installer will attempt to run in GUI mode. However, if GUI mode isn’t supported on the platform, the installer will fail.




Uninstalling Introscope

Uninstalling IntroscopeThe 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 ModesThe 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. Open the file, <Introscope home>/Uninstaller Data/Uninstall Introscope.lax.

2. Find the property, lax.command.line.args=$CMD_LINE_ARGUMENTS$ -u

3. 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 UninstallerTo uninstall Introscope components:

1. Locate the Introscope uninstaller for your platform:

• Windows: <Introscope home>/Uninstaller Data/Uninstall Introscope.exe.



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



• 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. Manually delete any extra files that exist in the Introscope directory.

6. Repeat the uninstall process on other machines as necessary.


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 didn’t 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


Installing License

Installing LicenseIf you chose not to install a license during the installation process, use the following instructions.

1. To obtain a license, contact your Wily Technology sales representative.

2. Place the license file in the <Introscope home>/license directory on the machine that will run the Enterprise Manager.

Starting Enterprise ManagerAfter 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 &


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 LogfileAs 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 ProgramYou 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 ManagerTo 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


Enterprise Manager Ports

Enterprise Manager PortsDesignate 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. Open the file, <Introscope home>/config/introscopeEnterpriseManager.properties

2. Under Port Settings, find the property, introscope.enterprisemanager.port.agentlistener

3. 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 StorageSmartStorTM functions like a flight recorder. It records all application performance data (Introscope Metrics) at all times while it’s 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 SmartStorSmartStor 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. Open the file, IntroscopeEnterpriseManager.properties.

2. For the property, introscope.enterprisemanager.smartstor.enable, enter a value of true.


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.

SmartStor’s 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:


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:


2. For the introscope.enterprisemanager.smartstor.tier1.frequency property, enter the desired value.

3. For the introscope.enterprisemanager.smartstor.tier1.age property, enter the desired value.

4. Repeat for the remaining two data tier property pairs.

5. Restart the Enterprise Manager.

Note: If you change your data tiers and reboot the Enterprise Manager, SmartStor will do its best to adjust data to your new configuration, but it may lose a day’s worth of data.

Transaction Event Database StorageTransaction 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 Settings1. Open the file, IntroscopeEnterpriseManager.properties.

2. Make the desired changes to the following properties:

Property Function Notes

introscope.enterprisemanager.transactionevents.storage.dir

Specifies where to store transaction event data.

Select a location that has at least 2 GB of available space.


Enterprise Manager Metric Throttle

3. Save changes.

Enterprise Manager Metric ThrottleOccasionally 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 couldn’t 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 ThrottleIf 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:


2. Add the property, introscope.enterprisemanager.agent.metrics.limit, to the file, and enter a value for the Metric throttle limit.

3. Save changes.


Enterprise Manager Logging Options

Running Enterprise Manager in Verbose ModeRunning 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.enterprisemanagter.transactionevents.storage.max.data.age

Specifies (in days) how long to store transaction event data.

Increasing the data aging period has overhead and storage implications.


Running Enterprise Manager in nohup Mode on UNIX


2. 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 FileTo redirect Enterprise Manager output to a file:


2. 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.Log4JSeverityLevel,logfile

3. If desired, change the name and/or location of the Enterprise Manager logfile in the property, log4j.appender.logfile.File.

4. Save changes.

Running Enterprise Manager in nohup Mode on UNIXThe 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 ConfigurationsFor additional optional Enterprise Manager configurations, see Chapter 15, Optional Introscope Configurations.


Configuring Enterprise Manager To Run As A Windows Service


OverviewA 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 RequirementsThe 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. Shut down the Enterprise Manager.

2. In the file, IntroscopeEnterpriseManager.lax make sure the following property is blank:

lax.stdin.redirect




4. In the file, IntroscopeEnterpriseManager.properties, ensure the following property is set to true, as shown in the example below:



6. 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. Save changes to the <Introscope home>/EMService.conf file.

8. 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 ServiceThere 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. Stop the Enterprise Manager Service and shut down the Windows Services GUI.

2. Run <Introscope home>/DeregisterEMService.bat.

Note: If either the Enterprise Manager Service or the Windows Services GUI are active, 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.

Changing Windows Service PropertiesIf 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.


Configuring Enterprise Manager To Run As a z/OS Batch Job

Running the Enterprise Manager as a Windows ServiceUse 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.

Configuring Enterprise Manager To Run As a z/OS Batch JobTo 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:



• 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 user’s 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 user’s 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



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

2. The DB2 CLI application plan must be public. Execute the following command from SPUFI or from a batch job:

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.



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.



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. Uncomment the property, introscope.enterprisemanager.db.useBatchInserts=true.

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



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

3. 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 DD PATH='/<path>/stdout',

//STDERR DD PATH='/<path>/stderr',

Copy WILYPROC into an active PROCLIB

♦ Using ISPF option 3, copy the PROC to xxxx.PROCLIB where xxxx represents an site-dependent 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.



♦ 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 JOB installation jobcard parameters,NOTIFY=&SYSUID

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



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



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


5 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 DomainsA 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 TypesThere 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.


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

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

Modifier value Rules

name name of Domain • alphanumeric characters only, and _ and -• no spaces allowed

description short description of Domain

• any characters except quotation marks

agent mapping fully-qualified Agent name (Domain|host|process|Agent) for Agent

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



• 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. Open the file, <Introscope home>/config/domains.xml in an xml editing program.

2. 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. Save and close the domains.xml file.

4. Restart the Enterprise Manager so it can load the new Domain(s).

Note: If there are any syntax or other errors in the domains.xml file, the Enterprise Manager will not start.

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



2. Move the desired Management Module from the <Introscope home>/config/modules directory into the new directory you just created.

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

Note: IMPORTANT! The Sample Management Module copied into the new Domain is NOT 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.

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


2. Delete the Domain from the <Introscope home>/config/domains.xml file.

3. If necessary, reassign any mapped Agents to different Domains.

4. Delete the corresponding Domain directory from <Introscope home>/config/modules.




Merging Two DomainsMerging two Domains involves merging all Agent mapping information into one Domain, and moving any associated Management Modules under one Domain.

To merge two Domains:


2. Open the <Introscope home>/config/domains.xml file.

3. Under the source Domain (for example, Domain A), copy the Agent mapping XML code information.

4. Under the target Domain (for example, Domain B), paste the Agent mapping XML code information.

5. Delete Agent mapping XML code from the source Domain (e.g., Domain A).

6. 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. Delete the source Domain from domains.xml.


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. Copy the <Introscope home>/config/domains.xml file in the source installation over to the same directory in the target installation.

2. Copy the <Introscope home>/config/shutoff/MetricShutoffConfiguration.xml in the source installation over to the same directory in the target installation.

3. Copy the contents of the <Introscope home>/config/modules/<domain> directory from the source installation to the target installation.


Moving a Domain Between Non-cloned Installations

If the Domain configurations between the old and new installations vary slightly, use the following steps:


Configuring User Authentication

1. Open the <Introscope home>/config/domains.xml file in the source installation.

2. Copy the Domain information.

3. Open the <Introscope home>/config/domains.xml file in the target installation.

4. Copy the Domain information into the domains.xml file.

5. In the target installation, create new Management Module directories that correspond to those in the source installation in <Introscope home>/config/modules.

6. Copy any Management Modules that belong to the Domain you are moving over and paste them into the corresponding Domain directories.

7. Delete the Domain from the source installation.


Configuring User AuthenticationIntroscope 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 OverviewLocal 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)



Configuring Local Authentication

Configuring Enterprise Manager to Use Local Authentication

Introscope uses local authentication by default. To check that local authentication is used:

1. Open the file, <Introscope home>/config/IntroscopeEnterpriseManager.properties.

2. Locate the Authentication Providers section.

3. For the property, 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 doesn’t 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. Open the file, <Introscope home>/config/LocalAuthenticationExtension.properties.

2. For the property, authentication.extension.local.userFile, enter the path of the users.xml file.

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


name username • alphanumeric characters only, and _ and -



Here is the syntax for configuring a user:

<users>

<user name="username" password="password">

</user>

</users>

Defining a User

To define a user:

1. Open the <Introscope home>/config/users.xml file in an xml editing program.

2. Define a user name and password using the above attributes and syntax.


3. Repeat step two for any additional users required.

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

password user password • 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



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:

• for Windows, MD5Encoder.bat <password>• for Unix, MD5encoder.sh <password>

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.

Configuring External AuthenticationIf 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 AuthenticationIntroscope’s LDAP authentication works with the following supported v3 LDAP servers:



• 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. Make sure the LDAP extension is present in the following location: <Introscope home>/ext/LDAPAuthenticationExtension.jar.


3. Locate the Authentication Providers section.

4. 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=Wily-LDAP

introscope.enterprisemanager.authentication.controlFlag.ldap=REQUIRED

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:



This Setting Specifies Default Setting

authentication.extension.ldap.url= URL for the remote LDAP server

The default port for non-SSL connections is 389, the default port for SSL connections is 636.

Note: If you are using SSL, the SSL LDAP port should be part of the server URL.

ldap://host:port

authentication.extension.ldap.useSSL Whether to use SSL to connect to remote LDAP server

false

authentication.extension.ldap.bindName Name used to bind to LDAP server. If blank, anonymous bind is used.

IntroscopeLDAPUser

authentication.extension.ldap.bindPassword

Password used to bind to LDAP server. If anonymous bind is used, this property is ignored.

password123

authentication.extension.ldap.bindAuthentication

Authentication type to use when binding.

Options are: none, simple, CRAM-MD5.

simple

authentication.extension.ldap.user.nameSuffix

Suffix to append to Introscope user name for use with LDAP queries.

@dev.com

authentication.extension.ldap.user.baseDN

Base distinguished name (DN) for all user object queries

cn=Users, dc=dev, dc=com

authentication.extension.ldap.user.scopeDepth

Search depth when querying for a user object

subtree

authentication.extension.ldap.user.usernameAttribute

Name of LDAP attribute that will match an Introscope username

userPrincipalName

authentication.extension.ldap.user.userObjectQuery

LDAP search filter used to query a user object. The token “%u” will be filled in with the Introscope username before the query executes.

(&(userPrincipalName=%u)(objectclass=user))

authentication.extension.ldap.serverCertificate

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://java.sun.com/j2se/1.4.2/docs/index.html).

blank


http://java.sun.com/j2se/1.4.2/docs/index.html




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)(objectclass=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.user.nameSuffix=

authentication.extension.ldap.user.baseDN=ou=users,dc=acme,dc=com


authentication.extension.ldap.user.usernameAttribute=uid

authentication.extension.ldap.user.userObjectQuery=(&(uid=%u)(objectclass=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





[email protected]

authentication.extension.ldap.user.baseDN=cn=Users,dc=dev,dc=com


authentication.extension.ldap.user.usernameAttribute=cn

authentication.extension.ldap.user.userObjectQuery=(&(cn=%u)(objectclass=user))

authentication.extension.ldap.serverCertificate=config/sulu5.cer

Defining User PermissionsSetting 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



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

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




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. Open the <Introscope home>/config/domains.xml file in an xml editing program.

2. For each Domain, define permissions for each user, with the above attributes and syntax.


3. Repeat for any additional users required.

4. Save and close the domains.xml file.

Note: If there are any syntax or other errors in the domains.xml file, the Enterprise Manager will not start.

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

live_agent_control User can shut off reporting for Metrics, Resources, and Agent within Domain


full User has all possible permissions for Domain.




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



Server Permissions Defined

The following table defines the server permissions available.

TABLE 10. 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. Open the <Introscope home>/config/server.xml file in an xml editing program.

2. Define permissions for each user, with the above attributes and syntax.


3. Repeat for any additional users required.

4. Save and close the server.xml file.

Note: If there are any syntax or other errors in the server.xml file, the Enterprise Manager will not start.

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


shutdown User can shut down the Enterprise Manager.

purge_metrics User can remove Metrics from persistent data store (only database)

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



<grant user="bsmith" permission="shutdown" />

<grant user="tjones" permission="purge_metrics" />

<grant user="tjones" permission="publish_mib" />

</server>

Agent Failover and Domain/User ConfigurationIf 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.


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 Use the instructions in this chapter

WebLogic Chapter 7, Configuring WebLogic Server With Introscope

WebSphere (distributed) Chapter 8, Configuring WebSphere Application Server With Introscope

WebSphere on z/OS Chapter 9, Configuring WebSphere on z/OS With Introscope

Sun ONE Chapter 10, Configuring Sun ONE Application Server With Introscope

Oracle 10g Chapter 11, Configuring Oracle Application Server 10g With Introscope

Fujitsu Interstage 6.0 (Japanese version)

Please contact Wily support to obtain Japanese installation instructions.

SAP NetWeaver Chapter 12, Configuring SAP NetWeaver With Introscope

Other Application Server (other than those listed above)

Chapter 13, Configuring Other Application Servers or Applications With Introscope

Any - Using ProbeBuilder Wizard or Command-Line ProbeBuilder

Chapter 14, Configuring the Java Applications Manually With ProbeBuilder


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 OverviewThere 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 WebLogicTo install the Introscope Agent on WebLogic:

1. Make sure that the WebLogic Server version 6.1 or higher and any required patches have been installed.

2. 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 system’s working directory, commonly the Web Application Server’s 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


ProbeBuilder Configuration Options

• Several .pbd and .pbl files (ProbeBuilder Directives and List files)

ProbeBuilder Configuration OptionsA 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 OptionThe following table details the ProbeBuilder options available for each WebLogic Server version and JVM combination. To find the appropriate ProbeBuilder method:

1. Choose the row containing your WebLogic Server version.

2. Choose a ProbeBuilder configuration option.

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



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 JVM AutoProbe Using Java 5.0 JVM, page 99

JRockit JVM AutoProbe With WebLogic Using WebLogic JRockit, page 100

WebLogic 8.1

JVM AutoProbe

Sun JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99

IBM JVM AutoProbe With WebLogic Using Sun or IBM JVM, page 99

HP JVM AutoProbe With WebLogic Using HP HotSpot JVM, page 100


Application Server AutoProbe

any Application Server AutoProbe With WebLogic 8.1, page 101

Manual ProbeBuilder

any Chapter 14, Configuring the Java Applications Manually With ProbeBuilder

WebLogic 7.0

JVM AutoProbe









Manual ProbeBuilder


WebLogic 6.1SP3

JVM AutoProbe





any Application Server AutoProbe With WebLogic 6.1 SP3, page 101

Manual ProbeBuilder


WebLogic 6.1

JVM AutoProbe






Manual ProbeBuilder




JVM AutoProbe Using Java 5.0 JVMThe 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 JVMThere 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. Change the working directory to wily/connectors under the installation directory.

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



• all JVMs but IBM JVM 1.2.x:

-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>:<path-to-Agent.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.


JVM AutoProbe With WebLogic Using HP HotSpot JVMThe following instructions work with HP HotSpot JVM:

1. Install HP Hotspot JVM 1.2.2.08 or higher. This can be obtained from http://www.hp.com/products1/unix/java.

2. 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 JRockitThe 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:


-Xmanagement:class=com.wily.introscope.api.jrockit.AutoProbeLoader

Note: The above command should be all on one line.


http://www.hp.com/products1/unix/java/



• For WebLogic JRockit 7.0:

-Djrockit.preprocessor.class=com.wily.introscope.api.weblogic.PreProcessor



Application Server AutoProbe With WebLogicThe 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. Edit the classpath in the application startup script (such as startMedRecServer.cmd) to include the wily/Agent.jar file.

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



1. Edit the Java classpath in the WebLogic Server startup script (startWLS.cmd) to include the wily/Agent.jar file.

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



Application Server AutoProbe With WebLogic 6.1 SP3

The following instructions work with WebLogic 6.1 SP3:

1. Edit the Java classpath in the WebLogic startup script (such as StartPetstore.cmd) to include the wily/Agent.jar file.

2. Set the following property on the Java command line with the -D option. This will activate Introscope AutoProbe:


Configuring Basic Agent Settings for WebLogic





1. Edit the Java classpath in the WebLogic startup script to include the wily/Agent.jar file.


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. Locate the <WebLogic home>/wily/toggles-full.pbd.

2. Go to the HTTP Servlets Configuration section.

3. 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. Repeat steps 2-4 for <WebLogic home>/wily/toggles-typical.pbd


Configuring Basic Agent Settings for WebLogicThe 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 LocationIntroscope looks for the Agent profile in a set sequence of three locations:

• the location defined in the system property, com.wily.introscope.agentProfile


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


Additional Configuration Options

Additional Configuration OptionsThere 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.

Property Value and Description

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

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

Note: 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, introscope.enterprisemanager.port.agentlistener in the introscopeEnterpriseManager.properties file for each matching Enterprise Manager. See Uninstalling Introscope, page 54.


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.



Creating a WebLogic Startup ClassThe 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. Open the WebLogic 8.1 Administrative Console.

2. In the left pane, expand the Deployments folder.

3. Click the Startup & Shutdown folder. The Startup and Shutdown page appears.

4. 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. Check the box(es) for the server(s) you’d like to make this startup class available to. Click Apply.

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


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


• Configuring Basic Agent Settings on WebSphere

Configuring Introscope With WebSphere OverviewThere are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager:




Installing Introscope Agent on WebSphereTo install the Introscope Agent on WebSphere:

1. Make sure that the WebSphere Application Server 4.0 or higher and any required patches have been installed.

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



• Agent.jar


• WebAppSupport.jar • connectors/CreateAutoProbeConnector.jar • Several .pbd and .pbl files (ProbeBuilder Directives and List files)





• JVM AutoProbe







Choosing ProbeBuilder Configuration OptionThe following table details the ProbeBuilder options available for each WebSphere Application Server version and JVM combination. To find the appropriate ProbeBuilder method:

1. Choose the row containing your WebSphere Application Server version.






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





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:



ProbeBuilder Configuration Option JVM

Use the Instructions In This Section

WebSphere6.0/5.1/5.0

JVM AutoProbe

Sun JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108

IBM JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108

HP JVM AutoProbe With WebSphere Using HP HotSpot JVM, page 110


any Application Server AutoProbe With WebSphere 6.0/5.1/5.0, page 111

Manual ProbeBuilder


WebSphere 4.0

JVM AutoProbe

Sun JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108

IBM JVM AutoProbe With WebSphere Using Sun or IBM JVM, page 108

HP JVM AutoProbe With WebSphere Using HP HotSpot JVM, page 110


any Application Server AutoProbe With WebSphere 4.0 (Distributed), page 112

Manual ProbeBuilder







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:











Running the AutoProbe Connector


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 Administrator’s 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:


3. Click OK.

4. Apply the changes in the Administrator’s Console.

5. Restart the Web Application Server.



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. In WebSphere, start the Administrator’s Console, and go to the JVM Settings section for the application server you want to modify.

2. Click Advanced JVM Settings. A new window will open.

3. In the Boot classpath (prepend) field, enter the following command:

wily/connectors/AutoProbeConnector.jar:<path-to-Agent.jar>




JVM AutoProbe With WebSphere Using HP HotSpot JVMThe following instructions work with HP HotSpot JVM:








Application Server AutoProbe With WebSphereThe following sections describe how to configure your deployment to use Application Server AutoProbe.

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. Add the Agent.jar to the runtime extensions directory for WebSphere at <product_installation_root>/lib/ext.

2. In WebSphere, start the Administrator’s 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.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.











//permissions for Introscope AutoProbe


permission java.io.FilePermission "${was.install.root}${/

}wily${/}-", "read";









};

grant {


};

Application Server AutoProbe With WebSphere 4.0 (Distributed)

The following instructions work with WebSphere 4.0:

1. Add the Agent.jar to the runtime extensions directory for WebSphere at <product_installation_root>/lib/ext.


3. Add the following two system properties:


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>







1. Locate <WebSphere home>/wily/toggles-full.pbd.






5. Repeat steps 2-4 for <WebSphere home>/wily/toggles-typical.pbd


Configuring Basic Agent Settings on WebSphereThe 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.




Configuring Basic Agent Settings on WebSphere

• if com.wily.introscope.agentProfile is not defined, (or the Agent profile is not found in the defined location), it looks in the location defined in com.wily.introscope.agentResource

• if neither of the prior two properties were defined (or the Agent profile was not found in the defined location), Introscope looks for the Agent profile in the <working directory>/wily directory.



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








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



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. Open the Agent profile, usually IntroscopeAgent.profile.

2. Set the value of the property, introscope.agent.agentAutoNamingEnabled, to false.

Additional Configuration OptionsThere 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.
















Configuring a Custom Service in WebSphereThe 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. Open the WebSphere Administrative Console.

2. 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. Click OK.


Optional WebSphere ConfigurationsSee the following sections for information on optional WebSphere configurations.



• Advanced WebSphere Performance Data, page 189



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.


• Installing Introscope Agent on WebSphere on z/OS


• Configuring HTTP Servlet Tracing For Application Server AutoProbe

Configuring Introscope With WebSphere on z/OS OverviewThere are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager:




You may also choose to configure to run your Enterprise Manager as a z/OS batch job.

Installing Introscope Agent on WebSphere on z/OSTo install the Introscope Agent on WebSphere on z/OS:

1. Make sure that the WebSphere Application Server 5.0 or higher and any required patches have been installed.

2. Find the WebSphere installer file:

• IntroscopeAgentInstall6.0.1websphere.zOS.tar



• Agent.jar


• WebAppSupport.jar • connectors/CreateAutoProbeConnector.jar • Several .pbd and .pbl files (ProbeBuilder Directives and List files)





• JVM AutoProbe







Choosing ProbeBuilder Configuration OptionThe following table details the ProbeBuilder options available for each WebSphere Application Server version and JVM combination. To find the appropriate ProbeBuilder method:

1. Choose the row containing your WebSphere Application Server version.






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





JVM AutoProbe With WebSphere Using IBM JVMThere are two steps required to configure and use JVM AutoProbe with IBM JVM:





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:



• 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



WebSphere 5.x and 6.0 on z/OS

JVM AutoProbe

IBM JVM AutoProbe With WebSphere Using IBM JVM, page 119


any Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS, page 122

Manual ProbeBuilder




To create the AutoProbe connector:











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:


2. Select Application Servers > <your server> > Process Definition.

3. You should see two items, Control and Servant. Click Servant, then Java Virtual Machine.

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




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.

8. Restart WebSphere.

9. Proceed to the section, Configuring Basic Agent Settings for WebSphere, page 124 to configure the Agent profile.
















};

grant {


};

Application Server AutoProbe With WebSphere for z/OSThis section contains instructions specifically for configuring Application Server AutoProbe for WebSphere on z/OS.



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:


2. Select Application Servers > <your server> > Process Definition.

3. You should see two items, Control and Servant. Click Servant, then JavaVirtualMachine.

4. 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.wily.introscope.agentProfile=<path to IntroscopeAgent.profile>

OR


-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



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. Restart WebSphere application server.

9. When WebSphere says “open for e-business,” open the Administrator’s Console. Metrics should start reporting.

















};

grant {


};


Configuring Basic Agent Settings for WebSphere




1. Locate <WebSphere home>/wily/toggles-full.pbd.






5. Repeat steps 2-4 for <WebSphere home>/wily/toggles-typical.pbd

6. Proceed to the section, Configuring Basic Agent Settings for WebSphere, page 124 to configure the Agent profile.

Configuring Basic Agent Settings for WebSphereThe 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:


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


Configuring Basic Agent Settings for WebSphere

Disabling Automatic Agent Naming for WebSphere 5.x and 6.0 for z/OS

To disable Automatic Agent Naming:


2. Set the value of the property, introscope.agent.agentAutoNamingEnabled, to false.


















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.

Additional Configuration OptionsThere 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/OSThere 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.



Configuring a Custom Service in WebSphere 5.0The 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. Open the WebSphere 5.0 Administrative Console.

2. Select the server you'd like to configure.

3. Click on Custom Services.

4. Click New to add a new Custom Service.

5. Check the Startup checkbox.

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


Optional WebSphere ConfigurationsSee the following sections for information on optional WebSphere configurations.



• Advanced WebSphere Performance Data, page 189


Further Installation Information

For more help with configuring Introscope for z/OS, please contact Wily Technical Support at 1-888-GET-WILY or [email protected].


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


• Configuring Basic Agent Settings for SunONE

Configuring Introscope With Sun ONE OverviewThere are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager:




Installing Introscope Agent on Sun ONETo 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.jar


http://wwws.sun.com/software/download/app_servers.html

http://wwws.sun.com/software/download/app_servers.html







• JVM AutoProbe







Choosing ProbeBuilder Configuration OptionThe following table details the ProbeBuilder options available for each Sun ONE Application Server version and JVM combination. To find the appropriate ProbeBuilder method:

1. Choose the row containing your Sun ONE Application Server version.






— Sun ONE Application Server version 7.0

— JVM AutoProbe



— Sun JVM

you would use the instructions in the section, JVM AutoProbe With Sun ONE 7.0 Using Sun JVM, page 130.



JVM AutoProbe With Sun ONE 7.0 Using Sun JVMThere are two steps required to configure and use JVM AutoProbe with Sun JVM:





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:










Sun ONE 7.0

JVM AutoProbe

Sun JVM AutoProbe With Sun ONE 7.0 Using Sun JVM, page 130


any Application Server AutoProbe With Sun ONE 7.0, page 131

Manual ProbeBuilder








Use the following instructions to run the AutoProbe connector:

1. In order to add Introscope information to startup scripts for Sun ONE 7.0, you must be logged in as Administrator or Root.

2. 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-to-Agent.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 ONEThe following sections describe how to configure your deployment to use Application Server AutoProbe.

Application Server AutoProbe With Sun ONE 7.0

The following instructions work with Sun ONE 7.0:



Note: The use of “...” in the .xml examples below denotes that there is additional information in the .xml code (not relevant to the example) that is not shown.





3. Add the full path of wily/Agent.jar to the “server-classpath” property of the java-config 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 ... bytecode-preprocessors="com.wily.introscope.api.sun.appserver.SunONEAutoProbe">

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


Configuring Basic Agent Settings for SunONE





1. Locate <Sun ONE home>/wily/toggles-full.pbd.






5. Repeat steps 2-4 for <Sun ONE home>/wily/toggles-typical.pbd

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















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:





3. Add the following line to the server.xml file:

<jvm-options>

-Dcom.wily.introscope.agentProfile=<Sun ONE home>/wily/IntroscopeAgent.profile

</jvm-options>



• Agent Name

• Process Name





For additional configuration options, see, Chapter 15, Optional Introscope Configurations.














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 OverviewThere are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager:




Installing Introscope Agent on Oracle 10gTo install the Introscope Agent on Oracle 10g:

1. Make sure that the Oracle 10g version 10.0.3 Application Server and any required updates have been installed.

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








• JVM AutoProbe







Choosing ProbeBuilder Configuration OptionThe following table details the ProbeBuilder options available for each Oracle Application Server 10g version and JVM combination. To find the appropriate ProbeBuilder method:

1. Choose the row containing your Oracle Application Server 10g version.






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





JVM AutoProbe With Oracle 10g Using Sun JVMThere are two steps required to configure and use JVM AutoProbe with Sun JVM:





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:












ProbeBuilder Configuration Option JVM

Use the Instructions In This Section

Oracle 10g 10.0.3

JVM AutoProbe

Sun JVM AutoProbe With Oracle 10g Using Sun JVM, page 138


any Application Server AutoProbe With Oracle Application Server 10g, page 139

Manual ProbeBuilder






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. Add the Agent.jar to the Application Server classpath.

2. Set the system property oracle.classpreprocessor.classes with the value of com.wily.introscope.api.oracle.OracleAutoProbe.

3. Set the system property oracle.j2ee.class.preprocessing with the value of true.

4. Restart the Oracle Application Server 10g.





1. Locate <Oracle 10g home>/wily/toggles-full.pbd.






5. Repeat steps 2-4 for <Oracle 10g home>/wily/toggles-typical.pbd

6. Proceed to the section, Configuring Basic Agent Settings for Oracle 10g, page 140 to configure the Agent profile.


Configuring Basic Agent Settings for Oracle 10g

Configuring Basic Agent Settings for Oracle 10gThe 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.















• Agent Name


Configuring Basic Agent Settings for Oracle 10g

• Process Name

















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




Configuring Introscope With SAP NetWeaver OverviewThere are three main steps required to install and configure the Introscope Agent to report information to the Enterprise Manager:




Installing Introscope AgentTo install the Introscope Agent:

1. Find the Agent installer file for your platform:

SAP Support Only


Windows IntroscopeAgentInstall6.0.1netweaver.windows.zip

Solaris

HP-UX

AIX

Linux

IntroscopeAgentInstall6.0.1netweaver.unix.tar


Windows IntroscopeAgentInstall6.0.1netweaver.windows.SAP.zip



2. Extract the installer file into the Java system’s working directory, commonly the Java Application’s installation directory.


• Agent.jar


• Several .pbd and .pbl files (ProbeBuilder Directives and List files).


3. If you want to use any custom .pbd files, add them to the /wily directory.


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




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.

Choosing ProbeBuilder Configuration OptionThe 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 Manual ProbeBuilder, use the instructions associated with that option.

Solaris

HP-UX

AIX

Linux

IntroscopeAgentInstall6.0.1netweaver.unix.SAP.tar





JVM AutoProbe Using Sun or IBM JVMThere are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM:



Note: You will have to re-create the AutoProbe connector if you update the JVM that is used for the SAP J2EE nodes, even if you just change the patch level, e.g., from 1.4.2_04 to 1.4.2_05! For this reason it is also important that you specify exactly the same JVM that is actually used by the SAP J2EE nodes.



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:



1. Change the working directory to wily/connectors.



/<jvm_path>/java -jar CreateAutoProbeConnector.jar -current


java -jar CreateAutoProbeConnector.jar -jvm<directory>

Application Server


SAP NetWeaver v 6.20 or 6.40

JVM AutoProbe

Sun JVM AutoProbe Using Sun or IBM JVM, page 144

IBM JVM AutoProbe Using Sun or IBM JVM, page 144

HP JVM AutoProbe Using HP HotSpot JVM, page 146

Manual ProbeBuilder







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-to-Agent.jar>

-Dcom.wily.introscope.agentProfile=<path-to-IntroscopeAgent.profile>

-Dcom.wily.introscope.agent.agentName=<yourAgentName>

For example:

-Xbootclasspath/p:C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\connectors\AutoProbeConnector.jar;C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\Agent.jar

-Dcom.wily.introscope.agentProfile=C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\IntroscopeAgent.profile

3. Restart SAP server.

Using NetWeaver 04/SAP J2EE 6.40

1. Run the SAP J2EE Configtool.

2. Select the server to modify.



3. In the Java Parameters field, add the following new java parameters:

-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>;<path-to-Agent.jar>

-Dcom.wily.introscope.agentProfile=<path-to-IntroscopeAgent.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. Click the disk button to save.

5. Repeat steps 2 - 4 for each server.

6. Restart SAP server.

7. To verify that Config tool changes were made, open the file:

<drive>:\usr\sap\ccms\P66\JC00\j2ee\cluster\instance.properties

8. Check for a line beginning with ID<server_id>.JavaParameters, and see if it contains the lines you entered in the step above.

9. Proceed to the section, Configuring Basic Agent Settings, page 147 to configure the Agent profile.

JVM AutoProbe Using HP HotSpot JVMThe following instructions work with HP HotSpot JVM.









Configuring Basic Agent Settings

Configuring Basic Agent SettingsThe 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.















• Agent Name

• Process Name

















introscope.agent.customProcessName

Enter name for process being monitored.


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




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




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:




Installing Introscope AgentTo 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





• Agent.jar




3. If you want to use any custom .pbd files, add them to the /wily directory.


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




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.

Choosing ProbeBuilder Configuration OptionThe following table details the ProbeBuilder options available when not using WebLogic, WebSphere, Sun ONE or Oracle 10g. To find the appropriate ProbeBuilder method:




• If using Manual ProbeBuilder, use the instructions associated with that option.





JVM AutoProbe Using Java 5.0 JVMThe 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 JVMThere are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM:





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:



1. Change the working directory to wily/connectors.



/<jvm_path>/java -jar CreateAutoProbeConnector.jar -current



JVM AutoProbe

any Java 5.0 JVM JVM AutoProbe Using Java 5.0 JVM, page 151

Sun JVM AutoProbe Using Sun or IBM JVM, page 151

IBM JVM AutoProbe Using Sun or IBM JVM, page 151

HP JVM AutoProbe Using HP HotSpot JVM, page 152

Manual ProbeBuilder




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






Configuring Basic Agent SettingsThe 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.



















• Agent Name

• Process Name

















introscope.agent.customProcessName

Enter name for process being monitored.


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


• Options for Running Introscope-enabled Code

• Switching Back to Your Non-Introscope-enabled Code

Configuring Java Applications Manually OverviewA 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 Introscope-enabling 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 WizardIf your machine has a windowing environment, use the instructions in this section to add Probes to your bytecode.



Configuring Java Applications With ProbeBuilder Wizard

• perform a full Introscope installation

• Introscope-enable the application code using ProbeBuilder Wizard


Installing IntroscopeA full Introscope install is required to install the ProbeBuilder Wizard and obtain the correct .pbd directory structure.

1. Install Introscope using the instructions found in Chapter 3, Installing Introscope Components.

2. Proceed to Installing Introscope Agent, page 156.

Installing Introscope Agent1. 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



— IntroscopeAgentInstall6.0.1default.zOS.tar

— IntroscopeAgentInstall6.0.1default.os400.zip



• Agent.jar

• ext/ProbeBuilder.jar



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


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 WizardTo add Probes to bytecode with ProbeBuilder Wizard:

1. If you have any custom .pbds to use, add them to the <Introscope home>/config/custompbd directory.

2. Locate the bytecode to modify.

3. Launch the ProbeBuilder Wizard located in the <Introscope home> directory.

4. Read the Welcome screen. Click Next.



5. Enter your bytecode directory or click Browse to pick one, then click Next.

To browse:

a. Double-click until you reach your directory.

b. Single-click the desired directory.

Note: You can also select .jar files or individual .class files.



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



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 didn’t 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 isn’t 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.



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


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:/<your-applicationpath>/lib/app.jar MainClass

to look like this:

java -classpath /<your-applicationpath>.isc/classes:/<your-applicationpath>.isc/lib/app.jar:/Introscope/lib/Agent.jar MainClass

3. Save the changes.

4. Start your application with the new startup script.

5. Proceed to the section, Configuring Basic Agent Settings, page 165.


If your machine does not have a windowing environment, use the instructions in this section to add Probes to your bytecode.



• Introscope-enable the application code using Command-line ProbeBuilder


Installing Introscope Agent1. 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



• Agent.jar

• ext/ProbeBuilder.jar



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


If you want to use any custom .pbd files, add them to the /wily directory.

Adding Probes to Bytecode Using Command-Line ProbeBuilderThe 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



-origdir /usr/myApp/classes -destdir /usr/myApp/classes.isc

–verbose

TABLE 4. Command Line ProbeBuilder Commands

Editing the ClasspathAfter 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.

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

java -classpath /<your-applicationpath>/lib/app.jar MainClass

Option Result

-help -h -? Displays a help screen

-directives (or -pbd) comma-separated-file-list

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

Specifies the original directory (including subdirectories)

Specifies the destination directory

-origjar file

-destjar file

Specifies the original archive, including .jar, .zip, .war, .rar and .ear archives

Specifies the destination archive

-origclass file

-destclass file

Specifies the original class

Specifies the destination class

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

-prompt Turns on an interactive text UI when problems arise.



to look like this:

java -classpath /<your-applicationpath>.isc/lib/app.jar:/<appserver home>/wily/Agent.jar MainClass


4. Start your application with the new startup script.

5. Proceed to the section, Configuring Basic Agent Settings, page 165.

Configuring Basic Agent SettingsThe 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:







Options for Running Introscope-enabled Code

• Agent Name

• Process Name



Options for Running Introscope-enabled CodeThere 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.













If an Agent is not named in the Agent profile, the default name is Unknown Agent.



Switching Back to Your Non-Introscope-enabled Code

If only part of the application’s 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. Non-Introscope-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 CodeIf 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.


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


Agent Naming Options

Agent Naming OptionsIntroscope 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 SequenceThe 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 doesn’t find a name using the first method, it will try the second method, and so on. If it doesn’t 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 PropertiesThe 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:



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. Open the IntroscopeAgent.profile.

2. 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 doesn’t exist, this property will be ignored.


Obtaining Agent Name Automatically From Application ServerAs part of Wily’s 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.



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.



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. In the Agent profile, make sure that introscope.agent.agentAutoNamingEnabled is set to true.

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


2. Under the Agent Name section, configure the desired delay in the introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds property.


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:


2. Under the Agent Name section, configure the desired interval in the introscope.agent.agentAutoRenamingIntervalInMinutes property.



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:


2. Locate the property, introscope.agent.disableLogFileAutoNaming, and enter a value of true.


Agent FailoverAgent Failover allows you to define a list of Enterprise Managers for the Agent to connect to if the Agent can’t 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 FailoverIn 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.


2. Locate the Enterprise Manager Locations and Names section.

The default Enterprise Manager set in the introscope.agent.enterprisemanager.tcp.host and


Agent Failover

introscope.agent.enterprisemanager.tcp.port settings is named DEFAULT, as seen here:

introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost

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.

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

introscope.agent.enterprisemanager.transport.tcp.host.MainEM=enterprise

introscope.agent.enterprisemanager.transport.tcp.port.MainEM=5001

introscope.agent.enterprisemanager.transport.tcp.host.BackupEM1=voyager

introscope.agent.enterprisemanager.transport.tcp.port.BackupEM1=5002

introscope.agent.enterprisemanager.transport.tcp.host.BackupEM2=space9

introscope.agent.enterprisemanager.transport.tcp.port.BackupEM2=5003

5. Locate the Enterprise Manager Connection Order section.

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


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. In the Agent profile, IntroscopeAgent.profile, locate the Enterprise Manager Failback Retry Interval section.

2. Uncomment the property,

introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds.

3. By default, the reconnect attempt interval is 120 seconds. Change if desired.

4. Save your changes.

5. Restart the application.

Agent Failover and Domain/User ConfigurationIf 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 OptionsIn 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 OptionsTo change to using a “typical” .pbl:


2. Locate the Directives Files section.


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


Other Optional Agent Settings

Enabling Cloned Agent Naming in the Agent Profile

To enable Cloned Agent naming:

1. Open the Agent profile, IntroscopeAgent.profile.

2. Set the following property:

introscope.agent.clonedAgent=true

3. Restart your managed application.

Running An Application Twice On One MachineYou 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 ConflictsThe 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 didn’t 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 Fully-Qualified 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.


Agent Logging Options

1. AutoProbe looks for any custom directives files in the directory that contains the IntroscopeAgent.profile file, and resolves filenames relative to this directory. For ease of use, you can place custom directives files (.pbds and/or .pbls) in the <appserver home>/wily directory.

2. In the file, wily/IntroscopeAgent.profile, modify the property, introscope.autoprobe.directivesFile, to include the names of any new directives files, separated by commas.

In the following example, a directives file named acme.pbd has been added:

introscope.autoprobe.directivesFile=default.pbl,acme.pbd

Note: Do not remove any ProbeBuilder list files (.pbl) already listed in the property.

For more information on creating and modifying ProbeBuilder Directive files, see the chapter, ProbeBuilder Directives, page 212.

Removing Line Numbers in BytecodeWhen 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 MetricsMetrics 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 OptionsThe 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.


http://jakarta.apache.org/log4j/docs/documentation.html


Agent Logging Options

Agent Log Files and Automatic Agent NamingIf 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:


2. In the property, log4j.logger.IntroscopeAgent, replace “INFO” with the following:


3. Save changes.

Redirecting Agent Output to a FileTo redirect Agent output to a file:


2. In the property, log4j.logger.IntroscopeAgent, replace “console” with “logfile.”


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.Log4JSeverityLevel,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:


Platform Monitors

Platform monitors are included with the Introscope Agent installers.

Enabling Platform MonitorsPlatform 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 MonitorsTo 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

Solaris

• <appserver home>/wily/ext/introscopeSolarisStats.jar• <appserver home>/wily/ext/introscopeSolarisStats.so

Windows • Server 2003• all Windows 2000

platforms• XP Professional

• <appserver home>\wily\ext\introscopeWindowsStats.jar• <appserver home>\wily\ext\introscopeWindowsStats.dll


http://techsupport.services.ibm.com/server/aix.fixsearch51

http://techsupport.services.ibm.com/server/aix.fixsearch51

ftp://ftp.software.ibm.com/aix/fixes/v4/os

JMX Filters For Obtaining Advanced Performance Data

Platform Configuration Troubleshooting OptionIn 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.


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


JMX Filters For Obtaining Advanced Performance DataIntroscope obtains application server internal Metric information through the application server’s 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

AIX• <appserver home>/wily/ext/introscopeAIXStats.jar• <appserver home>/wily/ext/introscopeAIXStats.so

RedHat Enterprise Linux

• <appserver home>/wily/ext/introscopeRedHatStats.jar• <appserver home>/wily/ext/introscopeRedHatStats.so



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



For example, if an MBean has the following attributes:

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

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:

and the user didn’t 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.

Domain name Key/Value Pairs Metric Names

WebLogic category=server, type=jdbc connections


WebLogic category=server, type=jdbc connections



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 FunctionalityFull 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. Shut down the managed application if it is running.

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



#introscope.agent.jmx.name.jsr77.enable=true#introscope.agent.jmx.name.primarykeys=J2EEServer,Application,j2eeType,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:


2. 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. Open the Agent profile, IntroscopeAgent.profile.

2. Make sure the property, introscope.agent.jmx.name.filter, is uncommented.

3. 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. Save changes.


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



WebLogic Diagnostic Framework Data

permission com.tivoli.jmx.MBeanServerPermission "*";

permission com.tivoli.jmx.MBeanPermission "*";

permission com.tivoli.jmx.AllMBeanPermission "*";

};

Viewing JMX Data In ExplorerAfter you’ve 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 DataThe 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 run-time performance of servers and applications and enables you to isolate and diagnose faults when they occur.


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 agents—which were developed by customers or third-party tools vendors—was 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 ConversionIntroscope 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:

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.


WebLogic Name=HTTPAccessLog, Type=WLDFDataAccessRuntime=Accessor,

WLDFRuntime=WLDFRuntime

BYTECOUNT


http://e-docs.bea.com/wls/docs90/wldf_configuring/index.html

http://e-docs.bea.com/wls/docs90/wldf_configuring/index.html

Advanced WebSphere Performance Data

Obtaining WLDF DataNo 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 DataIntroscope 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


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:



1. Open the WebSphere Administrative Console.

2. Select the server you'd like to configure.

3. Click the Services tab.



4. Select Performance Monitoring Settings in the list, then click Edit Properties.

5. Check the checkbox for Enable performance counter monitoring. The Counter Settings section will become available.

6. 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. Repeat to set monitoring levels for each desired Metric category.

8. Click OK.

9. 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 CollectionOnce you have turned on Performance Monitoring Settings in WebSphere, you must enable PMI data collection in Introscope, and enable the Metric categories you’d like to see reported.

To configure PMI collection, use the following steps:

1. Shut down your managed application.




3. Locate the property, introscope.agent.pmi.enable, under the WebSphere PMI Configurations heading, and enter a value of true.

4. 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 categories—connectionPool, threadPool, and servletSessions—are set to true by default.

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.



Viewing WebSphere Agent PMI DataAfter you’ve enabled PMI collections in Introscope, available PMI Metrics will be displayed in the following location in the Explorer tree:

<Domain>|<Host>|<Process>|<Agent>|WebSpherePMI

WebSphere 4.0 PMI Categories 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

Note: For data to be provided to the jvmpiModule, JVMPI must be turned on in WebSphere.

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


Enterprise Manager Database Recording

The following screenshot shows an example of WebSphere PMI Metrics in the Explorer tree.

Enterprise Manager Database RecordingThe 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.



Upgrading Database Schema Tables From Previous VersionsThe 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.



Setting Database Properties

To configure the Enterprise Manager to write to the database:



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

4. Remove the pound signs at the start of these four lines (URL, driver, user ID, password), so that these commented-out properties become active.

5. Save changes.

Database Type Sample Configurations

Oracle with Oracle driver

introscope.enterprisemanager.db.driver=oracle.jdbc.driver.OracleDriverintroscope.enterprisemanager.db.url=jdbc:oracle:thin:@myDB:PortID:SIDintroscope.enterprisemanager.db.username=myUserintroscope.enterprisemanager.db.password=myPassword

Sybase introscope.enterprisemanager.db.driver=com.sybase.jdbc2.jdbc.SybDriver

introscope.enterprisemanager.db.url=jdbc:sybase:Tds:myHost:PortID/database

introscope.enterprisemanager.db.username=myUserintroscope.enterprisemanager.db.password=myPassword

DB2 database on local machine

introscope.enterprisemanager.db.driver=COM.ibm.db2.jdbc.app.DB2Driver

introscope.enterprisemanager.db.url=jdbc:db2:databasename


DB2 database on remote machine

introscope.enterprisemanager.db.driver=COM.ibm.db2.jdbc.net.DB2Driver

introscope.enterprisemanager.db.url=jdbc:db2://myhost.mydomain.com:PortID/databasename


Microsoft Access

introscope.enterprisemanager.db.driver=sun.jdbc.odbc.JdbcOdbcDriver

introscope.enterprisemanager .db.url=jdbc:odbc:WILY01




Configuring the Enterprise Manager Classpath

6. Open the file, <Introscope home>/Introscope Enterprise Manager.lax

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

• 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. Save changes.

9. 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 DatabaseThe 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 Sun’s JDBC ODBC bridge.

• On Windows 2000, use Start > Settings > Control Panel > Administrative Tools > Data Sources (ODBC). Name the data source WILY01.

Database Type Sample Configurations

Oracle with Oracle driver C:\\oracle\\ora81\\jdbc\\lib\\classes12.zip

Sybase C:\\sybase\\jConnect-5_5\\classes\\jconn2.jar

DB2 /sw/opt/IBMdb2/V7.1/java12/db2java.zip


Optional Enterprise Manager Configurations


Running Enterprise Manager CommandsIn the Enterprise Manager terminal window, you can enter the following commands:

Configuring Scheduled Export of DataYour deployment may use a system to process data that can’t 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

Command Result

iscopedebugpolling [true | false] [delay in seconds]

Periodically reports debugging information to the log

iscopehelp Display help screen

iscopeshutdown Shuts down the Enterprise Manager



Configuring Scheduled Export of Data

To configure scheduled export of flat file data based on time:


2. Under the Flat File Recording heading, uncomment the property, introscope.enterprisemanager.flatfile.maxTimeInHours.

3. The default value is 24 (hours). Edit the value to the desired number of hours between flat file archiving.

4. Save changes to the file and restart the Enterprise Manager.

Note: If you change the system clock, or adjust the duration of archiving, you should manually archive in-progress flat files, to avoid out of order data, or data outside of the expected time range.

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 won’t 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.


Workstation Options

Defining Explicit Table QualifierBy 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 company’s DBA.

To define an explicit table qualifier:

1. Obtain the relevant explicit table qualifier from your DBA (syntax will vary according to which database is used).

2. If you are running the Enterprise Manager, shut it down.


4. Under the Database Settings section, set the introscope.enterprisemanager.db.tablequalifier property to the table qualifier provided by your DBA. The following are some examples:

• If using Oracle:

introscope.enterprisemanager.db.tablequalifier=wilyuser.

• If using DB2 or Sybase:

introscope.enterprisemanager.db.tablequalifier=wilydb.wilyuser.

Note: You must enter a trailing table qualifier separator after the specified table qualifier (in the above examples, the separator is a period). Contact your DBA for the proper separator.

5. Save changes.


Workstation Options

Workstation Logging OptionsThe 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.


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. Open the file, IntroscopeWorkstation.properties.

2. 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.Log4JSeverityLevel,logfile

3. If desired, change the name and/or location of the Workstation logfile in the property, log4j.appender.logfile.File.

4. Save changes.

Connecting Workstation to Enterprise Manager Behind FirewallThis 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 ProcessIn your build cycle, you will want to run the ProbeBuilder after compiling classes and before running qualification tests, as follows:


Miscellaneous Installation Options

1. Compile classes.

2. Run the ProbeBuilder.

3. 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 Introscope-enabled classes in the appropriate place.

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


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.


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


Introscope 6.0.1 Database Schema

Introscope 6.0.1 Database Schema

Note: The database schema has not changed for 6.0.1.


Database Tables

Database TablesThis 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 TableThe 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 TableThe 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 Default Actual Name

propertytable WT_PROPERTY

agenttable WT_AGENT

resourcetable WT_RESOURCE

metricnametable WT_METRIC_NAME

metrictable WT_METRIC

resourcemetrictable WT_RESOURCE_METRIC


Database Tables

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

recordtypetable WT_RECORD_TYPE

metadatatable WT_METADATA

tempquerytable_1 WT_TMP_Q_1





Logical Name Default Actual Name


Database Tables

Resource TableThe 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 TableThe 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 TableThe default name for the metadata table is WT_METADATA.

The metadata table has three columns:




The metadata table saves the Metric and Agent structure for Metrics whose values have been persisted to the value table.

Metric TableThe name for the Metric table is WT_METRIC.

The Metric table has 24 columns:




• RESOURCE_METRIC_ID (INTEGER)

• RECORD_TYPE_ID (INTEGER)

• PERIOD (INTEGER)

• INTENDED_END_TS (TIMESTAMP)

• ACTUAL_START_TS (TIMESTAMP)


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.


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.


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 TableThe 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 TableThe 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 TypesIntroscope 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 Fully-


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 TablesThis 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. one- and 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.

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


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 DataTo create database reports from Introscope data, you can use:

• SQL

• your database’s report tools

• third-party database reporting software

Once you create reports, you can use data and numerical analysis tools to analyze your data.

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


17 ProbeBuilder Directives

This chapter describes how to create and modify ProbeBuilder Directives.


• 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


Introduction to Directives

Introduction to DirectivesProbeBuilder 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 TrackedBy 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 GroupsIn 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.


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 TracedIntroscope 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 FilesThere 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 FilesIntroscope 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.


Modifying Default ProbeBuilder Directives

Full and Typical ProbeBuilder Directives SetsTracer 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.

Modifying Default ProbeBuilder DirectivesThe 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 FilesThe <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.



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

Name Definition

Default Full Setting

Default Typical Setting

CorbaTracing CORBA method invocations on on

EntityBeanTracing Entity EJB method invocations on on

SessionBeanTracing Session EJB method invocations on on

MessageDrivenBeanTracing Message-driven EJB method invocations

on on

J2eeConnectorTracing J2EE connector information on on

JavaMailTransportTracing Mail sending times on on

JDBCQueryTracing JDBC queries on on

JDBCUpdateTracing JDBC updates on on

JMSListenerTracing JMS message processing times on on

JMSConsumerTracing JMS message processing times on on

JMSPublisherTracing JMS message broadcast times on on

JMSSenderTracing JMS message broadcast times on on

JSPTracing JSP service responses on on

RMIClientTracing RMI client method invocations on on

RMIServerTracing RMI server method invocations on on

HTTPServletTracing

Note: If you are using Application Server AutoProbe, you will need to turn on the following Tracer group:

HTTPAppServerAutoProbeServletTracing

HTTP servlet service responses on on

StrutsTracing Execution times of actions in the Struts framework

on on

InstanceCounts

Note: Nothing will be traced until classes are identified with this Tracer group.

Counts number of instances of object type identified with Tracer group.

on on

FileSystemTracing File system bytes written and read

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

JAXMListenerTracing JAXM message sends on off

JNDITracing JNDI lookup times on off

JSPDBTagsTagLibraryTracing Jakarta DB Tags custom tag library for reading and writing from a SQL database

on off

JSPIOTagLibraryTracing Jakarta IO custom tag library for a variety of input and output tasks

on off

JTACommitTracing Commit times using JTA on off

EJBMethodLevelTracing EJB activity at method level on off

SocketTracing Network socket bandwidth on off

UDPTracing Network socket bandwidth on off

SystemOutTracing Captures standard out text off off

SystemErrorTracing Captures standard error text off off

ThreadTracing Number of active threads by class on off

XMLSAXTracing Time spent parsing XML document

on off

XSLTTracing XML transformation time on off

JSPTagLibraryTracing Processing time of custom JSP tags

off off

Name Definition

Default Full Setting

Default Typical Setting

Default stalled method Tracers

Stalled method tracing on on

DefaultConcurrentInvocationTracing

Concurrent invocation information

on off

Previous rate Metrics Metric information by rate (not interval count)

off



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.

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

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



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 GroupYou 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 application’s 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:


Creating Custom Tracers

mySessionEJB implements javax.ejb.SessionBeanmySessionEJBsubclass1 extends mySessionEJB

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

Creating Custom TracersCustom 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 KeywordsTo 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 won’t collect the desired information. This syntax is described in the next section.



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

The following table describes tracer names and what they trace.

TABLE 10. Tracer Names

Tracer component Definition

<class>

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.

<method>

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

<Tracer-name>

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

<metric-name>

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-nameThe Metric appears immediately inside the Agent.

• resource:metric-nameThe Metric appears inside one Resource (folder) below the Agent.

• resource|sub-resource|sub-sub-resource:metric-nameThe Metric appears more than one Resource (folder) level deep below the Agent, use pipe characters (|) to separate the Resources.

Tracer Name What It Traces

MethodTimer Average method execution time in milliseconds and reports it under <metric-name> in the Metrics tree

BlamedMethodTimer

Average method execution time in milliseconds and also collects information about runtime interactions between components



MethodCPUTimer

Average CPU time (in milliseconds) used during method execution and reports it under <metric-name> in the Metrics tree.

Note: This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0).

BlamedMethodCPUTimer

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

MethodRateTracer

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.

BlamedMethodRateTracer

Traces the same thing as MethodRateTracer and also collects information about runtime interactions between components

MethodTraceIncrementor and MethodTraceDecrementor

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.

BlamedMethodTraceIncrementor and MethodTraceDecrementor

Traces the same thing as MethodTraceIncrementor and MethodTraceDecrementor, with the addition of information about runtime interactions between components.

ConcurrentInvocationCounter

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



Custom Method Tracer ExamplesThe 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"



Custom Tracers in Blame TechnologyIntroscope’s 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:

SocketsInput BandwidthOutput Bandwidth

ServletsAverage Response TimeResponses Per SecondResponses Per IntervalMain Servlet

Average Response TimeResponses Per SecondCalled EJB

MyEJBAverage Method Invocation TimeMethod Invocations Per Interval

Called SocketsInput BandwidthOutput Bandwidth

EJBAverage Method Invocation TimeMethod Invocations Per IntervalMyEJB

Called JDBCAverage Response TimeResponses Per Second

JDBCAverage Query TimeQueries Per Second


Creating Advanced Custom Tracers

Creating Advanced Custom TracersThis 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

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

Parameter Runtime Substitution

{method} Name of the method being traced

{classname} Runtime class name of the class being traced

{packagename} Runtime package name of the class being traced

{packageandclassname} Runtime package and class name of the class being traced


http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html

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-class-shorthand-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:

OrderBookOrder

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.


Directive Keywords

SkipsCertain 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 TracersYou 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 InstancesThe 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 KeywordsThis 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 Value

<package-name> Period-separated, fully-qualified package name, such as java.lang.

<class-name> Period-separated, fully-qualified class name, such as java.lang.Object.


Directive Keywords

ProbeBuilder Skip KeywordsThe 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 KeywordsThe 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

<Tracer-name> Name of Tracer to use, one of the following in this list:

MethodTimerBlamedMethodTimerPerIntervalCounterMethodRateTracerBlamedMethodRateTracerMethodTraceIncrementorBlamedMethodTraceIncrementorMethodTraceDecrementorBlamedMethodTraceDecrementorConcurrentInvocationCounter

<method> Method name with an optional descriptor, such as Main or Main([Ljava/lang/String;)V).

<name> Valid Metric name or Resource category depending on the specific Tracer class, such as Resource|Sub-resource.

<Tracer-group> Name of Tracer group to use.


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.


The result is an aggregate Metric for all methods traced. To get detailed results for particular methods, use one of the TraceOneMethod keywords.


TraceOneMethodOfClass: <class-name> <method> <Tracer-name> <name>

Traces the specific method in the named class with the given Tracer class and Metric name.



TraceOneMethodWithParametersIfInherits: <class-name> <method> <Tracer-name> <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).


Directive Keywords

TraceOneMethodWithParametersOfClass: <class-name> <method> <Tracer-name> <name>




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>




TraceAllMethodsWithThresholdOfClass: <class-name> <Tracer-name> <name> <threshold>

Traces all methods in the named class with the given Tracer class and Metric name.


The result is an aggregate Metric for all methods traced. To get detailed results for particular methods, use one of the TraceOneMethod keywords.


Updating Introscope With Modified or New ProbeBuilder Directives Files


Keyword Syntax

The table below defines parameters used in the keyword syntax for these specific Directives.

TABLE 13. Threshold Directives Parameters

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


After you’ve 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.

Parameter Value

<class-name> Period-separated, fully-qualified class name, such as java.lang.Object.

<Tracer-name> Name of Tracer to use, one of the following in this list:

StalledMethodTracerThresholdMethodTimer

<method> Method name with an optional descriptor, such as Main or Main([Ljava/lang/String;)V).

<name> Valid Metric name or Resource category depending on the specific Tracer class, such as Resource|Sub-resource.

<threshold> Length of threshold in milliseconds



Adding New Custom ProbeBuilder Directives FilesAfter you’ve 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 IntroscopeAgent.profile file, and resolves filenames relative to this directory. For ease of use, you can place custom directives files (.pbds and/or .pbls) in the <appserver home>/wily directory.

2. In the file, wily/IntroscopeAgent.profile, modify the property, introscope.autoprobe.directivesFile, to include the names of any new directives files, separated by commas.

In the following example, a directives file named petstore.pbd has been added:

introscope.autoprobe.directivesFile=default.pbl,petstore.pbd

Note: Do not remove any ProbeBuilder list files (.pbl) already in the property.

Using ProbeBuilder Wizard

1. Place custom directives files in the <Introscope home>/config/custompbd directory.

2. The files you placed in the <Introscope home>/config/custompbd directory will appear in the Custom Directives screen during the ProbeBuilder Wizard process.

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

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

Applying Changes To ProbeBuilder Directives FilesWhether 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.




3. If they are not already running, start the Enterprise Manager and the Workstation.

Using the ProbeBuilder Wizard or the Command-Line ProbeBuilder

1. Make changes to Directives files.

2. Stop your managed application.

3. Run the ProbeBuilder (through the ProbeBuilder Wizard or Command-line ProbeBuilder).

4. Start the managed application.

5. If they are not already running, start the Enterprise Manager and the Workstation.


I

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.


• 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 FileAgent 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 InstallationIf 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).

ntroscope® 6.0.1 Installation & Configuration Guide (9/15/05)

Introscope Agent Settings File

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.


http://jakarta.apache.org/log4j/docs/documentation.html.


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


introscope.autoprobe.enable When option is set to false, this option turns off the automatic insertion of Probes into the application’s bytecode, it does not turn off the Agent or Agent reporting.

true

introscope.autoprobe.logfile Name and location of AutoProbe log file.

AutoProbe.log

introscope.autoprobe.directivesFile Specifies Directives files for AutoProbe. For more information, see Directives Files.

varies by installer

log4j.logger.IntroscopeAgent Amount of logging detail for the Introscope Agent log

INFO, console

log4j.appender.logfile.File Specifies the name and location of Introscope Agent logfile

IntroscopeAgent.log

introscope.agent.sockets.reportRateMetrics

Enables reporting of individual Socket's Input/Output Bandwidth rate Metrics

true



introscope.agent.extensions.directory 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

ext

introscope.agent.enterprisemanager.connectionorder

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.

DEFAULT


The host name of machine running the Enterprise Manager.

localhost


The port on the Enterprise Manager machine that listens for the Agent.

5001

introscope.agent.enterprisemanager.transport.tcp.socketReadTimeoutInSecond

Network timeout value in seconds when establishing Agent connection to Enterprise Manager

60

introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds

Number of seconds between attempts by Agent to reconnect to primary Enterprise Manager.

Commented out; 120

introscope.agent.customProcessName Name for process being monitored. Commented out; set to name of application server for application-server specific installers

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.

UnknownProcess; may vary by installer

introscope.agent.agentNameSystemPropertyKey

Specifies which Java system property will contain Agent name.

blank

introscope.agent.agentAutoNamingEnabled

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.

commented out and false in example IntroscopeAgent.profile; uncommented and true in Agent profile shipped with supported application servers

introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds

Specifies the amount of time in seconds the Agent waits for naming information before connecting to the Enterprise Manager.

120




introscope.agent.agentAutoRenamingIntervalInMinutes

Specifies the time interval in minutes during which the Agent will check to see if it has been renamed.

10

introscope.agent.disableLogFileAutoNaming

Specifies whether to disable automatic naming of Agent log files when using AutoNaming options.

false

introscope.agent.agentName 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

• For IntroscopeAgent.profile file included with default installer, commented out, and provided Agent name is Unknown Agent

• For IntroscopeAgen.profile included with AutoProbe installer, provided Agent name is same as application server (e.g. WebLogic Agent)

introscope.agent.thread.all.priority

Controls the priority of Agent threads. You can set this from 1 (low) to 10 (high).

Commented out; And, if unspecified, is level 5.

introscope.agent.pmi.enable Enables collection of data from WebSphere PMI.

false

introscope.agent.pmi.enable.threadPool Enables collection of PMI threadPool data.

true

introscope.agent.pmi.enable.servletSessions

Enables collection of PMI servletSessions data.

true

introscope.agent.pmi.enable.connectionPool

Enables collection of PMI connectionPool data.

true

introscope.agent.pmi.enable.bean Enables collection of PMI bean data.

false

introscope.agent.pmi.enable.transaction Enables collection of PMI transaction data.

false

introscope.agent.pmi.enable.webApp Enables collection of PMI webApp data.

false

introscope.agent.pmi.enable.jvmRuntime

Enables collection of PMI jvm Runtime data.

false




introscope.agent.pmi.enable.jvmpi Enables collection of PMI jvmpi data.

Note: For data to be provided to this module, JVMPI must be turned on in WebSphere.

false

introscope.agent.pmi.enable.system WebSphere 5.0.x only; enables collection of operating system-level data.

false

introscope.agent.pmi.enable.cache WebSphere 5.0.x only; enables collection of data about the effectiveness of WebSphere caching layers.

false

introscope.agent.pmi.enable.orbPerf WebSphere 5.0.x only; enables collection of performance statistics about the embedded Object Request Broker (ORB).

false

introscope.agent.pmi.enable.j2c WebSphere 5.0.x only; enables collection of J2EE connector data.

false

introscope.agent.pmi.enable.webServices

WebSphere 5.0.x only; enables collection of SOAP and web services data.

false

introscope.agent.pmi.enable.wlm WebSphere 5.0.x only, enables collection of Workload Management (WLM) data on load balancing and failover of WebSphere applications.

false

introscope.agent.jmx.enable Enables collection of JMX Metrics. false

introscope.agent.jmx.name.primarykeys User-defined order of MBean information, and simplifies name conversion.

Commented out in default IntroscopeAgent.profile file

For WebLogic: Type,Name

For WebSphere: J2EEServer,Application,j2eeType,JDBCProvider,name,mbeanIdentifier




introscope.agent.jmx.name.filter Filtered string(s), separated by commas

Note: IntroscopeAgent.profile file installed with Agent for WebLogic has the following filters defined:

Commented out in default IntroscopeAgent.profile file

For WebLogic: ActiveConnectionsCurrentCount,WaitingForConnectionCurrentCount,PendingRequestCurrentCount,ExecuteThreadCurrentIdleCount,OpenSessionsCurrentCount

For Websphere:

JSR77

introscope.agent.jmx.name.jsr77.enable Enables the retrieval of JMX Metrics for application servers which support the JSR77 specification.

Present only in WebSphere Agent Profile

Commented out; true

introscope.agent.jmx.ignore.attributes 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.

Present only in WebSphere Agent Profile

Commented out; server

introscope.agent.clonedAgent Unique name for cloned Agents Commented out; false

introscope.agent.platform.monitor.system

Name of operating system to load a platform monitor for.

Commented out; Solaris

introscope.agent.leakhunter.enable Enables LeakHunter functionality. true

introscope.agent.leakhunter.logfile.location

Location of LeakHunter.log file. Filename is relative to the application working directory.

Note: If property is commented out or left blank, no log file will be written.

LeakHunter.log

introscope.agent.leakhunter.logfile.append

Specifies whether to replace log file (value of false) or append existing log file (value of true) on application restart.

false

introscope.agent.leakhunter.leakSensitivity

Sensitivity of LeakHunter (higher sensitivity will report more collections as potential leaks). Must be integer value from 1-10.

5




introscope.agent.leakhunter.timeoutInMinutes

Period (in minutes) during which Introscope LeakHunter looks for new potential leaks. Must be non-negative integer. Value of zero means no timeout.

120 minutes

introscope.agent.leakhunter.collectAllocationStackTraces

Specifies whether to collect allocation stack trace information.

Note: Turning on this option has the potential to create higher system overhead, in CPU usage and memory.

false

introscope.agent.sqlagent.sql.useblame Specifies whether SQL Agent will generate blame Metric data.

Commented out; true

introscope.agent.transactiontracer.userid.method

Specifies the HttpServletRequest.getRemoteUser method to specify User IDs.

Commented out; HttpServletRequest.getRemoteUser


Specifies the HttpServletRequest.getHeader method to specify User IDs.

Commented out; HttpServletRequest.getHeader

introscope.agent.transactiontracer.userid.key

User-defined key string Commented out; supplied by user


Specifies the HttpServletRequest.getValue method to specify User IDs.

Commented out; HttpServletRequest.getValue

introscope.agent.transactiontracer.userid.key

User-defined key string Commented out; supplied by user

introscope.agent.transactiontracer.parameter.httprequest.headers

Specifies (in comma-separated list) httprequest header data to capture. Comma separated list.

Commented out; supplied by user

introscope.agent.transactiontracer.parameter.httprequest.parameters

Specifies (in comma-separated list) httprequest parameter data to capture.


introscope.agent.transactiontracer.parameter.httpsession.attributes

Specifies (in comma-separated list) http session attribute data to capture.




Introscope ProbeBuilder Settings File

Introscope ProbeBuilder Settings File

Introscope ProbeBuilder Wizard.lax FileTABLE 15. File: <Introscope home>/Introscope ProbeBuilder Wizard.lax

Introscope Enterprise Manager Settings FilesThe 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.


lax.nl.current.vm VM to use the next time the ProbeBuilder is started. Can be set to any installed JDK or JRE version 1.3.

Varies by operating system

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.

blank

lax.stdin.redirect 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.

blank

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.

blank



Introscope Enterprise Manager Settings Files

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

• Database’s 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.



TABLE 16. File: <Introscope home>/config/IntroscopeEnterpriseManager.properties

This Setting SpecifiesDefault Setting

introscope.enterprisemanager.agent.metrics.limit

Number of Metrics Agent will report before it is shut off.

Note: This property is not present in the EM properties file, it must be typed in manually.

50000

introscope.enterprisemanager.port.workstation.rmi

Enterprise Manager machine port that communicates with Workstations.

4500

introscope.enterprisemanager.port.workstation.rmi.secure

Additional Enterprise Manager machine port used for secure (SSL) connection with Workstations. Port defined in this property must also be opened in the firewall.

4550

introscope.enterprisemanager.workstation.disableSecureConnection

Disables the secure Workstation port.

Note: If this property is used, usernames and password information will be sent unencrypted over the network.

false

introscope.enterprisemanager.port.agentlistener

Enterprise Manager machine port that communicates with Agents

5001

log4j.logger.Manager Amount of logging detail for the Enterprise Manager log

INFO, console

log4j.appender.logfile.File Name and location of Enterprise Manager logfile

IntroscopeEnterpriseManager.log

introscope.enterprisemanager.autoUnmountDelayInMinutes

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.

60

introscope.enterprisemanager.smartstor.enable

Enables SmartStor data collection.

Note: SmartStor does not interfere with data being sent to Persistent Collections.

true

introscope.enterprisemanager.smartstor.directory

Specifies the directory SmartStor will use.

Note: Do not touch this.

data

introscope.enterprisemanager.smartstor.tier1.frequency

Specifies the frequency (in seconds) of data collection for the first data tier.

15

introscope.enterprisemanager.smartstor.tier1.age

Specifies the number of days after which data in first tier ages out of SmartStor.

1


Specifies the frequency (in seconds) of data collection for the second data tier.

60




Specifies the number of days after which data in second tier ages out of SmartStor.

7


Specifies the frequency (in seconds) of data collection for the third data tier.

300


Specifies the number of days after which data in third tier ages out of SmartStor.

7

introscope.enterprisemanager.transactionevents.storage.dir

Specifies where to store transaction event data.

traces

introscope.enterprisemanagter.transactionevents.storage.max.data.age

Specifies (in days) how long to store transaction event data.

14 days

introscope.enterprisemanager.db.driver

Name of your database driver Commented out

introscope.enterprisemanager.db.url Name of your database URL. Commented out

introscope.enterprisemanager.db.username

User name required for database access Commented out

introscope.enterprisemanager.db.password

Password required for database access Commented out

introscope.enterprisemanager.db.tablequalifier

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 tothe table name so be sure to include any separator required by the database.

Commented out

introscope.enterprisemanager.db.reconnect.intervalInSeconds

Number of seconds between reconnection attempts of an Enterprise Manager to a disconnected database. A value of zero means the Enterprise Manager won’t try to reconnect.

30

introscope.enterprisemanager.db.useBatchInserts

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.

Commented out

introscope.enterprisemanager.db.batchInsertSize

Controls the size (in row insertion count) of batch inserts, if they are enabled.

Commented out

introscope.enterprisemanager.db.queryTimeoutInSeconds

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.

Commented out




introscope.enterprisemanager.db.maximumTableCacheSize

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.

Commented out

introscope.enterprisemanager.db.queryConnections

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.

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.

<Introscope>/ flatfiles

introscope.enterprisemanager.flatfile.maxFileLength

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.

100

introscope.enterprisemanager.flatfile.maxTimeInHours

Time in hours after which the flat file is archived.

Commented out; 24

introscope.enterprisemanager.flatfile.disableCompression

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.

false

introscope.enterprisemanager.disableInteractiveMode

Disables interactive console (whether console accepts input).

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.

true




Introscope Enterprise Manager.lax FileTABLE 17. File: <Introscope home>/Introscope Enterprise Manager.lax

introscope.enterprisemanager.snmp.enable

Enables SNMP Agent (only relevant if you have installed SNMPServices.jar)

false

introscope.enterprisemanager.snmp.agent.port

Enterprise Manager port that communicates with the SNMP Agent

161

introscope.enterprisemanager.webview.disableLogin

Determines whether WebView can establish a connection with Enterprise Manager.

false

introscope.enterprisemanager.webview.password

Specifies password WebView users to connect to Enterprise Manager

WebView

The following four properties are duplicated for each authentication extension used.

introscope.enterprisemanager.authentication.providers

Specifies which authentication extensions are used during login

<Extension type>

introscope.enterprisemanager.authentication.extensionName.<ExtensionName>

Specifies extension name <Extension name>

introscope.enterprisemanager.authentication.controlflag.<ExtensionName>

Specifies control flag <control flag value>

introscope.enterprisemanager.authentication.configFile.<ExtensionName>

Specifies name and location of extension configuration file

<config-file information>


lax.class.path The Java classpath necessary to run this application. Can be appended with a JDBC driver and license.

lib/EnterpriseManager.jar:lib/SNMPAdapter.jar:lib/IntroscopeServices.jar:lax.jar

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.


lax.nl.java.option.additional

Initial minimum and maximum heap sizes -ms128m -mx512m


console



Introscope Workstation Settings Files

EMService.conf FileThe 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

Introscope Workstation Settings FilesThe files described in the following sections contain settings for the Introscope Workstation.

lax.stdin.redirect Standard Input.

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

console


console


wrapper.java.initmemory Wrapper’s initial memory size in megabytes

128

wrapper.java.maxmemory Wrapper’s maximum memory size in megabytes

512

wrapper.logfile Name and location of logfile ./logs/EMService.log

wrapper.logfile.maxsize Maximum logfile size 10 MB

wrapper.ntservice.name Name of the service IScopeEM

wrapper.ntservice.displayname Display name of the service Introscope Enterprise Manager



Introscope Workstation Settings Files

IntroscopeWorkstation.properties FileTABLE 19. File: <Introscope home>/config/IntroscopeWorkstation.properties

Introscope Workstation.lax FileTABLE 20. File: <Introscope home>/Introscope Workstation.lax


log4j.logger.Workstation Amount of logging detail for the Workstation log

INFO, console

log4j.appender.logfile.File Name and location of Workstation logfile

IntroscopeWorkstation.log


lax.command.line.args 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.

$CMD_LINE_ARGUMENTS$

lax.nl.current.vm 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.

-classic -ms64m -mx256m

The classic setting invokes Java 2 classic VM.


blank


blank


blank


Introscope WebView Settings Files

Introscope WebView Settings FilesThe files described in the following sections contain settings for Introscope WebView.

IntroscopeWebView.properties FileTABLE 21. File: <Introscope home>/config/IntroscopeWebView.properties

Introscope WebView.lax FileTABLE 22. File: <Introscope home>/Introscope WebView.lax


log4j.logger.WebView Amount of logging detail for the WebView log

INFO, console

log4j.appender.logfile.File Name and location of WebView logfile

logs/IntroscopeWebView.log

introscope.webview.tcp.port Port on which WebView listens for HTTP traffic

8080

introscope.webview.enterprisemanager.tcp.host

Enterprise Manager hostname to connect to

localhost

introscope.webview.enterprisemanager.tcp.port

Enterprise Manager port to connect to

4500

introscope.explorer.refresh.interval

Frequency (in seconds) at which the Explorer tree refreshes.

15

introscope.webview.password Password WebView uses to connect to the Enterprise Manager

WebViewNote: DO NOT CHANGE.


lax.class.path The Java classpath necessary to run this application.

lib/WebViewServices.jar;lib/Workstation.jar;lib/WebViewAPI.jar;lib/WebViewServer.jar;lib/IntroscopeServices.jar;lax.jar

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.

$CMD_LINE_ARGUMENTS$

lax.nl.current.vm 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.

-classic -ms64m -mx256m

The classic setting invokes Java 2 classic VM.


Database Settings Files

Database Settings FilesThe file described in the following section contains settings related to database usage with Introscope.

CustomDBRecordTypes.properties FileThe 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 Agent’s name is matched against Agent regular expressions, until a match is found. Then Metric regular expressions are checked for that Agent.

The Metric’s 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 Metric’s 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.


blank


blank


blank



Extensions Settings Files

TABLE 23. File: <Introscope home>/config/customDBRecordTypes.properties


LocalAuthenticationExtension.propertiesThis file contains the configuration properties for the local authentication extension.

TABLE 24. File: <Introscope home>/config/LocalAuthenticationExtension.properties

LDAPAuthenticationExtension.propertiesThis file contains the configuration properties for the LDAP authentication extension.

TABLE 25. File: <Introscope home>/config/LDAPAuthenticationExtension.properties


introscope.enterprisemanager.database.recordtypes.agentexpression.#

Identifies an Agent Regular Expression

introscope.enterprisemanager.database.recordtypes.metricexpression.#

Identifies Metric Regular Expression

introscope.enterprisemanager.database.recordtypes.typestring.#

Datatype name assigned to a Metric that matches both regular expressions above

Record Type


authentication.extension.local.userFile

Pathname of the username/password file

config/users.xml


authentication.extension.ldap.url= URL for the remote LDAP server

Note: If you are using SSL, the SSL LDAP port should be part of the server URL.

ldap://host:port

authentication.extension.ldap.useSSL

Whether to use SSL to connect to remote LDAP server

false

authentication.extension.ldap.bindName

Name used to bind to LDAP server. If blank, anonymous bind is used.

IntroscopeLDAPUser



authentication.extension.ldap.bindPassword

Password used to bind to LDAP server. If anonymous bind is used, this property is ignored.

password123

authentication.extension.ldap.bindAuthentication

Authentication type to use when binding.

Options are: none, simple, CRAM-MD5.

simple

authentication.extension.ldap.user.nameSuffix

Suffix to append to Introscope user name for use with LDAP queries.

@dev.com

authentication.extension.ldap.user.baseDN

Base distinguished name (DN) for all user object queries

cn=Users, dc=dev, dc=com

authentication.extension.ldap.user.scopeDepth

Search depth when querying for a user object

subtree

authentication.extension.ldap.user.usernameAttribute

Name of LDAP attribute that will match an Introscope username

userPrincipalName

authentication.extension.ldap.user.userObjectQuery

LDAP search filter used to query a user object. The token “%u” will be filled in with the Introscope username before the query executes.

(&(userPrincipalName=%u)(objectclass=user))

authentication.extension.ldap.serverCertificate

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.

blank



In

BLicenses

Apache Software License, Version 1.1Copyright (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. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

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

3. 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 [email protected].

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.

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.

troscope® 6.0.1 Installation & Configuration Guide (9/15/05)

http://www.apache.org



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 DistributionCopyright (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. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.

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

3. 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 [email protected].

4. 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 ([email protected]).

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 <[email protected]> and Jason Hunter <[email protected]>. For more information on the JDOM Project, please see http://www.jdom.org.

License for Tanuki Software DistributionCopyright (c) 1999, 2003 TanukiSoftware.org


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.


Introsc

Index

AAgent

cloned Agent naming 176configuration

other settings 177verbose mode 179

installingon Oracle 10g 136on other application servers 142, 149on Sun ONE 128on WebLogic 95on WebSphere 106on WebSphere on OS/390 117

naming options 169automatic

automatically from application server170

using Java system property 169using system property key 170

redirecting output to a file 179resolving Agent naming conflicts 177running Agent twice on one machine 177verbose mode 179

Agent FailoverDomains and User issues with 93

Agent failoverDomain/User configuration 175

AIXplatform monitors 181

audience 15Authentication

LDAP 84local 81

AutoProbeApplication Server AutoProbe 96

with Oracle 10g 139

with Sun ONE 131with WebLogic 101with WebSphere 111with WebSphere on OS/390 121

definition 22directives

using custom 177JVM AutoProbe

with Oracle 10g 138with other application servers 144, 151with Sun ONE 130with WebLogic 99with WebSphere 108with WebSphere on OS/390 119

properties file locationon WebLogic 102

Bbatch job

running Enterprise Manager as in OS/390 67Blame Technology 23

blamed tracers 221, 222

CCommand-Line ProbeBuilder

commands 164configuring

other Java applications 162Console 24Console mode

49custom Tracers. See ProbeBuilder Direc-tives

ope® 6.0.1 Installation & Configuration Guide (9/15/05)

Ddatabase

5.0 database schema 203configuring Enterprise Manager for 193creating reports 211Enterprise Manager properties 195explicit table qualifier 199querying tables 210record types 209reporting 202–211sample Microsoft Access database 196scripts

creation 194tables

Agent table 205Index table 204Metadata table 206Metric name table 206Metric table 206Property table 205Resource table 206Version table 204

upgrading schema tables 194Domain 23Domains

Agent mapping 78changing 79

associating Management Modules with 78attributes and syntax 77creating 77, 78creation rules 77deleting 79Managing Domains 76merging 80moving between Introscope installations 80

Domains and Usersoverview 76with Agent Failover 93

EElement 26Enterprise Manager 22

configuringdatabase 193new database connection 194

installing and configuringon OS/390

running as a batch job in OS/390 67running as Windows Service 65

deregistering 66running from command line

commands 197starting 58

OS/390 59UNIX 58Windows 58

stopping 59

Ffirewall 32

connecting components behind 200flat file properties 243Fujitsu Interstage

using Introscope 5.0 with 94

GGUI mode

36GUI installation sequence 37launching GUI mode installer 37

IInstallation

in Console mode 49in GUI mode 36

GUI installation sequence 37launching GUI mode installer 37

in Silent mode 51launching silent mode installer 52

miscellaneous options 201planning where to install 27preparing for 27, 32process 33


system requirements 29Interstage

using Introscope with 94Introscope

components defined 21JVMs bundled with 31supported JVM versions 31terms defined 21

Introscope.EnterpriseManager.propertiesdatabase properties 195

Introscope-enabled code 21options 166switching back to original code 167

JJava2 Security Policy 201

on WebSphere 5.0 110, 112JMX support 182–187

configuring 185enabling 185JMX filters 184, 186Metric name conversion 183

default method 184primary keys method 183

primary keys 183primary keys, defining 186viewing JMX data in Explorer 187

Llax files

Introscope Enterprise Manager.lax 247Introscope ProbeBuilder Wizard.lax 242Introscope WebView.lax 250Introscope Workstation.lax 249

LicenseApache Software Version 1.1 254JDOM Binary Distribution 255

license fileinstalling 58

Log4JAgent settings 179

Enterprise Manager settings 63, 64Workstation settings 199, 200

MManaged Java Application 21Management Module 26Management Modules

moving 198message URL http

//wrapper.tanukisoftware.org/doc/english/properties.html 65

Metric 23Metric Grouping 23

OOracle Application Server 10g

configuring with Introscope 136–141basic Agent settings 140installing Agent on 136ProbeBuilder configuration options 137

organization of book 15OS/390

base structure for Java 67customizing UNIX shell script 71DASD 70DB2 68DB2 considerations on 74Enterprise Manager OS/390 files and parti-

tioned dataset 71installing Enterprise Manager on 70JDBC 69PROC

customizing 72executing 72

running Enterprise Manager as a batch job in67

running Enterprise Manager as started task72

running Enterprise Manager on 72security and authorization 68software prerequisites for Java 67


starting Enterprise Manager 59starting Enterprise Manager automatically

on 74OS/400

installing Introscope Agent with AutoProbeWebLogic 95

Pplatform monitor 180

troubleshooting 182ports

specifying 242ProbeBuilder 22

Command-line ProbeBuilder 162configuring java applications manually with

155customizing Directives 212integrating into build process 200list files 214log 201ProbeBuilder Wizard 155

ProbeBuilder Directives 212applying changes to 232components tracked 213components tracked in 213custom Tracers 220

combining 227creating 220examples template 223

filescustom 161, 214

updating Introscope with 232system 160, 214

keywords 227action 228

IdentifyClassAs 228IdentifyCorbaAs 228IdentifyInheritedAs 228InstrumentPoint 228TraceAllMethodsIfInherits 229TraceAllMethodsOfClass 229TraceOneMethodOfClass 229TraceOneMethodWithParameterIfIn-

herits 229

TraceOneMethodWithParametersOf-Class 230

TurnOn 230skip 228

SkipClass 228SkipPackage 228

Threshold action 230parameters 231TraceAllMethodsWithThresholdOf-

Class 230TraceOneMethodWithThresholdOf-

Class 230Threshold Tracers

OverThresholdPerIntervalCounter231

StalledMethodTracer 231UnderThresholdPerIntervalCounter

231modifying 215

EJB subclass tracing 219Tracer groups

adding classes to 219turning on or off 218

only defined methods traced 214parameters 227single-Metric Tracers 213Tracer groups

adding classes to 219default 216turning on or off 213, 218, 219

updating probes 231ProbeBuilder Wizard 22, 155–161

adding Probes to bytecode with 157Probes 21properties

database 243Directives files to use 235files 234flat file 243introscope.autoprobe.DirectivesFile 235

properties filesCustomDBRecordTypes.properties 251Introscope Enterprise Manager.lax 247Introscope ProbeBuilder Wizard.lax 242Introscope WebView.lax 250Introscope Workstation.lax 249


IntroscopeEnterpriseManager.properties242

IntroscopeWebView.properties 250IntroscopeWorkstation.properties 249

RRedHat

platform monitor 180redirect output

Agent 179Enterprise Manager in 64Workstation 200

Resource 23

SSilent mode 51

launching silent mode installer 52SmartStor 60

and Persistent Collections 60, 193requirements 61

SNMP Collections 243Sun ONE Application Server


SuperDomain 23system requirements

Introscope 29JVM 31memory 31

TTracer groups

adding classes to 219Tracers

advanced customcreating 225

advanced single-Metric 225

Blame Technology and 224BlamedMethodRateTracer 222BlamedMethodTimer 221BlamedMethodTraceDecrementor 222BlamedMethodTraceIncrementor 222ConcurrentInvocationCounter 222default Tracer Groups 215example template 223full and typical tracing options 175MethodCPUTimer 222MethodRateTracer 222MethodTimer 221MethodTraceDecrementor 222MethodTraceIncrementor 222PerIntervalCounter 222toggle files 215

Transaction Event Databaseconfiguration during GUI installation 41settings 62, 243

type conventions 17

Uuninstalling Introscope 54UNIX

Enterprise Managerrunning in nohup mode 64

starting Enterprise Manager 58User

modifiers and syntax 82User permissions

creation rules 88Users

access privilegesserver permissions

creation rules 91defining 81defining a user 82permissions 88

Domain accessdefining permissions 90

server accessdefining permissions 92modifiers and syntax 91


Vverbose mode

running Agent in 179running Enterprise Manager in 63running Workstation in 199

WWebLogic Server


JMX data 182WebSphere 6.0 109Websphere 6.0 111WebSphere Application Server

configuring custom service for 116, 127configuring with Introscope 106–116

basic Agent settings 113installing Agent on 106ProbeBuilder configuration options 107

PMI data 189–193enabling and defining 191viewing 192

WebSphere 4.0disabling automatic Agent naming for 115

WebSphere Application Server on OS/390

configuring as batch job 67–75configuring with Introscope ??–127

installing Agent on 117ProbeBuilder configuration options 118

Workstation 24connecting to Enterprise Manager behind

firewall 200installing on Windows 94


installation and configuration guide - the content...

Documents