Introscope 4.2 Installation Guide

Transcription

Installation and
Configuration Guide
Version 6 Release 6.0.1
Wily Technology, Inc.
8000 Marina Boulevard, Suite 700
Brisbane, CA 94005
1 888 GET WILY < US Toll Free >
415 562 2000 < phone >
415 562 2100 < fax >
www.wilytech.com
Introscope 6.0.1 Installation and Configuration Guide
Copyright © 2005, Wily Technology™, Inc. All Rights Reserved.
The following trademarked names are properties of the named companies:
Introscope® is a registered trademark of Wily Technology™, Inc.
Java, Sun MicroSystems Solaris, and Sun ONE are registered trademarks of Sun MicroSystems, Inc.
AIX, AS/400, z/OS, iSeries and WebSphere are registered trademarks of International Business Machines Corporation.
UNIX is a registered trademark of The Open Group.
Windows, Windows 2000 Professional/Server/Advanced Server/Datacenter Server, Windows
Server 2003, Windows XP and Excel are registered trademarks of Microsoft Corporation.
HP-UX and HP HotSpot JVM are registered trademarks of Hewlett-Packard Company.
Linux is a registered trademark of Linus Torvalds.
Interstage is a registered trademark of Fujitsu Limited.
WebLogic is a registered trademark of BEA Systems, Inc.
Oracle® and Oracle® Application Server 10g™ are registered trademarks of Oracle Corporation.
All other names used in this document are the property of their respective holders.
Contents - Chapters
Contents - Detailed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 1 Introscope Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 2 Preparing For Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 3 Installing Introscope Components . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 4 Configuring and Running the Introscope Enterprise Manager. . . . 57
Chapter 5 Configuring Introscope Security and Permissions . . . . . . . . . . . . . 76
Chapter 6 Configuring Java Applications With Introscope . . . . . . . . . . . . . . . 94
Chapter 7 Configuring WebLogic Server With Introscope . . . . . . . . . . . . . . . 95
Chapter 8 Configuring WebSphere Application Server With Introscope . . . 106
Chapter 9 Configuring WebSphere on z/OS With Introscope . . . . . . . . . . . 117
Chapter 10 Configuring Sun ONE Application Server With Introscope . . . . 128
Chapter 11 Configuring Oracle Application Server 10g With Introscope . . . 136
Chapter 12 Configuring SAP NetWeaver With Introscope . . . . . . . . . . . . . . 142
Chapter 13 Configuring Other Application Servers or Applications
With Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Chapter 14 Configuring the Java Applications Manually With ProbeBuilder 155
Chapter 15 Optional Introscope Configurations. . . . . . . . . . . . . . . . . . . . . . 168
Chapter 16 Database Configuration and Reporting . . . . . . . . . . . . . . . . . . . 202
Chapter 17 ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Appendix A Introscope Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Appendix B Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Introscope® 6.0.1 Installation & Configuration Guide (9/15/05)
Page 3
Contents - Detailed
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Introscope 6.0.1 Installation and Configuration Guide Audience
Introscope 6.0.1 User Guides . . . . . . . . . . . . . .
Introscope 6.0.1 Upgrade Guide . . . . . . . . . .
Introscope 6.0.1 Installation and Configuration
Introscope 6.0.1 Workstation Guide . . . . . . .
Introscope 6.0.1 WebView Guide . . . . . . . . .
. . . . . . . . . . . 15
. . . . . . . . . . . . . . . . . . . . . . . . . 15
. . . . . . . . . . . . . . . . . . . . . . . . . 15
Guide (this guide) . . . . . . . . . . . 15
. . . . . . . . . . . . . . . . . . . . . . . . . 15
. . . . . . . . . . . . . . . . . . . . . . . . . 16
Organization of the Introscope 6.0.1 Installation Guide . . . . . . . . . . . . . . . . . . 16
Need Help With Installation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 1 Introscope Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
How Introscope Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Introscope Components and Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Managed Java Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
ProbeBuilder Wizard and Command Line ProbeBuilder . . . . . . . . . . . . . . . . 22
ProbeBuilder and Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Metric Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Blame Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
SuperDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Introscope Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Dashboard Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Management Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 2 Preparing For Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Preparing To Install Introscope . . . . . . . . . . . . . . . . . .
Step 1: Plan Where To Install Introscope Components
Step 2: Choose Installation Method . . . . . . . . . . . . . .
Install Notes . . . . . . . . . . . . . . . . . . . . . . . . . .
Introscope Installer Modes . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 27
. . . . . . . . . . . . . . . . . . . 27
. . . . . . . . . . . . . . . . . . . 27
. . . . . . . . . . . . . . . . . . . 28
. . . . . . . . . . . . . . . . . . . 28
Page 4
Supported Modes By Platform
Step 3: Check System Requirements
Supported Platforms . . . . . . .
Space Requirements . . . . . . .
Memory Requirements . . . . . .
Bundled JVMs . . . . . . . . . . . .
JVM Used by Installer . . . . . .
Step 4: Review Installation Notes . .
..
.
..
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 29
. 29
. 29
. 30
. 31
. 31
. 32
. 32
Information to Collect Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Enterprise Manager Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Reviewing Installation and Configuration Process . . . . . . . . . . . . . . . . . . . . . . . 33
Starting the Installation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Chapter 3 Installing Introscope Components . . . . . . . . . . . . . . . . . . . . . . . . . 35
Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Installing Introscope In GUI Mode . . . . . . . . . .
Installation in GUI mode . . . . . . . . . . . . . . .
Launching GUI Mode Installer . . . . . . . .
GUI Installation Sequence . . . . . . . . . .
Next Steps - Installing Introscope Agent
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . . 36
. . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . 37
. . . . . . . . . . . . . . . . . . . . 49
Installing Introscope In Console Mode . . . . . . . .
Launching Console Mode Installer . . . . . . . . . .
Using z/OS . . . . . . . . . . . . . . . . . . . . . .
Using Any Other Platform . . . . . . . . . . .
Next Steps - Installing Introscope Agent .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 49
. . . . . . . . . . . . . . . . . . . 50
. . . . . . . . . . . . . . . . . . . 50
. . . . . . . . . . . . . . . . . . . 50
. . . . . . . . . . . . . . . . . . . 51
Installing Introscope In Silent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Response File Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Using an Automatically-generated Response File . . . . . . . . . . . . . . . . . . . 51
Using a Manually-Configured Sample Response File . . . . . . . . . . . . . . . . . 51
Launching Silent Mode Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using Any Other Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Next Steps - Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . 53
Uninstalling Introscope . . . . . . . . . . . . . . . . . .
Uninstall Modes . . . . . . . . . . . . . . . . . . . . .
Forcing an Uninstall Mode . . . . . . . . . .
Running Uninstaller . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 54
. . . . . . . . . . . . . . . . . . . 54
. . . . . . . . . . . . . . . . . . . 54
. . . . . . . . . . . . . . . . . . . 54
Chapter 4 Configuring and Running the Introscope Enterprise Manager. . . . 57
Installing License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Starting Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Windows (Enterprise Manager not configured as a Windows Service) . . . . . 58
OS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Writing Status Information to Logfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Running the Enterprise Manager as a Java Program . . . . . . . . . . . . . . . . . . . . . 59
Stopping Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Page 5
Enterprise Manager Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
SmartStorTM Data Storage . . . . . . . . . . . . . . . . . . . .
Configuring SmartStor . . . . . . . . . . . . . . . . . . . . .
Enabling SmartStor . . . . . . . . . . . . . . . . . . .
Determining SmartStor System Requirements
Specifying SmartStor Data Tier Values . . . . .
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . . 60
. . . . . . . . . . . . . . . . . . . . 60
. . . . . . . . . . . . . . . . . . . . 60
. . . . . . . . . . . . . . . . . . . . 61
. . . . . . . . . . . . . . . . . . . . 61
Transaction Event Database Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Configuring Transaction Event Database Settings . . . . . . . . . . . . . . . . . . . . . . . 62
Enterprise Manager Metric Throttle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Configuring Enterprise Manager Metric Throttle . . . . . . . . . . . . . . . . . . . . . . . . 63
Enterprise Manager Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Running Enterprise Manager in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . . 63
Redirecting Enterprise Manager Output to a File . . . . . . . . . . . . . . . . . . . . . . . . 64
Running Enterprise Manager in nohup Mode on UNIX . . . . . . . . . . . . . . . . . . . . 64
Additional Enterprise Manager Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Configuring Enterprise Manager To Run As A Windows Service . . . . . . . . . . . . . 65
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Configure and Register Enterprise Manager as a Windows Service . . . . . . . . . . . 65
Register Enterprise Manager as a Service . . . . . . . . . . . . . . . . . . . . . . . . 65
Deregister Enterprise Manager(s) Running as a Windows Service . . . . . . . . . . . . 66
Changing Windows Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Running the Enterprise Manager as a Windows Service . . . . . . . . . . . . . . . . . . . 67
Connecting to a Database Configured After Enterprise Manager
Service Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Configuring Enterprise Manager To Run As a z/OS Batch Job . . . . . . . . . . . . . . 67
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Overview of Installation Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Copying and Customizing Introscope Enterprise Manager Files . . . . . . . . . . 70
Customizing the Introscope Enterprise Manager Properties File . . . . . . . . . 70
Customizing runem.sh – the UNIX Shell Script . . . . . . . . . . . . . . . . . . . . . 71
Copying Introscope Enterprise Manager z/OS files to a z/OS
Partitioned Dataset (PDS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Customizing the z/OS PROC That Invokes BPXBATCH . . . . . . . . . . . . . . . . 72
Running the Introscope Enterprise Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Executing the z/OS PROC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Starting the Introscope Enterprise Manager automatically . . . . . . . . . . . . . 74
DB2 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Database Implementation Considerations . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 5 Configuring Introscope Security and Permissions . . . . . . . . . . . . . 76
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Configuring and Managing Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Domain Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Page 6
SuperDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-defined Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Domain Attributes and Syntax . . . . . . . . . . . . . . . . . . . . . . .
Domain Creation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Domain and Mapping Agents . . . . . . . . . . . . . . . .
Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Associating Management Modules With Domains . . . . . . . . . . . . . .
Adding Sample Management Module to Newly Created Domains
Changing the Domain Mapping of an Agent . . . . . . . . . . . . . . . . . .
Deleting a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Merging Two Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Moving a Domain From One Introscope Installation to Another . . . . .
Moving a Domain Between Installations To Clone the Domains .
Moving a Domain Between Non-cloned Installations . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 76
. 77
. 77
. 77
. 77
. 78
. 78
. 78
. 79
. 79
. 79
. 80
. 80
. 80
. 80
Configuring User Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Local User Authentication Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Configuring Local Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Configuring Enterprise Manager to Use Local Authentication . . . . . . . . . . . 82
Configuring Location or Name of Local Authentication File . . . . . . . . . . . . . 82
Defining a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
User Configuration Modifiers and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 82
Defining a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Generating Encoded Passwords (Optional) . . . . . . . . . . . . . . . . . . . . . . . . 83
Default User Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Configuring Enterprise Manager to Use LDAP Authentication . . . . . . . . . . . 85
Configuring LDAP Authentication Extension . . . . . . . . . . . . . . . . . . . . . . . 85
LDAP Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Defining User Permissions . . . . . . . . . . . . . . . . . .
Permissions Rules . . . . . . . . . . . . . . . . . .
Domain Permissions . . . . . . . . . . . . . . . . . . . .
Domain Access Rules . . . . . . . . . . . . . . .
Domain Permissions Defined . . . . . . . . . .
Defining Domain Permissions . . . . . . . . . .
Domain Permissions and the Explorer Tree
Server Permissions . . . . . . . . . . . . . . . . . . . . .
Server Permissions Rules . . . . . . . . . . . .
Server Permissions Defined . . . . . . . . . . .
Defining Server Permissions . . . . . . . . . . .
Agent Failover and Domain/User Configuration . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . . 88
. . . . . . . . . . . . . . . . . . . . 88
. . . . . . . . . . . . . . . . . . . . 88
. . . . . . . . . . . . . . . . . . . . 88
. . . . . . . . . . . . . . . . . . . . 89
. . . . . . . . . . . . . . . . . . . . 90
. . . . . . . . . . . . . . . . . . . . 91
. . . . . . . . . . . . . . . . . . . . 91
. . . . . . . . . . . . . . . . . . . . 91
. . . . . . . . . . . . . . . . . . . . 92
. . . . . . . . . . . . . . . . . . . . 92
. . . . . . . . . . . . . . . . . . . . 93
Chapter 6 Configuring Java Applications With Introscope . . . . . . . . . . . . . . . 94
Chapter 7 Configuring WebLogic Server With Introscope . . . . . . . . . . . . . . . 95
Configuring Introscope With WebLogic Overview . . . . . . . . . . . . . . . . . . . . . . . 95
Installing Introscope Agent With WebLogic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Page 7
JVM AutoProbe Using Java 5.0 JVM . . . . . . . . . . . . . . . . . . . . . . . . . . .
JVM AutoProbe With WebLogic Using Sun or IBM JVM . . . . . . . . . . . . . .
Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . .
Running AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . .
JVM AutoProbe With WebLogic Using HP HotSpot JVM . . . . . . . . . . . . . .
JVM AutoProbe With WebLogic Using WebLogic JRockit . . . . . . . . . . . . .
Application Server AutoProbe With WebLogic . . . . . . . . . . . . . . . . . . . .
Application Server AutoProbe With WebLogic 8.1 . . . . . . . . . . . . .
Application Server AutoProbe With WebLogic 6.1 SP3 . . . . . . . . . .
Configuring HTTP Servlet Tracing For Application Server AutoProbe
Configuring Basic Agent Settings for WebLogic
Agent Profile Location . . . . . . . . . . . . . . . . .
Defining Agent Profile Location . . . . . . .
Configuring Introscope Agent . . . . . . . . . . . .
Agent Naming . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . 99
. . 99
. . 99
. . 99
. 100
. 100
. 101
. 101
. 101
. 101
. 102
. 102
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 102
. . . . . . . . . . . . . . . . . . . 102
. . . . . . . . . . . . . . . . . . . 103
. . . . . . . . . . . . . . . . . . . 103
. . . . . . . . . . . . . . . . . . . 103
Additional Configuration Options . . . . . . . . . . . . . .
Creating a WebLogic Startup Class . . . . . . . . . . .
Configuring a Startup Class In WebLogic 8.1
Optional WebLogic Configurations . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . 104
. . . . . . . . . . . . . . . . . . 105
. . . . . . . . . . . . . . . . . . 105
. . . . . . . . . . . . . . . . . . 105
Chapter 8 Configuring WebSphere Application Server With Introscope . . . 106
Configuring Introscope With WebSphere Overview . . . . . . . . . . . . . . . . . . . . . 106
Installing Introscope Agent on WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
ProbeBuilder Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . 107
JVM AutoProbe With WebSphere Using Sun or IBM JVM . . . . . . . . . . . . . . . . . . 108
Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
JVM AutoProbe With WebSphere Using HP HotSpot JVM . . . . . . . . . . . . . . . . . . 110
Application Server AutoProbe With WebSphere . . . . . . . . . . . . . . . . . . . . . . . . 111
Application Server AutoProbe With WebSphere 6.0/5.1/5.0 . . . . . . . . . . . 111
Application Server AutoProbe With WebSphere 4.0 (Distributed) . . . . . . . 112
Configuring HTTP Servlet Tracing For Application Server AutoProbe . . . . . 113
Configuring Basic Agent Settings on WebSphere
Agent Profile Location . . . . . . . . . . . . . . . . . .
Defining Agent Profile Location . . . . . . . .
Configuring Introscope Agent . . . . . . . . . . . . .
Agent Naming . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 113
. . . . . . . . . . . . . . . . . . . 113
. . . . . . . . . . . . . . . . . . . 114
. . . . . . . . . . . . . . . . . . . 114
. . . . . . . . . . . . . . . . . . . 114
Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Configuring a Custom Service in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . 116
Configuring a Custom Service in WebSphere 6.0/5.0 . . . . . . . . . . . . . . . . 116
Optional WebSphere Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Chapter 9 Configuring WebSphere on z/OS With Introscope . . . . . . . . . . . 117
Configuring Introscope With WebSphere on z/OS Overview . . . . . . . . . . . . . . 117
Installing Introscope Agent on WebSphere on z/OS . . . . . . . . . . . . . . . . . . . . 117
Page 8
Choosing ProbeBuilder Configuration Option . . . . . . . . . . . . . . . . . . . . .
JVM AutoProbe With WebSphere Using IBM JVM . . . . . . . . . . . . . . . . . .
Creating an AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . .
Running the AutoProbe Connector . . . . . . . . . . . . . . . . . . . . . . . .
Application Server AutoProbe With WebSphere for z/OS . . . . . . . . . . . .
Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 118
. 119
. 119
. 120
. 121
. 122
. 124
Configuring Basic Agent Settings for WebSphere . . . . . . . . . . . . . . . . . . . . . . . 124
Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
New z/OS Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Using PMI with Introscope on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Configuring a Custom Service in WebSphere 5.0 . . . . . . . . . . . . . . . . . . . . . . 127
Configuring a Custom Service in WebSphere 5.0 . . . . . . . . . . . . . . . . . . 127
Optional WebSphere Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Further Installation Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 10 Configuring Sun ONE Application Server With Introscope . . . . 128
Configuring Introscope With Sun ONE Overview . . . . . . . . . . . . . . . . . . . . . . . 128
Installing Introscope Agent on Sun ONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
JVM AutoProbe With Sun ONE 7.0 Using Sun JVM . . . . . . . . . . . . . . . . . . . . . . 130
Application Server AutoProbe With Sun ONE . . . . . . . . . . . . . . . . . . . . . . . . . 131
Application Server AutoProbe With Sun ONE 7.0 . . . . . . . . . . . . . . . . . . . 131
Configuring Basic Agent Settings for SunONE
Agent Profile Location . . . . . . . . . . . . . . . .
Defining Agent Profile Location . . . . . .
Configuring Introscope Agent . . . . . . . . . . .
Additional Configuration Options . . . . .
..
..
..
..
..
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 133
. . . . . . . . . . . . . . . . . . . 133
. . . . . . . . . . . . . . . . . . . 133
. . . . . . . . . . . . . . . . . . . 134
. . . . . . . . . . . . . . . . . . . 135
Chapter 11 Configuring Oracle Application Server 10g With Introscope . . . 136
Configuring Introscope With Oracle 10g Overview . . . . . . . . . . . . . . . . . . . . . 136
Installing Introscope Agent on Oracle 10g . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
JVM AutoProbe With Oracle 10g Using Sun JVM . . . . . . . . . . . . . . . . . . . . . . . 138
Application Server AutoProbe With Oracle Application Server 10g . . . . . . . . . . . 139
Configuring Basic Agent Settings for Oracle
Agent Profile Location . . . . . . . . . . . . . .
Defining Agent Profile Location . . . .
Configuring Introscope Agent . . . . . . . . .
Additional Configuration Options . . .
10g
....
....
....
....
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 140
. . . . . . . . . . . . . . . . . . . 140
. . . . . . . . . . . . . . . . . . . 140
. . . . . . . . . . . . . . . . . . . 140
. . . . . . . . . . . . . . . . . . . 141
Page 9
Chapter 12 Configuring SAP NetWeaver With Introscope . . . . . . . . . . . . . . 142
Configuring Introscope With SAP NetWeaver Overview
. . . . . . . . . . . . . . . . . 142
Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ProbeBuilder Configuration Options . . . . . . . .
Choosing ProbeBuilder Configuration Option .
JVM AutoProbe Using Sun or IBM JVM . . . . .
Creating an AutoProbe Connector . . . .
Running the AutoProbe Connector . . . .
JVM AutoProbe Using HP HotSpot JVM . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 143
. . . . . . . . . . . . . . . . . . . 143
. . . . . . . . . . . . . . . . . . . 144
. . . . . . . . . . . . . . . . . . . 144
. . . . . . . . . . . . . . . . . . . 145
. . . . . . . . . . . . . . . . . . . 146
Configuring Basic Agent Settings . . . . . . . . . . . .
Additional Configuration Options . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 147
. . . . . . . . . . . . . . . . . . . 147
. . . . . . . . . . . . . . . . . . . 147
. . . . . . . . . . . . . . . . . . . 147
. . . . . . . . . . . . . . . . . . . 148
Chapter 13 Configuring Other Application Servers or Applications With Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Configuring Introscope With Other Application Servers Overview . . . . . . . . . 149
Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ProbeBuilder Configuration Options . . . . . . . .
Choosing ProbeBuilder Configuration Option .
JVM AutoProbe Using Java 5.0 JVM . . . . . . .
JVM AutoProbe Using Sun or IBM JVM . . . . .
Creating an AutoProbe Connector . . . .
Running the AutoProbe Connector . . . .
JVM AutoProbe Using HP HotSpot JVM . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 150
. . . . . . . . . . . . . . . . . . . 150
. . . . . . . . . . . . . . . . . . . 151
. . . . . . . . . . . . . . . . . . . 151
. . . . . . . . . . . . . . . . . . . 151
. . . . . . . . . . . . . . . . . . . 152
. . . . . . . . . . . . . . . . . . . 152
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 152
. . . . . . . . . . . . . . . . . . . 152
. . . . . . . . . . . . . . . . . . . 153
. . . . . . . . . . . . . . . . . . . 153
. . . . . . . . . . . . . . . . . . . 154
Chapter 14 Configuring the Java Applications Manually With ProbeBuilder 155
Configuring Java Applications Manually Overview . . . . . . . . . . . . . . . . . . . . . . 155
Configuring Java Applications With ProbeBuilder Wizard . . . . . . . . . . . . . . . . 155
Installing Introscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Adding Probes to Bytecode With ProbeBuilder Wizard . . . . . . . . . . . . . . . . . . . 157
Editing the Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Configuring Java Applications With Command-Line ProbeBuilder . . . . . . . . . . 162
Installing Introscope Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Adding Probes to Bytecode Using Command-Line ProbeBuilder . . . . . . . . . . . . . 163
Editing the Classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 165
. . . . . . . . . . . . . . . . . . . 165
. . . . . . . . . . . . . . . . . . . 165
. . . . . . . . . . . . . . . . . . . 165
. . . . . . . . . . . . . . . . . . . 166
Page 10
Options for Running Introscope-enabled Code . . . . . . . . . . . . . . . . . . . . . . . . . 166
Switching Back to Your Non-Introscope-enabled Code . . . . . . . . . . . . . . . . . . 167
Chapter 15 Optional Introscope Configurations. . . . . . . . . . . . . . . . . . . . . . 168
Agent Naming Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Agent Name Location Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Obtaining Agent Name Using System Properties . . . . . . . . . . . . . . . . . . . . . . . 169
Specifying Agent Name Using Java System Property . . . . . . . . . . . . . . . . 169
Specifying Agent Name Using System Property Key . . . . . . . . . . . . . . . . 170
Obtaining Agent Name Automatically From Application Server . . . . . . . . . . . . . 170
Supported Application Server Versions . . . . . . . . . . . . . . . . . . . . . . . . . 170
How Automatic Agent Naming Works . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Automatic Agent Naming and Renamed Agents . . . . . . . . . . . . . . . . . . . 171
Enabling Automatic Agent Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Advanced Automatic Naming Options . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Agent Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Configuring Agent Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Configuring Automatic Agent Failback to Primary Enterprise Manager . . . . . . . . 175
Agent Failover and Domain/User Configuration . . . . . . . . . . . . . . . . . . . . . . . . 175
Switching Between “Full” and “Typical” Tracing Options . . . . . . . . . . . . . . . . 175
Switching to “Typical” Tracing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Multiple Agent Options . . . . . . . . . . . . . . . . . . . . .
Enabling Cloned Agent Naming . . . . . . . . . . . . .
Scenario . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Cloned Agent Naming in the Agent
Running An Application Twice On One Machine . .
How Introscope Resolves Agent Naming Conflicts
. . . . . . . . . . . . . . . . . . . . . . 176
. . . . . . . . . . . . . . . . . . . . . . 176
. . . . . . . . . . . . . . . . . . . . . . 176
Profile . . . . . . . . . . . . . . . . . 177
. . . . . . . . . . . . . . . . . . . . . . 177
. . . . . . . . . . . . . . . . . . . . . . 177
Other Optional Agent Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Using Custom ProbeBuilder Directives Files (AutoProbe installations only) . . . . . 177
Removing Line Numbers in Bytecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Turning Off Socket Input/Output Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Agent Logging Options . . . . . . . . . . . . . . . . . . .
Agent Log Files and Automatic Agent Naming .
Agent Logfile Automatic Naming Notes .
Running Agent in Verbose Mode . . . . . . . . . .
Redirecting Agent Output to a File . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 178
. . . . . . . . . . . . . . . . . . . 179
. . . . . . . . . . . . . . . . . . . 179
. . . . . . . . . . . . . . . . . . . 179
. . . . . . . . . . . . . . . . . . . 179
Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Enabling Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Enabling Platform Monitors on Windows Server 2003 . . . . . . . . . . . . . . . 181
Enabling Platform Monitors on AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Disabling Platform Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Platform Configuration Troubleshooting Option . . . . . . . . . . . . . . . . . . . . . . . . 182
JMX Filters For Obtaining Advanced Performance Data . . . . . . . . . . . . . . . . . . 182
WebLogic 9.0 MBean Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Metric Name Conversion and Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Primary Keys Conversion Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Default Conversion Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
JMX Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Configuring JMX Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Step 1: Enabling JMX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Page 11
Step 2: Defining Primary Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Step 3: Defining JMX Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Viewing JMX Data In Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
WebLogic Diagnostic Framework Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Metric Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Obtaining WLDF Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Advanced WebSphere Performance Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Turning on Performance Monitor Settings in WebSphere . . . . . . . . . . . . . . . . . 189
Turning on Performance Monitor Settings in WebSphere 6.0/5.0.x . . . . . . 189
Turning on Performance Monitor Settings in WebSphere 4.0 (Distributed) . 189
Enabling and Defining PMI Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Viewing WebSphere Agent PMI Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Enterprise Manager Database Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Upgrading Database Schema Tables From Previous Versions . . . . . . . . . . . . . . 194
Configuring a New Enterprise Manager to Database Connection . . . . . . . . . . . . 194
Running Database Creation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Setting Database Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Sample Microsoft Access Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Optional Enterprise Manager Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Running Enterprise Manager Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Configuring Scheduled Export of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Configuring Scheduled Export of Data . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Adding or Moving Management Modules Between Enterprise Managers . . . . . . . 198
Defining Explicit Table Qualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Workstation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Workstation Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Running Workstation in Verbose Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Redirecting Workstation Output to a File . . . . . . . . . . . . . . . . . . . . . . . . 200
Connecting Workstation to Enterprise Manager Behind Firewall . . . . . . . . . . . . 200
Optional ProbeBuilder Configurations . . . . . . . .
Integrating ProbeBuilder into the Build Process .
ProbeBuilder Log . . . . . . . . . . . . . . . . . . . . . .
AutoProbe ProbeBuilder Log . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . 200
. . . . . . . . . . . . . . . . . . 200
. . . . . . . . . . . . . . . . . . 201
. . . . . . . . . . . . . . . . . . 201
Miscellaneous Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Java2 Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Chapter 16 Database Configuration and Reporting . . . . . . . . . . . . . . . . . . . 202
Introscope 6.0.1 Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Database Tables . . . . . . . . . . . . . . . . . . . . . . . .
Version Table . . . . . . . . . . . . . . . . . . . . . . .
Index Table . . . . . . . . . . . . . . . . . . . . . . . .
Property Table . . . . . . . . . . . . . . . . . . . . . .
Agent Table . . . . . . . . . . . . . . . . . . . . . . . .
Resource Table . . . . . . . . . . . . . . . . . . . . . .
Metric Name Table . . . . . . . . . . . . . . . . . . .
Metadata Table . . . . . . . . . . . . . . . . . . . . . .
Metric Table . . . . . . . . . . . . . . . . . . . . . . . .
Resource Metric Table . . . . . . . . . . . . . . . . .
Record Type Table . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . 204
. . . . . . . . . . . . . . . . . . 204
. . . . . . . . . . . . . . . . . . 204
. . . . . . . . . . . . . . . . . . 205
. . . . . . . . . . . . . . . . . . 205
. . . . . . . . . . . . . . . . . . 206
. . . . . . . . . . . . . . . . . . 206
. . . . . . . . . . . . . . . . . . 206
. . . . . . . . . . . . . . . . . . 206
. . . . . . . . . . . . . . . . . . 209
. . . . . . . . . . . . . . . . . . 209
Database Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Page 12
Querying Introscope Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Creating Reports from Introscope Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Introscope Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Chapter 17 ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Introduction to Directives . . . . . . . . . . . . . . . . .
Components Tracked . . . . . . . . . . . . . . . . . .
Single-Metric Tracers and Tracer Groups . . . .
Only Defined Methods Traced . . . . . . . . . . . .
ProbeBuilder Directive Files . . . . . . . . . . . . .
Default System ProbeBuilder Files . . . . .
Custom ProbeBuilder Directives Files . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . 213
. . . . . . . . . . . . . . . . . . 213
. . . . . . . . . . . . . . . . . . 213
. . . . . . . . . . . . . . . . . . 214
. . . . . . . . . . . . . . . . . . 214
. . . . . . . . . . . . . . . . . . 214
. . . . . . . . . . . . . . . . . . 214
Default ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Full and Typical ProbeBuilder Directives Sets . . . . . . . . . . . . . . . . . . . . . . . . . 215
Modifying Default ProbeBuilder Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Default Tracer Groups and Toggles Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Turning on Toggles To Gather Additional Metric Information . . . . . . . . . . 217
Turning Tracer Groups On or Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Turning a Tracer Group On or Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Turning On InstrumentPoint Directives . . . . . . . . . . . . . . . . . . . . . . . . . 218
Adding Classes to a Tracer Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
EJB Subclass Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Creating Custom Tracers . . . . . . . . . . . . . . . . .
Custom Tracers and Keywords . . . . . . . . . .
Tracer Syntax . . . . . . . . . . . . . . . . . .
Custom Method Tracer Examples . . . . . . . .
Example Average Tracer . . . . . . . . . .
Example Rate Tracer . . . . . . . . . . . . .
Example Per Interval Counter Tracer . .
Example Counter Tracer . . . . . . . . . .
Example Combined Counter Tracers . .
Custom Tracers in Blame Technology . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 220
. . . . . . . . . . . . . . . . . . . 220
. . . . . . . . . . . . . . . . . . . 221
. . . . . . . . . . . . . . . . . . . 223
. . . . . . . . . . . . . . . . . . . 223
. . . . . . . . . . . . . . . . . . . 223
. . . . . . . . . . . . . . . . . . . 223
. . . . . . . . . . . . . . . . . . . 223
. . . . . . . . . . . . . . . . . . . 223
. . . . . . . . . . . . . . . . . . . 224
Creating Advanced Custom Tracers . . . . . . .
Advanced Single-Metric Tracers . . . . . . . .
Signature Differentiation . . . . . . . . .
Keyword-Based Substitution . . . . . .
Metric-Name-Based Parameters . . . .
Skips . . . . . . . . . . . . . . . . . . . . . . . . . . .
Combining Custom Tracers . . . . . . . . . . .
Counting Object Instances . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 225
. . . . . . . . . . . . . . . . . . . 225
. . . . . . . . . . . . . . . . . . . 225
. . . . . . . . . . . . . . . . . . . 225
. . . . . . . . . . . . . . . . . . . 226
. . . . . . . . . . . . . . . . . . . 227
. . . . . . . . . . . . . . . . . . . 227
. . . . . . . . . . . . . . . . . . . 227
Directive Keywords . . . . . . . . . . . . . . . . . . . . . .
ProbeBuilder Skip Keywords . . . . . . . . . . . . .
ProbeBuilder Action Keywords . . . . . . . . . . .
Threshold ProbeBuilder Action Keywords
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . 227
. . . . . . . . . . . . . . . . . . 228
. . . . . . . . . . . . . . . . . . 228
. . . . . . . . . . . . . . . . . . 230
Updating Introscope With Modified or New ProbeBuilder Directives Files . . . . 231
Adding New Custom ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . . 232
Using AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Using ProbeBuilder Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Applying Changes To ProbeBuilder Directives Files . . . . . . . . . . . . . . . . . . . . . 232
Using AutoProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Page 13
Using the ProbeBuilder Wizard or the Command-Line ProbeBuilder . . . . . . 233
Appendix A Introscope Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Introscope Agent Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Agent Settings with AutoProbe Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Directives Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Agent Settings Common to Both AutoProbe and non-AutoProbe Installations . . . 235
Log 4J Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Enterprise Manager Connection Order . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Enterprise Manager Locations and Names . . . . . . . . . . . . . . . . . . . . . . . 235
Agent and Process Name Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Agent Thread Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
PMI Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
JMX Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
LeakHunter Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Transaction Tracer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Introscope ProbeBuilder Settings File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Introscope ProbeBuilder Wizard.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Introscope Enterprise Manager Settings Files
IntroscopeEnterpriseManager.properties File
Ports . . . . . . . . . . . . . . . . . . . . . . . .
Log 4J Settings . . . . . . . . . . . . . . . . .
SmartStor Properties . . . . . . . . . . . . .
Transaction Event Database . . . . . . . .
Database Properties . . . . . . . . . . . . .
Flat File Properties . . . . . . . . . . . . . .
SNMP Collections . . . . . . . . . . . . . . .
WebView . . . . . . . . . . . . . . . . . . . . .
Introscope Enterprise Manager.lax File . . . .
EMService.conf File . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . . . . . . . . . . . 242
. . . . . . . . . . . . . . . . . . . 242
. . . . . . . . . . . . . . . . . . . 242
. . . . . . . . . . . . . . . . . . . 242
. . . . . . . . . . . . . . . . . . . 242
. . . . . . . . . . . . . . . . . . . 243
. . . . . . . . . . . . . . . . . . . 243
. . . . . . . . . . . . . . . . . . . 243
. . . . . . . . . . . . . . . . . . . 243
. . . . . . . . . . . . . . . . . . . 243
. . . . . . . . . . . . . . . . . . . 247
. . . . . . . . . . . . . . . . . . . 248
Introscope Workstation Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
IntroscopeWorkstation.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Introscope Workstation.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Introscope WebView Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
IntroscopeWebView.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Introscope WebView.lax File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Database Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
CustomDBRecordTypes.properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Extensions Settings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
LocalAuthenticationExtension.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
LDAPAuthenticationExtension.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Appendix B Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Apache Software License, Version 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
License for JDOM Binary Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
License for Tanuki Software Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Page 14
Preface
Introscope® is a system management application created to help you manage Java
Application performance. Unlike development tools, Introscope® is designed to scale with
minimal performance impact. This allows you to monitor and manage your application
performance in live production environments.
Introscope 6.0.1 Installation and Configuration Guide
Audience
This book is written for users who are experienced in installing and configuring
application servers and systems. The book assumes that the reader knows how to install
and run Java software on distributed and mainframe systems, set classpaths, and modify
property files.
Introscope 6.0.1 User Guides
Introscope documentation is comprised of the following guides:
• Introscope 6.0.1 Upgrade Guide
• Introscope 6.0.1 Installation and Configuration Guide (this guide)
• Introscope 6.0.1 Workstation Guide
• Introscope 6.0.1 WebView Guide
Introscope 6.0.1 Upgrade Guide
The Introscope 6.0.1 Upgrade Guide is intended for users who are upgrading an
Introscope deployment from an earlier version to Introscope 6, version 6.0.1. The
Upgrade guide also describes new features introduced in Introscope version 6.0.1.
Introscope 6.0.1 Installation and Configuration Guide (this guide)
The Introscope 6.0.1 Installation and Configuration Guide is intended for those who
install and configure Introscope components. This guide includes information on:
• Installing and configuring the Introscope Agent, Enterprise Manager, and
Workstation
• Introscope-enabling your Java Application
• Configuring Domains in your deployment
• Configuring users, permissions and authentication settings
Introscope 6.0.1 Workstation Guide
The Introscope 6.0.1 Workstation Guide is intended for users who view management
application data and configure monitoring logic in the Introscope Workstation.
Page 15
Organization of the Introscope 6.0.1 Installation Guide
This guide includes information on:
• Viewing data displayed in the Explorer and Console
• Creating and editing Introscope Elements, including Alerts, Persistent Collections,
and Metric Groupings
• Creating and editing Introscope Dashboards
Introscope 6.0.1 WebView Guide
The Introscope 6.0.1 WebView Guide is intended for users who view management
application data in WebView using a web browser.
This book is organized into the following chapters and appendices:
Chapter 1, Introscope Overview, introduces Introscope software, its features, and terms
used in this book.
Chapter 2, Preparing For Installation, discusses system requirements and information to
gather to prepare for Introscope installation.
Chapter 3, Installing Introscope Components, describes how to use the installer to install
and perform basic configurations for Introscope components except Introscope Agent.
Chapter 4, Configuring and Running the Introscope Enterprise Manager, describes how to
hand-edit the properties files after installation of Introscope Enterprise Manager.
Chapter 5, Configuring Introscope Security and Permissions, describes how to configure
Domains, Users and permissions and local and external authentication.
Chapter 6, Configuring Java Applications With Introscope, directs you to the appropriate
chapter to use to Introscope-enable your applications.
Chapter 7, Configuring WebLogic Server With Introscope, describes how to install and
configure the Introscope Agent and Introscope-enable your Java application with
WebLogic Server.
Chapter 8, Configuring WebSphere Application Server With Introscope, describes how to
install and configure the Introscope Agent and Introscope-enable your Java application
with WebSphere Application Server.
Chapter 9, Configuring WebSphere on z/OS With Introscope, describes how to install and
configure the Introscope Agent and Introscope-enable your Java application with
WebSphere Application Server on z/OS.
Chapter 10, Configuring Sun ONE Application Server With Introscope, describes how to
with Sun ONE Application Server.
Chapter 11, Configuring Oracle Application Server 10g With Introscope, describes how to
with Oracle Application Server 10g.
Page 16
Chapter 12, Configuring SAP NetWeaver With Introscope, describes how to install and
configure the Introscope Agent and Introscope-enable your Java application with SAP
NetWeaver Application Server.
Chapter 13, Configuring Other Application Servers or Applications With Introscope,
describes how to install and configure the Introscope Agent with Application Servers not
integrated with AutoProbe.
Chapter 14, Configuring the Java Applications Manually With ProbeBuilder describes how
to install and configure the Introscope Agent and manually Introscope-enable your Java
application.
Chapter 15, Optional Introscope Configurations, describes optional configurations for
Introscope components.
Chapter 16, Database Configuration and Reporting, describes the structure of Introscope
database tables.
Chapter 17, ProbeBuilder Directives, describes how to create custom Directives so that
Introscope reports desired Metrics.
Appendix A, Introscope Properties Files, shows various properties files and the specific
variables that you may need or want to customize.
Appendix B, Licenses, contains third-party licenses.
Type Conventions Used in this Book
Convention
Is Used For
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
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.
directory
/ (slash)
Separates directory and file names in UNIX path names as,
/Introscope6.0.1/examples/
IntroscopeAgent.profile.
Page 17
Need Help With Installation?
Convention
Is Used For
# (pound sign)
UNIX prompt with
root login, as:
# cd /usr
Do not type the # (pound sign).
: (colon)
In UNIX path names in path variables, separates file or directory
names from each other, as:
/<your-applicationpath>.isc/classes:/<yourapplicationpath>.isc/lib/app.jar:
/Introscope6.0.1/lib/Agent.jar
_ (underscore)
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.
Need Help With Installation?
For more help with configuring Introscope, please contact Wily Technical Support at 1888-GET-WILY or wilytech@custhelp.com.
Page 18
1 Introscope Overview
Introscope® version 6.0.1 is a system management application created to help you
manage Java Application performance. Unlike development tools, Introscope is designed
to scale with minimal performance impact. This allows you to monitor and manage your
application performance in live production environments.
Introscope provides real-time Java Application performance management without
requiring access to or modification of the 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.
Page 19
How Introscope Works
How Introscope Works
Figure 1 is a simple conceptual view of how Introscope prepares a Java Application to be
managed.
Figure 1. How Introscope prepares bytecode
Introscope, through the ProbeBuilder, adds Introscope Probes to a Java Application.
Using AutoProbe automates this process, with the ProbeBuilder dynamically adding
Probes to the Java Application when the application starts up.
The Probes measure specific pieces of information about an application without changing
the 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.
Page 20
Introscope Components and Terms
Data collected by the Enterprise Manager can be accessed through one or more
Workstations. You can use the Workstation to view performance data, and configure the
Enterprise Manager to perform such tasks as collecting information for later analysis, and
creating Alerts.
The Enterprise Manager can also be configured to send data to an external data store,
such as a database or flat file.
The following table summarizes key interactions among the components in an Introscope
environment:
ProbeBuilder
•
•
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
Agent
The following terms relate to the Introscope Agent and managed applications.
Agent
An Agent runs as part of the managed application on the Java Application machine. It
collects and summarizes the Probe-reported data and sends it to the Enterprise Manager.
Introscope-enabled Code
Introscope-enabled code is code that has had Introscope Probes added to it.
Managed Java Application
A managed Java Application (or managed application) is a running application whose
code has been Introscope-enabled.
Probes
Probes measure specific pieces of information about an application without changing the
application’s business logic. Probes track real-time performance information, making the
information available for review and action.
Page 21
ProbeBuilder Wizard and Command Line ProbeBuilder
The ProbeBuilder Wizard is GUI tool for running the ProbeBuilder in a windowing
environment. The Command Line ProbeBuilder runs with a command in a non-windowing
environment.
ProbeBuilder and Directives
The ProbeBuilder is an Introscope utility that creates a copy of Java bytecode and adds
Probes to it. ProbeBuilder Directives describe which methods, classes, and sets of classes
to monitor in managed application bytecode. Introscope provides a default ProbeBuilder
Directives file that tracks items in most common Java and Java 2 Enterprise Edition
(J2EE) application programming interfaces (APIs), such as servlets and sockets.
Additionally, custom Probes can be created to measure counts, rates, and response times
of methods being invoked. For more information on ProbeBuilder Directives, see Chapter
17, ProbeBuilder Directives.
AutoProbe
AutoProbe makes administration of a managed application with Introscope easy. With
AutoProbe, the ProbeBuilder inserts probes dynamically into the application code as it is
loaded.
There are two AutoProbe configuration options:
• JVM AutoProbe: dynamically Introscope-enables all classes loaded by the JVM
• Application Server AutoProbe: dynamically Introscope-enables all applications
loaded by the application server
AutoProbe integration is available on the following platforms:
• BEA WebLogic Server v6.1 or higher
• IBM WebSphere Application Server v4.0 or higher
• Hewlett-Packard HotSpot JVM v1.2.2.08 or higher
• WebLogic JRockit 7.0 and higher
Enterprise Manager
The following terms relate to the Introscope Enterprise Manager.
Enterprise Manager
The Enterprise Manager is the central process of an Introscope system. The Enterprise
Manager receives performance data from managed applications via the Agent, runs
requested calculations, makes performance data available to Workstation users, and
sends performance data to a database for later analysis.
Page 22
Metric
A Metric is a measurement of a specific application activity. By default, Probes report a
standard set of Metrics for a managed Java Application. Examples of Metrics collected by
default are:
• CORBA method timers
• Remote Method Invocation (RMI) method timers
• Thread counters
• Network bandwidth
• JDBC update and query timers
• Servlet timers
• Java Server Pages (JSP) timers
• System logs
• File system input and output bandwidth meters
• Available and used memory
• EJB (Enterprise JavaBean) timers
Resource
All Metric information reporting through a single Agent is organized under Resources.
Resources can also contain sub-resources that further group Metrics.
Metric Grouping
A Metric Grouping is a filter using a regular expression that selects a set of Metrics from
the group of all Metrics. Metric Groupings are the building blocks for any Elements
created, such as Views, Alerts, or Persistent Collections.
Blame Technology
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.
Workstation
The following terms relate to the Introscope Workstation.
Page 23
Workstation
The Workstation is the graphical user interface for viewing performance data. You use the
Workstation to create custom views of performance data which you can monitor.
The Workstation consists of three main windows, the Console, Introscope Explorer and
the Dashboard Editor.
Console
The Console displays performance data in a set of customizable views called Dashboards,
such as the one shown below.
Page 24
Introscope Explorer
The Explorer displays, in hierarchical tree structure, all data collected by Agents. The
Explorer also provides tools for creating and editing Management Module Elements, such
as Metric Groupings, Alerts and Calculators that filter performance data.
Page 25
Dashboard Editor
The Dashboard Editor consolidates all Dashboard editing tasks in one location, and adds
even more functionality, such as drawing program functions.
Management Module
Management Modules organize Elements in the Workstation so they can be conveniently
found and manipulated. Management Modules can be used to transport sets of Elements
between Enterprise Managers.
Element
Elements are objects that contain and organize data with monitoring logic.
Elements include:
• Actions
• Alerts
• Calculators
• Dashboards
• Persistent Collections
• Metric Groupings
• Report Templates
• SNMP Collections
Page 26
2 Preparing For Installation
This chapter describes the preparations you should make before installing and configuring
Introscope. Information is provided in the following sections:
• Preparing To Install Introscope
• Information to Collect Before You Begin
• Reviewing Installation and Configuration Process
Preparing To Install Introscope
You should perform several steps before you install Introscope:
• Plan where to install your components
• Choose installation method
• Check system requirements to ensure your system will support Introscope
• Collect information required for installation
• Review the installation and configuration process
Step 1: Plan Where To Install Introscope Components
To maximize performance of your managed Java Application, install the Enterprise
Manager, the Workstation and your Java Application with the Agent on separate
machines. Your deployment may also include a connection to a database.
You might have both UNIX and Windows machines in your Introscope/Java Application
configuration. For example, the machine that runs your Java Application might be a UNIX
machine, whereas the machine that runs the Workstation might be a Windows machine.
Therefore, you might be installing the UNIX version of Introscope on UNIX machines and
the Windows version on Windows machines.
Step 2: Choose Installation Method
The Introscope installer simplifies installation by performing most of the common
Enterprise Manager and Workstation configurations automatically during the installation
process.
Page 27
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
Page 28
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
Interface and Platform
GUI
Console
Silent Mode
Default Mode
Windows
Yes
No
Yes
GUI
AIX
Solaris
HP-UX
Red Hat Linux
Yes
Yes
Yes
GUI
OS/400
No
Yes
Yes
none
z/OS
No
Yes
Yes
none
Other
Yes
Yes
Yes
GUI
Note: For installers without a default mode (z/OS and OS/400), you must specify an
install mode on the command line.
Step 3: Check System Requirements
The following section details the system requirements for Introscope installation.
Supported Platforms
As described earlier, the Introscope system is composed of the Enterprise Manager,
Workstation and Agent(s). WebView is also included in the installer package. Each of
these components has a specific list of supported platforms. General guidelines for
platform support of each part of Introscope are as follows:
TABLE 2. Supported Platforms By Component
Introscope Component
Supported Platforms
Page 29
Enterprise Manager
Most major operating systems including:
Workstation
•
•
•
•
•
•
Windows 2000
Windows Server 2003
Solaris
AIX
HP-UX
z/OS
•
•
•
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
Note: For a complete list of environments supported by Introscope, please refer to the
Wily Compatibility Guide, available from your Wily representative.
Space Requirements
The following table details space requirements for the Introscope installation.
TABLE 3. Installation Space Requirements
What
Hard Drive Space
How Much
•
•
•
•
•
100 MB (complete
installation package)
80 MB for Workstation
alone
80 MB for Enterprise
Manager alone
10 MB for Agent install
80 for WebView alone
Details
Space required for package including
JVM
Temporary
Directory Space
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.
Page 30
Memory Requirements
Table 4 shows the minimum memory each component requires.
TABLE 4. Component Requirements
Component
Required 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
Note: Please note that these memory requirements are for Introscope components only.
Additional memory will be required for the operating system and any other
programs running.
Please see the Wily Compatibility Guide (available from your Wily representative) for the
specific list of support configurations.
Memory Required May Vary
While the previous table states the minimum memory required for each Introscope
component, in practice, the amount of memory needed by the Enterprise Manager and
the Workstation may be higher, depending on the following factors:
• the number of connected Agents
• the number of connected Workstations
• amount of Metrics generated
• monitoring logic, such as Metric Groupings, Persistent Collections, Alerts,
Calculators, etc.
Contact Wily Support for assistance in determining the proper amount of memory for
your deployment.
Bundled JVMs
For your convenience, Java Virtual Machine comes bundled with the Introscope install on
the following platforms: Sun Solaris, Windows, AIX, HP-UX and Red Hat Linux.
Table 5 shows which JDK versions are bundled with the installer:
TABLE 5. Bundled JVM Versions
Operating System
JDK
Solaris
Sun JDK 1.4.2_03
Page 31
Information to Collect Before You Begin
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
JVM Used by Installer
During install, the installer will use the JVM it was bundled with, unless the user forces an
alternate JVM on the command line when invoking the installer.
For any installer that does not bundle a JVM (such as OS/400), the user must specify the
desired JVM (version 1.3.x or higher) on the command line when invoking the installer.
Whenever possible, use a version 1.4.x JVM.
Step 4: Review Installation Notes
• If you are installing the Workstation and Enterprise Manager on separate
machines, synchronize the clocks on each of the machines. If clocks are not
synchronized, there may be discrepancies in historical query results between
Workstations and Enterprise Manager.
• For z/OS, the installed text files are already in EBCDIC format.
• For OS/400, we recommend you use QShell to install in either Console or Silent
mode.
• To run installers on machines without video cards, or Xservers, you must force
Console mode.
• When running WebView on AIX, X11 server must be running.
Information to Collect Before You Begin
Enterprise Manager Information
Collect host and port locations for each machine on which an Enterprise Manager is
installed. Needs one port to listen for the Agent and two ports to listen for the
Workstation, one of which is used for a secure connection during user authentication.
The secure port is only needed for firewall configuration, and does not need to be
specified in the Workstation itself.
These need to be unused ports at this IP address, and should be opened in a firewall if
needed.
Note: If you plan to use Agent Failover, you will need to collect host and port information
for each backup Enterprise Manager as well.
Collect or decide on the following information before installing Introscope:
Page 32
Reviewing Installation and Configuration Process
TABLE 6. Enterprise Manager Information To Collect
Enterprise Manager Information
Host and Port Information
Host Name or IP
address
Agent Port
Workstation
Port
Secure
Workstation Port
EM1_________________
EM1_______
EM1________
EM1__________
EM2_________________
EM2________
EM2_______
EM2__________
EM3_________________
EM3_______
EM3_______
EM3__________
EM4_________________
EM4________
EM4_______
EM4__________
User Name and Password on the Enterprise Manager Machine
User name (with administrative rights) and password on each Enterprise Manager machine.
User Name
Password
EM1_________________
EM1_______
EM2_________________
EM2_______
EM3_________________
EM3_______
EM4_________________
EM4_______
License obtained
Check here when license is obtained.
After 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.
Page 33
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 Process
To start the installation process, proceed to the next chapter, Installing Introscope
Components.
Note: If you are upgrading your Introscope deployment, consult the Introscope 6.0.1
Upgrade Guide to be sure that the necessary files are backed up before performing
a “clean” install.
Page 34
3 Installing Introscope Components
This chapter covers the installation and configuration of Introscope in the following
sections:
• Installer Files
• Installing Introscope In GUI Mode
• Installing Introscope In Console Mode
• Installing Introscope In Silent Mode
• Uninstalling Introscope
Installer Files
Obtain the appropriate aggregate installer file from your Wily representative.
You now have a choice of two installer files:
• install package that contains Introscope components (Enterprise Manager,
Workstation, and WebView) plus the Introscope Agent
• install package of Introscope components without the Introscope Agent
The following table details the names of the installer files.
Operating
System
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
For SAP Support Only
Operating System
Installer Filename
Windows
introscope6.0.1windowsinstall.SAPExpertCenter.zip
Page 35
Installing Introscope In GUI Mode
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
• If using Windows or OS/400, unzip the installer file.
• If using any other platform, extract the installer files using the following command
(substituting the appropriate filename for the one in this example):
#tar xvf introscope6.0.1solarisinstall.tar
Installer Files
The following table details the names of the installer files inside the aggregate install
package.
Operating System
Installer Filename
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
For SAP Support Only
Operating System
Installer Filename
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
After you have extracted the installer from the installer package, decide which installer
mode you are going to use, and follow the instructions in the appropriate section.
Page 36
Installation in GUI mode
This section describes Introscope installation in GUI mode. The installer defaults to GUI
mode on all platforms except z/OS and OS/400.
GUI mode is not supported on z/OS, or OS/400. Installer must be invoked in Console
mode (see Installing Introscope In Console Mode, page 49).
The GUI will walk the user through a series of friendly windows that:
• identify which components to install
• collect settings for each desired component
• error-check the settings and prompt the user to correct them if needed
• install the product, displaying a progress bar
• summarize the install results and name the location of more detailed log(s)
Launching GUI Mode Installer
There are several ways to launch the installer in GUI mode, depending on the installer file
type:
• For .exe files, double-click on the file, or invoke it from the command line.
For example:
c:> .\<installername>.exe
• For .bin files (with bundled JVM), invoke it from the command line.
For example:
[root@qaserver:/] ./introscope6.0.1solaris.bin
• For .jar files (no bundled JVM), invoke it from the command line, and specify the
appropriate JVM.
For example:
[root:/] /usr/java/bin/java -classpath introscope6.0.1other.jar
install
GUI Installation Sequence
You navigate through the installer windows using Next and Back buttons. You can use
the Tab key to select your choice, and the Return key to accept the choice.
The instructions shown in this section will show a complete install of all Introscope
components, and will say Yes to all installation options available.
General Installation Information
1.
After you launch the installer, you will see the Introduction screen.
Page 37
2.
Click Next.
In the Choose Install Set screen, choose which Introscope components to install.
You have the following options:
• Complete Install: installs all Introscope components
• Minimal Install: installs only the Enterprise Manager and Workstation
• Custom, and check the boxes for which components to install.
Page 38
3.
Click Next. The Choose Install Folder screen appears.
Click Next to accept the default location, or click Browse to specify a different
location.
4.
Click Next. If you are using an installer on a platform which includes a bundled JVM,
the Configure JVM Settings screen appears.
Note: If you are using an installer which does not include a JVM, you will not see this
choice screen. You will be automatically prompted in later screens to specify
JVM settings per component.
Page 39
• 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.
Page 40
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.
location.
Page 41
Note: Be sure to place the Transaction Event Database directory on drive with at
least 2GB of disk space available for data storage. The amount of space
required will vary depending on factors such as number of Transactions stored
and how long the data is kept.
9.
The second Enterprise Manager Transaction Event Storage screen appears.
Click Next to accept the default aging value, or enter another value (in days) and
then click Next.
10. The Enterprise Manager Data Storage Configuration screen appears.
• Leave the default Yes setting in the drop-down list box to use the SmartStor™
feature, which constantly records all Introscope data without the need for a
Page 42
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.
location.
Note: Be sure to place the SmartStor directory on drive with at least 8 GB of disk
space for SmartStor data storage. Since the amount of space required will
vary depending on factors such as number of Metrics and storage frequency,
see SmartStorTM Data Storage, page 60, for information on estimating disk
size requirements.
Page 43
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.
Page 44
• 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.
Page 45
• Workstation Default Host: the host entered here will be shown by default in the
Workstation Login screen.
• Workstation Default Port: the port entered here will be shown by default in the
Workstation Login screen.
16. Click Next.
If you selected “yes” in the earlier Configure JVM Settings screen, the
Workstation Advanced JVM Settings screen appears.
Specify the Java executable to use to run the Workstation, and any desired JVM
command-line arguments.
17. Click Next.
The Workstation Pre-Installation Summary screen appears.
Review the summary of Workstation installation configurations. Go back and make
corrections if necessary.
18. Click Next.
Page 46
WebView Settings
The WebView Settings screen appears.
19. Click Next to accept the default HTTP host, and Enterprise Manager port and host
values
OR
type other values in the appropriate fields, and click Next.
The WebView As Windows Service screen appears.
• Click No to continue without configuring WebView as a Windows Service.
• Select Yes to configure the WebView as a Windows Service. Then:
Page 47
— enter a unique service name for this instance of WebView as Windows Service
— either accept the default display name, or enter a unique display name.
20. Click Next.
If you selected “yes” in the earlier Configure JVM Settings screen, the WebView
Advanced JVM Settings screen appears.
Specify the Java executable to use to run WebView, and any desired JVM commandline arguments.
21. Click Next.
The WebView Pre-Installation Summary screen appears.
Review the summary of WebView installation configurations. Go back and make
Page 48
Installing Introscope In Console Mode
ProbeBuilder Settings
If you selected “yes” in the earlier Configure JVM Settings screen, the
ProbeBuilder Advanced JVM Settings screen appears.
Specify the Java executable to use to run the ProbeBuilder, and any desired JVM
command-line arguments.
22. Click Next.
The ProbeBuilder Pre-Installation Summary screen appears.
Review the summary of ProbeBuilder installation configurations. Go back and make
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.
♦
Proceed to Chapter 6, Configuring Java Applications With Introscope.
To install using Console mode, you must force it on the command line.
Installation using Console mode will be identical to that of the GUI mode, in that it will:
• Ask for the same fields as GUI mode
• Return the same error messages as GUI mode
• Present the same result summaries as GUI mode
Page 49
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:
Page 50
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.
♦
Silent mode is supported for installers on all platforms.
In silent mode, the installer is run from a command line and takes input from a response
file. This makes multiple installations of Introscope easy.
The silent mode installer will run in the background with no feedback. See the GUI
Installation Sequence, page 37, to review the information requested by the installer.
After installation, you can check the results in the installer logs.
Response File Methods
There are several methods you can use to perform a silent install using a response file:
• use an automatically-generated response file
• manually configure the sample response file with the desired settings
Using an Automatically-generated Response File
Every installation creates a response file, containing the settings specified during the
install process. You can use this response file for subsequent silent mode installs. The file
is named with the date and time information of the last installation, and is found in the
following location:
<Introscope home>/install/
autogenerated.responsefile.<year>.<month>.<day>.<hour>.<minutes>
.<second>
For example, an installation done April 30, 2004 at 7:10:00 a.m. would have a response
file with the following name:
<Introscope home>/install/
autogenerated.responsefile.2004.4.30.7.10.00
Using a Manually-Configured Sample Response File
You can manually configure the desired settings in the sample response file, then use this
file for subsequent silent mode installs. The sample response file is found in the following
location:
<Introscope home>/examples/installer/SampleResponseFile.txt
Page 51
The response file can have any name, and can be located in any directory, as long as you
specify the name and location in the command line when invoking the silent mode for the
installer.
The properties in the response file are very similar to those in the usual properties files.
However, keep in mind the following issues when entering values for the properties in the
response file:
• On Windows, backslashes need to be “escaped.”
• On Windows, any directory supplied needs to be suffixed by a slash.
For example:
/tmp/Wily1/Introscopedirectory/
• To specify any JVM settings, you will need to first uncomment the properties.
Launching Silent Mode Installer
Using z/OS
After extracting the introscope6.0.1zOSinstall.tar file, you will see two files:
• introscope6.0.1zOS.jar
• runinstaller.sh
The runinstaller.sh script will launch the installer, check that the specified response
file exists, and check there is at least 60 MB of space in the /tmp directory.
1.
Before running the script, check that a JAVA_HOME environment variable exists by
running:
echo $JAVA_HOME
2.
If it exists, continue to step 3. If no such variable exists:
— open the runinstaller.sh script in a text editor.
— Find the line that sets the Java home.
— Uncomment this line, and modify the path to specify your own Java home.
— Save your changes, then launch the script.
3.
Launch the script using:
runinstaller.sh introscope6.0.1zOS.jar -silent <absolute path to
responsefile>
Using Any Other Platform
To run the installer in silent mode:
• For .exe or .bin files, specify the path to the installer and the absolute path to the
response file:
<path to installer> -f <absolute path to responsefile>
Page 52
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.
♦
Page 53
Uninstalling Introscope
The Introscope base installer comes with an uninstaller program, which will remove all
installed components.
The following things will happen when you run the uninstaller:
• all files originally installed with Introscope will be deleted
• if you created a sample database during install, the uninstaller will ask to delete it
• if any other database is present, it will not be removed
• if there were files installed or created after original Introscope install (such as
Enterprise Manager logs), the uninstaller will instruct you to hand-delete them
Uninstall Modes
The uninstaller will run in whichever mode the installer originally ran in. For example, if
you installed in GUI mode, the uninstaller will also run in GUI mode. However, for
installers with bundled JVMs, you can force a different uninstall mode (for example, if you
originally ran the install in silent mode, and now want to control what is uninstalled in the
GUI mode).
This section displays the uninstall process in GUI mode. Just like in the installer, the
Console mode will ask for the same information as the GUI mode. The silent mode
uninstaller will just uninstall everything in the background.
Forcing an Uninstall Mode
You force a different uninstall mode by specifying the desired uninstall mode in the
uninstaller .lax file.
To specify uninstall mode in the uninstaller .lax file:
1.
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 Uninstaller
To uninstall Introscope components:
1.
Locate the Introscope uninstaller for your platform:
• Windows: <Introscope home>/Uninstaller Data/Uninstall
Introscope.exe.
Page 54
• Unix: <Introscope home>/Uninstaller Data/Uninstall/
Uninstall_Introscope
• z/OS, OS/400 and other: <Introscope home>/Uninstaller Data/
Uninstall/uninstaller.jar
2.
Run the uninstaller, using the appropriate command for your platform:
• For .exe or .bin files: run the .exe, or ./<bin file>
• For other: run the following command:
java -classpath uninstaller.jar uninstall
The Uninstall Introscope screen appears.
3.
If you opted to install the Enterprise Manager or WebView as a Windows Service
during the installation, a screen similar to this appears:
Page 55
• 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.
Page 56
4 Configuring and Running the Introscope
Enterprise Manager
This chapter describes how to manually configure basic properties for the Enterprise
Manager. You can use this chapter to:
• configure basic Enterprise Manager properties you 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
Page 57
Installing License
Installing License
If 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 Manager
After configuration, you can start the Enterprise Manager.
Note: Make sure the Enterprise Manager has both read access and write access to the
<Introscope home>/config directory, so that configuration changes will be
properly saved.
UNIX
♦
On UNIX, run Introscope_Enterprise_Manager.
Windows (Enterprise Manager not configured as a Windows Service)
If you configured the Enterprise Manager as a Windows Service during installation, the
Enterprise Manager will be started upon completion of the installation process.
Otherwise, start the Enterprise Manager manually as follows:
• from the Start menu, Introscope > Administration > Introscope Enterprise
Manager.
OR
• run Introscope Enterprise Manager.exe (located in the Introscope
directory).
OS/400
The Enterprise Manager can be started in OS/400 by:
• using a start script (described in the following section)
• running the Enterprise Manager as a Java Program, described in Running the
Enterprise Manager as a Java Program, page 59.
Running OS/400 Start Script
When the Enterprise Manager is installed on OS/400, the installer will automatically
generate a start script. You can invoke the start script from a QShell command prompt as
follows:
nohup ./runem.sh [IHOME] &
where [IHOME] is the optionally provided Introscope root directory. In other words,
nohup ./runem.sh &
Page 58
Starting Enterprise Manager
will assume that the Introscope home is the directory where you launched the script.
nohup ./runem.sh /blah &
will assume that /blah is the Introscope root directory.
z/OS
To start the Enterprise Manager, use the runem.sh file. For instructions on running the
Enterprise Manager on z/OS, please see Configuring Enterprise Manager To Run As a z/
OS Batch Job, page 67.
Writing Status Information to Logfile
As the Enterprise Manager starts and runs, it writes status information to a log, which, by
default, appears in a command prompt window. See Enterprise Manager Metric Throttle,
page 63 for information on configuring Enterprise Manager logging.
Running the Enterprise Manager as a Java Program
You can run the Enterprise Manager as a Java program. An example of running Enterprise
Manager from the command line from the <Introscope home> directory is:
java -classpath lib/EnterpriseManager.jar;lib/
IntroscopeServices.jar;lib/SNMPAdapter.jar
com.wily.introscope.api.IntroscopeEnterpriseManager
The exact syntax depends on the version of Java that used and other settings in your
environment. If you are using the Enterprise Manager with a database, you will need to
add the JDBC database driver to the classpath.
Stopping Enterprise Manager
To stop the Enterprise Manager:
♦
From the Enterprise Manager terminal window, enter:
iscopeshutdown
♦
If you are a user with shutdown privileges for the Enterprise Manager, you can also
shut down the Enterprise Manager from within the Workstation in an Explorer
window, by selecting Manager > Shut Down Enterprise Manager.
When the Enterprise Manager is shut down:
• Agents will stop collecting data
• SmartStor will not save data
• data will stop being sent to a database (if one is configured)
• you will be logged out of the Workstation
• all users connected to the Enterprise Manager will be disconnected
Page 59
Enterprise Manager Ports
Enterprise Manager Ports
Designate a port on the Enterprise Manager that can be used for listening to incoming
Agent connections.
If you are using multiple Enterprise Managers, you must complete these steps for each
Enterprise Manager. To configure Enterprise Manager ports:
1.
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 Storage
SmartStorTM 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 SmartStor
SmartStor is enabled by default during Introscope installation (unless you disable it).
Enabling SmartStor
SmartStorTM is enabled by default during installation (unless you chose to turn it off
during installation).
To enable SmartStorTM:
1.
Open the file, IntroscopeEnterpriseManager.properties.
2.
For the property, introscope.enterprisemanager.smartstor.enable, enter a
value of true.
Page 60
SmartStorTM Data Storage
3.
To use the default frequency and aging settings, save changes and restart the
Enterprise Manager. Otherwise, use the instructions in the following sections to
customize frequency and aging settings.
Determining SmartStor System Requirements
To help determine the system requirements that will enable SmartStor to effectively
handle your Metric workload, we have provided an Excel spreadsheet, located in the
following directory:
<Introscope home>/examples/SmartStorSizing.xls
You can experiment with different values for number of Metrics, and different periods and
aging ranges for your data tiers. The resulting GB size usage will appear in the table
below.
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:
Page 61
Transaction Event Database Storage
• the storage frequency must be a multiple of 15 seconds
• the frequency must not be greater than 1800 seconds (30 minutes)
• each tier's frequency must be an even multiple of the previous tier's frequency
(this multiple can be one; each tier can have the same frequency)
• the age must not be zero
• all three tiers must be defined, and you cannot define more than three tiers.
To configure the SmartStor data tier values:
1.
2.
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 Storage
Transaction Event data storage allows the storage and querying of Transaction Trace and
other event data.
This functionality is enabled by default during Introscope installation, and the installation
prompts for values for the following settings:
• where transaction event data will be stored
• the data aging period (in days).
You can manually change either of these settings. Note that if you increase the data aging
period, there will be an increase in system overhead, and required data space (currently
2 GB).
Configuring Transaction Event Database Settings
1.
2.
Make the desired changes to the following properties:
Property
Function
Notes
introscope.enterprisemanager.transactioneve
nts.storage.dir
Specifies where to
store transaction event
data.
Select a location that
has at least 2 GB of
available space.
Page 62
Enterprise Manager Metric Throttle
introscope.enterprisemanagter.transactionev
ents.storage.max.data.age
3.
Specifies (in days) how
long to store
transaction event data.
Increasing the data
aging period has
overhead and storage
implications.
Save changes.
Enterprise Manager Metric Throttle
Occasionally a situation may arise in which an Agent is misconfigured and becomes a
“runaway” Agent, creating thousands of Metrics in quick succession, overloading the
Enterprise Manager. If this happens in production, the user often had to put up with the
situation because they 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 Throttle
If not changed by the user, the default Metric throttle is 50,000 Metrics. If you want to
change the Metric threshold, you will need to manually add a property to the
IntroscopeEnterpriseManager.properties file.
To configure the Enterprise Manager Metric throttle:
1.
2.
Add the property, introscope.enterprisemanager.agent.metrics.limit, to
the file, and enter a value for the Metric throttle limit.
3.
Save changes.
4.
Enterprise Manager Logging Options
Running Enterprise Manager in Verbose Mode
Running the Enterprise Manager in verbose mode records details to the log, which is
helpful in debugging.
To run the Enterprise Manager in verbose mode:
Page 63
Running Enterprise Manager in nohup Mode on UNIX
1.
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 File
To redirect Enterprise Manager output to a file:
1.
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.Log4JSeverit
yLevel,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 UNIX
The Introscope Enterprise Manager can be run in nohup mode on UNIX, but several
properties must first be set in the Introscope properties files.
1.
In the Introscope Enterprise Manager.lax file, change the value of the
lax.stdin.redirect to <blank>, as in:
lax.stdin.redirect=
2.
In the IntroscopeEnterpriseManager.properties file, ensure that the
property introscope.enterprisemanager.disableInteractiveMode is set to
true, as in:
introscope.enterprisemanager.disableInteractiveMode=true
3.
Start the Enterprise Manager with the following command:
nohup Introscope_Enterprise_Manager&
It is critical that both of the Introscope Enterprise Manager properties are set exactly as
described above. If you attempt to run the Enterprise Manager in nohup mode without
changing these properties as described, or set them incorrectly, the Enterprise Manager
may not start, or CPU utilization may become excessive.
Additional Enterprise Manager Configurations
For additional optional Enterprise Manager configurations, see Chapter 15, Optional
Introscope Configurations.
Page 64
Configuring Enterprise Manager To Run As A Windows Service
Configuring Enterprise Manager To Run As A Windows
Service
Overview
A public domain java service wrapper from wrapper.tanukisoftware.org is used with
Introscope to enable running the Introscope Enterprise Manager as a Windows Service.
Documentation on the tanuki wrapper can be found at http://
wrapper.tanukisoftware.org/doc/english/properties.html.
Installing the Enterprise Manager as a Windows Service improves its availability. An
Enterprise Manager configured as a Windows Service has the following benefits:
• the Enterprise Manager Service will start automatically on machine reboot
• if the machine containing the Enterprise Manager shuts down, the Enterprise
Manager Service will be cleanly shut down
The following instructions assume you are familiar with configuring applications as
Windows Services, and are familiar with using the Windows Services console.
System Requirements
The Enterprise Manager can be run as a Windows Service on the following platforms:
• Windows 2000 Professional
• Windows 2000 Server
• Windows Advanced Server
• Windows Datacenter Server
• Windows Server 2003 Standard Edition
• Windows Server 2003 Enterprise Edition
• Windows Server 2003 Datacenter Edition
• Windows XP Professional
Configure and Register Enterprise Manager as a Windows Service
Register Enterprise Manager as a Service
To register a single Enterprise Manager on the Windows machine running with
Introscope-default JVM system parameters, you need only run a script and perform a
small configuration.
Before you register the Enterprise Manager as a Windows Service, make sure that the
Enterprise Manager is already installed and runs properly in Console mode
To register an Enterprise Manager instance as a Windows Service:
1.
Shut down the Enterprise Manager.
2.
In the file, IntroscopeEnterpriseManager.lax make sure the following property
is blank:
lax.stdin.redirect
Page 65
Configuring Enterprise Manager To Run As A Windows Service
3.
4.
In the file, IntroscopeEnterpriseManager.properties, ensure the following
property is set to true, as shown in the example below:
5.
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 Service
There are several situations in which you would deregister the Enterprise Manager
Service:
• before making changes to the EMService.conf properties file.
• to return the Enterprise Manager instance to Console control
• before you uninstall the Enterprise Manager instance
To deregister an Enterprise Manager Service:
1.
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 Properties
If you need to change any configuration properties in the EMService.conf file, first
deregister the service. Make the changes, and then re-register the service for the
changes to take effect.
Page 66
Configuring Enterprise Manager To Run As a z/OS Batch Job
Running the Enterprise Manager as a Windows Service
Use the standard controls in the Windows Services GUI to start, stop, and restart the
Enterprise Manager running as a Windows Service.
Connecting to a Database Configured After Enterprise Manager
Service Startup
If you have configured a database after the Enterprise Manager as a Windows Service has
been started, you will need to restart the Service to be able to connect to the database.
To facilitate use of Introscope in the z/OS environment, it is desirable to run the product
in a manner familiar to z/OS operations and development staff – either as a z/OS batch
job or started task. You can also run Introscope Enterprise Manager as a shell process if
desired. This section describes running the Introscope Enterprise Manager as a batch job
or started task.
The following list contains a brief description of each section:
• Overview briefly describes the z/OS environment and the BPXBATCH utility. This
section describes software prerequisites, security, authorization and address space
size requirements.
• Installation describes the tasks necessary to customize the sample JCL and other
files in preparation for running the Introscope Enterprise Manager as a batch job
on the z/OS platform.
• Running the Introscope Enterprise Manager describes the activities required to run
the Introscope Enterprise Manager as a batch job or started task on the z/OS
platform.
• DB2 Considerations discusses some of the most important considerations for
deploying the Introscope Enterprise Manager database on DB2 for z/OS.
Overview
Prerequisites
z/OS base infrastructure for Java
The infrastructure required to run the Introscope Enterprise Manager as an MVS batch job
or started task is straightforward and easily realized. The MVS utility program,
BPXBATCH, enables users to invoke UNIX System Services to run shell commands, shell
scripts and executable files in MVS batch. Specifically, the Introscope Enterprise Manager
can be started using the BPXBATCH utility.
Software Prerequisites
The specific software prerequisites to run Java (and therefore the Introscope Enterprise
Manager) on the z/OS can be found in the Java for z/OS Program Directory GI10-0614.
The minimum software requirements are:
Page 67
• 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
Page 68
• 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.
Page 69
DASD
The Introscope Enterprise Manager DB2 database constitutes the only significant DASD
requirement. DASD space for the Introscope Enterprise Manager DB2 database is
discussed in section Customizing the tablespaces and the sample CREATE TABLE
statements, page 75.
Installation
Overview of Installation Tasks
Before the Introscope Enterprise Manager can run as a z/OS batch job, the following files
(extracted from the z/OS installer file) must be copied into the z/OS environment and
customized to ensure compatibility with site-specific requirements.
• IntroscopeEnterpriseManager.properties – the Introscope Enterprise
Manager properties file, which specifies information pertinent to the operation of
the Introscope Enterprise Manager
• runem.sh – the shell script used to launch the Introscope Enterprise Manager
process
• WILYPROC – the z/OS PROC used to execute z/OS BPXBATCH program that
launches the shell script
• readme.txt - a description of the runem.sh and WILYPROC files and how to use
and customize them
Copying and Customizing Introscope Enterprise Manager Files
IntroscopeEnterpriseManager.properties and runem.sh are UNIX files that
must be copied into the Hierarchical File System (HFS) on the z/OS platform. These files
will be used by UNIX System Services and the Introscope Enterprise Manager
respectively. Required changes to these files should be made using a UNIX-based editor
such as vi. Do not use the ISPF editor because it does not properly handle insertion of
characters that increase line length.
WILYPROC is a z/OS file that will be used by the JES2 component of z/OS and by DB2 for
z/OS. Changes to this file should be made using the ISPF editor.
Copying the Introscope Enterprise Manager UNIX files to HFS Files
Copy the IntroscopeEnterpriseManager.properties and runem.sh files into the
Introscope installation directory, as shown in the following examples, where “xxxx” is the
UID assigned to Wily Technology.
/u/xxxx/introscope6.0.1/runem.sh
/u/xxxx/introscope6.0.1/config/
IntroscopeEnterpriseManager.properties
Customizing the Introscope Enterprise Manager Properties File
1.
Open the u/xxxx/introscope6.0.1/config/
IntroscopeEnterpriseManager.properties file.
Page 70
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.
Page 71
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 sitedependent high level qualifier. If WILYPROC is not an acceptable name in your
installation, rename the PROC accordingly.
Running the Introscope Enterprise Manager
Executing the z/OS PROC
Running as a Started Task from the z/OS Console or SDSF
You may run the Introscope Enterprise Manager as an MVS started task (STC). A started
task is a familiar, operator-friendly environment that allows the Introscope Enterprise
Manager to be started, monitored and cancelled from the MVS console. In this case, the
Introscope Enterprise Manager runs under the authorization of the STC user ID, thereby
allowing assignment of specific authorities to the started task.
Page 72
♦
To run the Introscope Enterprise Manager as a started task, type the following
command on the MVS console or on the command line of SDSF:
/start WILYPROC
You must type the member name of the PROC stored in an active PROCLIB. If you
were required to change the name of WILYPROC, you must use the new name in the
/start command.
Running as a Batch Job
The Introscope Enterprise Manager can also run as a batch job.
♦
To run the Introscope Enterprise Manager as a batch job, submit the following JCL:
//jobname
ISCOPE
JOB
EXEC
installation jobcard parameters,NOTIFY=&SYSUID
WILYPROC
/*
You must execute the member name of the PROC stored in an active PROCLIB. If you
were required to change the name WILYPROC, you must use the new name on the
EXEC statement.
The z/OS batch job and the OMVS Shell will end shortly after the Introscope Enterprise
Manager processes have started. If you submitted the batch JCL from your ISPF session
and your JOB card contains NOTIFY=&SYSUID, your ISPF session will receive notification
when your batch jobs ends.
Verifying That the Introscope Enterprise Manager Is Running
The most accurate way to determine that the Introscope Enterprise Manager has started
correctly is to view the STDOUT file. To view STDOUT, you must telnet into the z/OS and
view the STDOUT file defined in the WILYPROC. The last line of the file should indicate
that the Introscope Enterprise Manager has started.
You can also determine that the Introscope Enterprise Manager has started from SDSF by
following one of the procedures below:
• If you started the Introscope Enterprise Manager as a started task, on the DA
screen you should see at least two active started tasks whose owner is the owner
associated with the Introscope Enterprise Manager PROC.
• If you started the Introscope Enterprise Manager by submitting a batch job from
your TSO session, look for two active tasks with your TSO USERID as the owner.
You may also see the job that invoked the WILYPROC as well as the OMVS shell script.
These two entries will disappear from the list, once the Introscope Enterprise Manager
has started.
The owner of your TSO session is also your TSO/E USERID. Do not mistake your TSO/E
session for one of the Introscope Enterprise Manager tasks.
Page 73
Starting the Introscope Enterprise Manager automatically
To can start the Introscope Enterprise Manager automatically when JES2 starts:
1.
Place the following statement in JES2PARM:
$VS,’start WILYPROC
2.
You must type the member name of the PROC stored in an active PROCLIB. If you
were required to change the name of WILYPROC, you must use the new name in the
/start command.
You can also run the Introscope Enterprise Manager as a batch job using whatever job
scheduling package you use to manage your batch workload.
DB2 Considerations
DB2 for z/OS provides many installation parameters and customization options that are
designed to leverage the reliability, availability and serviceability of the z/OS platform as
well as the special features of DB2. Users of DB2 for z/OS generally augment these
parameters and options with site-specific standards, naming conventions, operator
procedures and OEM products. For this reason, the assumptions and suggestions
contained in this document and the db2_zOS.sql obtained from Wily Technology should
be thoroughly and carefully reviewed prior to installation of the Introscope Enterprise
Manager.
Assumptions
Table Usage
The database contains 14 tables and one view. There is a single unique index defined on
each table.
The following tables are small, non-volatile, code tables:
• WT_PROPERTY
• WT_AGENT
• WT_RESOURCE
• WT_RESOURCE_METRIC
• WT_METRIC_NAME
• WT_RECORD_TYPE
• WT_VERSIONLIST
•
WT_INDEX
•
WT_METADATA
•
WT_TMP_Q_1
•
WT_TMP_Q_2
•
WT_TMP_Q_3
•
WT_TMP_Q_4
Page 74
•
WT_TMP_Q_5
Currently, the DDL for these tables takes all defaults except for “IN database”.
WT_METRIC
The WT_Metric table is the largest table in the Introscope Enterprise Manager database
and the most heavily used. The implementation of the Introscope Enterprise Manager
described below represents the anticipated upper bound for number of agents deployed
and number of Metrics collected. Consequently, this implementation represents the
anticipated upper bound for the size of the WT_Metric table.
Environment
The Introscope Enterprise Manager is the primary means of accessing the WT_Metric
table. Only rarely will SQL queries be executed against the WT_Metric table outside of the
Introscope Enterprise Manager application.
Database Implementation Considerations
Sample database creation script is based on the assumptions listed above, particularly
the assumptions related to the WT_Metric table. Review these assumptions carefully. If
your environment will be substantially different, you should reevaluate associated
database creation script parameters.
Customizing the db2_zOS.sql File
Using the ISPF editor, customize the database creation script provided in db2_zOS.sql.
Customizing the tablespaces and the sample CREATE TABLE statements
When customizing the tablespaces, follow these rules:
• The WT_Metric table data should have its own segmented tablespace.
• The WT_Metric_U1 index should also have its own dedicated tablespace.
• The WT_Metric table and its index should be placed on high-speed devices. The
physical path to the data should be on a different path from the physical path to
the index.
These tablespaces may be defined as either DB2 managed or user managed.
Tables and indexes
All tables and indexes should be defined in the Wily database – not the default database.
All tables should be assigned to a specific storage group or tablespace. All CREATE INDEX
statements should contain a “USING” clause designating either a specific storage group
or VCAT.
Page 75
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 Domains
A Domain in Introscope is a partition of Agents and monitoring logic. Agents are mapped
to a Domain using a Perl5 regular expression in the domains.xml file.
Domain Types
There are two types of Domains in Introscope:
• SuperDomain
• User-defined Domain
SuperDomain
The SuperDomain is the “superset” Domain that contains all user-defined Domains in the
system, and holds any Agents which are not specifically mapped to a Domain.
In the default configuration shipped with Introscope, there is only one Domain: the
SuperDomain. If no other Domains are configured by a user, all Agents will be mapped to
the SuperDomain.
Page 76
User-defined Domains
New Domains are defined in the <Introscope home>/config/domains.xml file. The
file provides mappings of Domain names to regular expressions.
Creating Domains
If Domains are added/removed/edited, the changes will not be recognized until the
Enterprise Manager is restarted.
Domain Attributes and Syntax
The following table contains the attributes for defining a Domain:
TABLE 7. Domain Attributes
Modifier
value
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|Age
nt) 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
Rules
Users are granted permissions per Domain.
Domain permissions are discussed in Defining
User Permissions, page 88.
Here is the Domain syntax:
<domain name=”Domainname” description=”Domain description”>
<agent mapping=”host\|process\|agentname or matching agents”/>
<grant user=“username” permission=”permission”/>
</domain>
Domain Creation Rules
Please note the following rules about creating Domains in the domains.xml file:
• Domain creation must follow valid xml file rules
• Domain names are case sensitive
• any Domain must be placed inside the root XML domains element
Page 77
• 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 Domains
When you create new Management Modules, you can choose which Domains will contain
them.
You associate Management Modules with Domains by creating directories that correspond
to the names of the Domains you defined in domains.xml, then moving the
Management Modules into the new directories.
1.
In <Introscope home>/config/modules, create a directory that corresponds to
the Domain name you created in the previous section. For example, if you created a
Domain named “PetstoreA,” in this step, you would create a directory also named
PetstoreA, as in the following example:
<Introscope home>/config/modules/PetstoreA
Note: The Domain directory must match the name defined in the domains.xml file
exactly (spelled correctly and also matching in case) or any Management
Modules that reside in the directory will not be loaded.
Page 78
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 Domain
You may need to delete a Domain when you:
• assign an Agent to a different Domain
• merge two Domains
To delete a Domain and disconnect its associations:
1.
2.
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.
Page 79
5.
Merging Two Domains
Merging two Domains involves merging all Agent mapping information into one Domain,
and moving any associated Management Modules under one Domain.
To merge two Domains:
1.
2.
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.
8.
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.
4.
Moving a Domain Between Non-cloned Installations
If the Domain configurations between the old and new installations vary slightly, use the
following steps:
Page 80
Configuring User Authentication
1.
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.
8.
Introscope offers an extensible authentication system that can integrate with existing
systems through LDAP. If you do not use an external authentication mechanism,
authentication is configured locally by referencing the users stored in the users.xml file.
• to use local authentication, follow the instructions in this section, then proceed to
Defining User Permissions, page 88, to define permissions for each user.
• If you will be using an external authentication mechanism, you can skip this
section and use the instructions in Configuring External Authentication, page 84.
Local User Authentication Overview
Local authentication is used by default in Introscope. The authentication method used is
configured in the IntroscopeEnterpriseManager.properties file. If local
authentication is used, the Enterprise Manager references a local authentication
properties configuration file, which then refers to users.xml where users and passwords
are stored.
Local authentication changes are dynamic: when a user attempts to log in, login values
are compared to users.xml file each time an authentication request is made. Changes
to the contents of the users.xml file do not require an Enterprise Manager restart.
Introscope provides an optional mechanism for encoding passwords for use in local
authentication.
There are several steps involved in setting up local authentication:
• making sure Introscope is configured to use local authentication
• changing the location of the users.xml file if desired
• defining users in the users.xml file
• generating encoded passwords (optional)
Page 81
Configuring Local Authentication
Configuring Enterprise Manager to Use Local Authentication
Introscope uses local authentication by default. To check that local authentication is
used:
1.
IntroscopeEnterpriseManager.properties.
2.
3.
Locate the Authentication Providers section.
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.
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
Modifier
value
name
username
Rules
•
alphanumeric characters only, and _ and -
Page 82
Modifier
value
password
user password
Rules
•
•
•
•
any characters except quotation marks
by default, passwords are in clear-text and are
not encrypted or obfuscated (can optionally
generate encoded passwords)
password characters can be legal xml
characters
a password value can be empty
Here is the syntax for configuring a user:
<users>
<user name="username" password="password">
</user>
</users>
Defining a User
To define a user:
1.
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
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">
Page 83
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.
If you already have a system to authenticate user logins, Introscope can interface with
that system through LDAP.
By default, Introscope uses local authentication through the users.xml file. However, an
LDAP extension is also provided, and can be used instead of local authentication, once
the extension is configured for use with a specified LDAP server.
Configuring LDAP Authentication
Introscope’s LDAP authentication works with the following supported v3 LDAP servers:
Page 84
• 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.
2.
3.
4.
Locate the Authentication Providers section.
For the property,
introscope.enterprisemanager.authentication.providers, specify that
LDAP will be used as the authentication provider, as in the following example:
introscope.enterprisemanager.authentication.providers=ldap
5.
Check that the following LDAP configuration properties are present and
uncommented:
introscope.enterprisemanager.authentication.extensionName.ldap=WilyLDAP
introscope.enterprisemanager.authentication.controlFlag.ldap=REQUIRE
D
introscope.enterprisemanager.authentication.configFile.ldap=config/
LDAPAuthenticationExtension.properties
6.
Save changes to this file, and restart the Enterprise Manager.
Configuring LDAP Authentication Extension
Every site's LDAP server is configured uniquely, so you must obtain LDAP configuration
information from the site's LDAP administrator before attempting to configure the
following LDAP properties.
LDAP properties are configured the file, <Introscope home>/config/
LDAPAuthenticationExtension.properties.
Note: If there are any syntax or other errors in the
LDAPAuthenticationExtension.properties file, the Enterprise Manager will
not start.
The following table describes the properties in this file:
Page 85
This Setting
Specifies
Default Setting
authentication.extension.ldap.url=
URL for the remote LDAP server
ldap://host:port
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.
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.
IntroscopeLDAPUse
r
authentication.extension.ldap.bindPasswo
rd
Password used to bind to LDAP
server. If anonymous bind is used,
this property is ignored.
password123
authentication.extension.ldap.bindAuthen
tication
Authentication type to use when
binding.
simple
Options are: none, simple, CRAMMD5.
authentication.extension.ldap.user.nameS
uffix
Suffix to append to Introscope user
name for use with LDAP queries.
@dev.com
authentication.extension.ldap.user.baseD
N
Base distinguished name (DN) for all
user object queries
cn=Users, dc=dev,
dc=com
authentication.extension.ldap.user.scope
Depth
Search depth when querying for a
user object
subtree
authentication.extension.ldap.user.userna
meAttribute
Name of LDAP attribute that will
match an Introscope username
userPrincipalName
authentication.extension.ldap.user.userO
bjectQuery
LDAP search filter used to query a
user object. The token “%u” will be
filled in with the Introscope
username before the query
executes.
(&(userPrincipalNa
me=%u)(objectclas
s=user))
authentication.extension.ldap.serverCertif
icate
Name of certificate file. Supported
certificate types are of type X.509,
and base64-encoded.
blank
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).
Page 86
LDAP Configuration Examples
The following section contains examples of LDAP configurations on each of the supported
LDAP Servers. Please note that the following code samples are provided for example
only; every site's LDAP server is configured uniquely.
IBM Directory Server
The following example shows LDAP properties configured for use with the IBM Directory
Server, using SSL.
authentication.extension.ldap.url=ldaps://jonesey.acme.com:636
authentication.extension.ldap.useSSL=true
authentication.extension.ldap.bindName=
authentication.extension.ldap.bindPassword=
authentication.extension.ldap.bindAuthentication=simple
authentication.extension.ldap.user.nameSuffix=
authentication.extension.ldap.user.baseDN=ou=fjones,cn=users,dc=acme
,dc=com
authentication.extension.ldap.user.scopeDepth=subtree
authentication.extension.ldap.user.usernameAttribute=uid
authentication.extension.ldap.user.userObjectQuery=(&(uid=%u)(object
class=person))
authentication.extension.ldap.serverCertificate=config/spock2.cer
SunONE Directory Server
The following example shows LDAP properties configured for use with the Sun ONE
Directory Server, using SSL.
authentication.extension.ldap.url=ldaps://jonesey.acme.com:636
authentication.extension.ldap.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)(object
class=user))
authentication.extension.ldap.serverCertificate=config/
acmebase64.cer
MS Active Directory
Page 87
Defining User Permissions
The following example shows LDAP properties configured for use with MS Active
Directory, using SSL.
authentication.extension.ldap.url=ldaps://173.92.10.15:636
authentication.extension.ldap.user.nameSuffix=@dev.com
authentication.extension.ldap.user.baseDN=cn=Users,dc=dev,dc=com
authentication.extension.ldap.user.usernameAttribute=cn
authentication.extension.ldap.user.userObjectQuery=(&(cn=%u)(objectc
lass=user))
authentication.extension.ldap.serverCertificate=config/sulu5.cer
Setting up user permissions allows you to define greater deployment security by:
• defining user permissions within a specific Domain
• defining user permissions for the Enterprise Manager
User permissions determine what tasks the user can perform including configuring
monitoring logic in the Workstation, or Enterprise Manager administration tasks.
Permissions in Introscope are defined for Domains and the Enterprise Manager. Users can
be granted permissions to either or both.
• Domain permissions are configured in <Introscope home>/config/
domains.xml
• Enterprise Manager permissions are configured in <Introscope home>/
config/server.xml
Permissions Rules
Permissions for a user are “fixed” when a user logs in; if changes are made for that user
while they are logged in, they will not be recognized until the next time that user
attempts to log in. This means that a user will not be “booted off” if their permissions are
removed while they are logged in.
Introscope permissions are dynamic; the domains.xml and server.xml files are
checked whenever a user attempts to log in. Thus, permissions changes can be made
without restarting the Enterprise Manager.
Domain Permissions
Domain Access Rules
• the SuperDomain is treated just like any other Domain in terms of permissions
Page 88
• Any permissions granted to a user with access to the SuperDomain will also allow
them to use these privileges in all user-defined Domains.
• one user can have multiple permissions for a single Domain
• one user can have permissions in multiple Domains
• if a user has multiple permissions, use one line for each user/permission pair
Domain Permissions Defined
The following table defines the Domain permissions available for users in a Domain.
TABLE 9. Domain Permissions
Permission
read
Definition
User can view all Agents and business logic in Domain.
This includes tasks such as:
•
Viewing Explorer tree (which will show Agents and
Management Modules in the Domain user has access to)
• Viewing Dashboards in the Console
• Viewing Metric and Element data in the Explorer Preview
pane, including default Top N Filtered Views for certain
Resources in the Explorer tree
• Viewing any Management Module, Agent or Element
settings
• Viewing Alert messages
• Refreshing historical data in a historical Data Viewer, and
zoom in and out
• Changing historical date range options for historical Data
Viewer
• Showing/Hiding Metrics in a Graph
• Moving Metrics in a Data Viewer to the back or front
• Changing User Preferences (setting a home Dashboard,
displaying Management Module names with Dashboard
names)
Note: Users with read permission will be able to see all
commands in the Workstation, but the commands they do not
have access to will be disabled.
write
A user with write permission can do everything a user with
read permission can, but can also:
•
•
•
run_tracer
view all Agents and business logic in Domain
create and edit Dashboards
edit all monitoring logic in a Domain
User can start a Transaction Trace Session for an Agent.
Note: This permission also requires a user to have read
permission.
historical_agent_control
User can mount and unmount Agent(s).
permission.
Page 89
Permission
Definition
live_agent_control
User can shut off reporting for Metrics, Resources, and Agent
within Domain
permission.
full
User has all possible permissions for Domain.
Here is the syntax for configuring user permissions for a Domain:
<grant user="username" permission="permission">
Defining Domain Permissions
To define Domain permissions for a user:
1.
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
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">
Page 90
<domain name="HRApplication" description="">
<agent mapping="(.*)HRAppAgent(.*)" />
<grant user="bsmith" permission="full" />
<grant user="fjones" permission="read" />
<grant user="fjones" permission="run_tracer" />
</domain>
<SuperDomain>
<agent mapping="(.*)"/>
<grant user="jlo" permission="write"/>
<grant user="pdiddy" permission="read"/>
</SuperDomain>
</domains>
Domain Permissions and the Explorer Tree
The Explorer tree will look different to users with different Domain permissions:
• User with SuperDomain permission (at least read permission) can view the
contents of all defined Domains in the Explorer tree.
• Users with permissions for multiple Domains will see Domain information for those
Domains in the Explorer tree.
• Users with permissions for only one Domain will not see Domain information in the
Explorer tree, they will only see the folders for “Metrics” and “Management
Modules.”
Server Permissions
Server permissions are defined for activities relating to operation of the Enterprise
Manager:
• shutting down the Enterprise Manager
• purging non-reporting Metrics
• publishing MIB files
Server Permissions Rules
• a user can have multiple permissions for the Enterprise Manager
• if a user has multiple permissions, use one line for each user/permission pair
Page 91
Server Permissions Defined
The following table defines the server permissions available.
TABLE 10. Server Permissions
Permission
Definition
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.
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
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">
Page 92
<grant user="bsmith" permission="shutdown" />
<grant user="tjones" permission="purge_metrics" />
<grant user="tjones" permission="publish_mib" />
</server>
Agent Failover and Domain/User Configuration
If you want to take advantage of the Agent Failover functionality and have users and
passwords defined, you must make sure that the information in the domains.xml,
server.xml and users.xml files is in sync across the specified failover Enterprise
Managers.
Note: For more information on Agent Failover, see Agent Failover, page 173.
Page 93
6 Configuring Java Applications With Introscope
After you have installed the Enterprise Manager and Workstation, you are ready to install
and configure the Introscope Agent and Introscope-enable your Java Applications.
Use the table below to direct you to the appropriate chapter for your deployment.
Each of the following chapters contains instructions for:
• Installing Introscope Agent
• Choosing a ProbeBuilder configuration option
• Configuring Basic Agent Settings
If you are using this
Application Server
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
Page 94
7 Configuring WebLogic Server With Introscope
This section describes how to configure (Introscope-enable) Java Applications with
WebLogic Server in the following sections:
• Configuring Introscope With WebLogic Overview
• Installing Introscope Agent With WebLogic
• ProbeBuilder Configuration Options
• Configuring Basic Agent Settings for WebLogic
• Additional Configuration Options
Configuring Introscope With WebLogic Overview
There are three main steps required to install and configure the Introscope Agent to
report information to the Enterprise Manager:
• install the Introscope Agent
• Introscope-enable the application code using one of the ProbeBuilder configuration
options
• configure basic Introscope Agent settings
Installing Introscope Agent With WebLogic
To install the Introscope Agent on WebLogic:
1.
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
Page 95
ProbeBuilder Configuration Options
• Several .pbd and .pbl files (ProbeBuilder Directives and List files)
A Java application is monitored by adding Probes to the bytecode. The Probes then report
information to the Introscope Agent, and the Agent reports that information to the
Enterprise Manager. The tool used to add Probes is called ProbeBuilder.
There are three ProbeBuilder configuration options that can be used to install probes into
the application to be monitored:
• JVM AutoProbe
Using the JVM AutoProbe option dynamically Introscope-enables all classes loaded
by the JVM.
• Application Server AutoProbe
Using the Application Server AutoProbe option dynamically Introscope-enables all
applications loaded by the application server.
• Manual ProbeBuilder (using either the ProbeBuilder Wizard or Command-Line
Probebuilder)
The Manual ProbeBuilder option is a manual process which Introscope-enables
classes on disk before the application server is run.
Availability of these options will differ depending on the WebLogic application server
version.
The JVM AutoProbe and Application Server AutoProbe options install probes dynamically
into application code as it is loaded. Whenever possible, using ProbeBuilder through
AutoProbe will save time and provide ease of use that Introscope-enabling an application
manually does not.
Choosing ProbeBuilder Configuration Option
The following table details the ProbeBuilder options available for each WebLogic Server
version and JVM combination. To find the appropriate ProbeBuilder method:
1.
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
Page 96
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
5.0 JVM
JVM AutoProbe Using Java 5.0 JVM, page 99
JRockit
JVM AutoProbe With WebLogic Using WebLogic
JRockit, page 100
Sun
JVM AutoProbe With WebLogic Using Sun or IBM
JVM, page 99
IBM
JVM, page 99
HP
JVM AutoProbe With WebLogic Using HP HotSpot
JVM, page 100
JRockit
JRockit, page 100
WebLogic 9.0
JVM AutoProbe
WebLogic 8.1
JVM AutoProbe
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
Sun
JVM, page 99
IBM
JVM, page 99
HP
JVM, page 100
WebLogic 7.0
JVM AutoProbe
Page 97
JRockit
JRockit, page 100
any
page 101
Manual ProbeBuilder
any
Sun
JVM, page 99
IBM
JVM, page 99
HP
JVM, page 100
WebLogic 6.1SP3
JVM AutoProbe
any
Application Server AutoProbe With WebLogic 6.1
SP3, page 101
Manual ProbeBuilder
any
Sun
JVM, page 99
IBM
JVM, page 99
HP
JVM, page 100
WebLogic 6.1
JVM AutoProbe
any
page 102
Manual ProbeBuilder
any
Page 98
JVM AutoProbe Using Java 5.0 JVM
The following instructions work Java 5.0 JVM:
1.
Add the following command-line option to the JVM command line:
-javaagent:<path-to-Agent.jar>
2.
Proceed to the section, Configuring Basic Agent Settings for WebLogic, page 102 to
configure the Agent profile.
JVM AutoProbe With WebLogic Using Sun or IBM JVM
There are two steps required to configure and use JVM AutoProbe with Sun or IBM JVM:
• create an AutoProbe connector that will work with your JVM
• run the AutoProbe Connector by modifying the classpath with the location of the
AutoProbe connector, Agent, and ProbeBuilder
The following section details how to configure JVM AutoProbe.
Note: This method will not work with WebLogic 9.0. Use the method described in the
section, JVM AutoProbe Using Java 5.0 JVM, page 99.
Creating an AutoProbe Connector
Use the CreateAutoProbeConnector.jar tool to create a connector specific to the
JVM used to run WebLogic. There are two ways to specify the JVM:
• use the JVM that is running the tool
• pass the JVM directory on the command line to the tool
1.
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:
Page 99
• all JVMs but IBM JVM 1.2.x:
-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>:<path-toAgent.jar>
-Xbootclasspath/p:wily/connectors/
AutoProbeConnector.jar:<path-to-Agent.jar>
• for IBM JVM 1.2.x
-Xbootclasspath:wily/connectors/
AutoProbeConnector.jar:<jvm_home>/lib/rt.jar:<jvm_home>/lib/
i18n.jar:<path-to-Agent.jar>
Note: If you are using something other than the default bootstrap classpath, add
the Agent.jar and AutoProbeConnector.jar files to the beginning of
your customized bootstrap classpath.
2.
JVM AutoProbe With WebLogic Using HP HotSpot JVM
The 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>
3.
JVM AutoProbe With WebLogic Using WebLogic JRockit
The following instructions work with WebLogic JRockit:
1.
Start WebLogic JRockit with the following command line options:
• For WebLogic 9.0 with JRockit 5.0:
JAVA_VENDOR=Bea
JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:<path-to-Agent.jar>
• For WebLogic JRockit 8.1:
-Xmanagement:class=com.wily.introscope.api.jrockit.
AutoProbeLoader
Note: The above command should be all on one line.
Page 100
• For WebLogic JRockit 7.0:
-Djrockit.preprocessor.class=
com.wily.introscope.api.weblogic.PreProcessor
2.
Application Server AutoProbe With WebLogic
The following sections describe how to configure your deployment to use Application
Server AutoProbe.
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=
3.
Proceed to the section, Configuring HTTP Servlet Tracing For Application Server
AutoProbe, page 102.
1.
2.
Edit the Java classpath in the WebLogic Server startup script (startWLS.cmd) to
include the wily/Agent.jar file.
Set the following property on the Java command line (in the same startup script
startWLS.cmd) with the -D option. This will activate Introscope AutoProbe:
3.
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:
Page 101
3.
1.
Edit the Java classpath in the WebLogic startup script to include the wily/
Agent.jar file.
2.
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
6.
The following section details how to configure the Introscope Agent. The Agent settings
are found in the file, wily/IntroscopeAgent.profile. This guide will refer to the
IntroscopeAgent.profile file as the Agent profile.
Agent Profile Location
Introscope looks for the Agent profile in a set sequence of three locations:
• the location defined in the system property,
com.wily.introscope.agentProfile
Page 102
• 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:
• Make the Agent profile (IntroscopeAgent.profile) available in a resource on
the classpath. Set com.wily.introscope.agentResource to specify the path
to the Resource containing the Agent profile.
Note: If you use this option, AutoProbe will not be able to write to
AutoProbe.log. See AutoProbe ProbeBuilder Log, page 201.
Moving IntroscopeAgent.profile and Directives Files Together
You can rename and/or move the IntroscopeAgent.profile file to another directory,
such as the application directory. However, if you move the IntroscopeAgent.profile
to another location, you should also move the directives files (.pbd and .pbl files), as they
are referenced relative to the location of the Agent profile.
Configuring Introscope Agent
Basic Agent properties you need to set are:
• Enterprise Manager host and port
• Agent Name
• Process Name
Agent Naming
The standard method to name an Agent is to define its name in the property,
introscope.agent.agentName, in the IntroscopeAgent.profile. Use this method
if you have one Agent profile for each Agent already set up. You may also use automatic
Agent Naming, which is enabled by default for WebLogic.
To fully configure WebLogic to use automatic Agent naming, see Additional Configuration
Options, page 104, and for more information on automatic Agent naming, see Agent
Naming Options, page 169.
Page 103
Additional Configuration Options
Property
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.por
t.agentlistener in the
introscopeEnterpriseManager.prop
erties file for each matching Enterprise
Manager. See Uninstalling Introscope,
page 54.
line.
Note: The “DEFAULT” segment of the two settings above is used in configuring Agent Failover.
For information on Agent Failover, see Agent Failover, page 173.
introscope.agent.agentName
Enter a name for the application server the
Agent is monitoring.
The Agent Name value MUST start with an
alphabetical character, and cannot contain a
“%” character.
introscope.agent.customProcessName
Enter name for process being monitored.
There are several additional WebLogic configuration options. You can configure
Introscope to extract WebLogic performance data through the JMX management
interface, or configure the Agent to find its name automatically from the WebLogic
application server instance. Introscope can also collect WLDF data from a WebLogic 9.0
application server. However, all of these options require a WebLogic startup class to be
configured.
Use the following instructions to configure the startup class, then view the information in
the references in the next section to configure optional features that provide additional
performance data. Note that only one startup class is necessary to provide access to JMX
and AutoNaming capabilities.
Page 104
Creating a WebLogic Startup Class
The following section describes how to create a startup class in WebLogic 8.1. Consult
your WebLogic documentation for instructions on creating a startup class in other
versions, or for more information.
Configuring a Startup Class In WebLogic 8.1
1.
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 Configurations
See the following sections for information on optional WebLogic configurations.
• Agent Naming Options, page 169
• JMX Filters For Obtaining Advanced Performance Data, page 182
For general Introscope additional configuration options, see, Chapter 15, Optional
Page 105
8 Configuring WebSphere Application Server With
Introscope
This section describes how to configure (Introscope-enable) a Java Application in the
following sections:
• Configuring Introscope With WebSphere Overview
• Installing Introscope Agent on WebSphere
• Configuring Basic Agent Settings on WebSphere
Configuring Introscope With WebSphere Overview
options
Installing Introscope Agent on WebSphere
To 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
3.
• Agent.jar
Page 106
• JVM AutoProbe
by the JVM.
Probebuilder)
manually does not.
The following table details the ProbeBuilder options available for each WebSphere
Application Server version and JVM combination. To find the appropriate ProbeBuilder
method:
1.
Choose the row containing your WebSphere Application Server version.
2.
3.
— WebSphere Application Server version 5.0
— JVM AutoProbe
— IBM JVM
you would use the instructions in the section, JVM AutoProbe With WebSphere Using
Sun or IBM JVM, page 108.
Page 107
Application
Server Version
ProbeBuilder
Configuration
Option
JVM
Use the Instructions In This
Section
WebSphere
6.0/5.1/5.0
JVM AutoProbe
Sun
JVM AutoProbe With WebSphere Using Sun
or IBM JVM, page 108
IBM
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
any
Chapter 14, Configuring the Java
Applications Manually With ProbeBuilder
Sun
IBM
HP
JVM AutoProbe With WebSphere Using HP
HotSpot JVM, page 110
WebSphere 4.0
JVM AutoProbe
any
WebSphere 4.0 (Distributed), page 112
Manual ProbeBuilder
any
JVM AutoProbe With WebSphere Using Sun or IBM JVM
Page 108
JVM used to run WebSphere. There are two ways to specify the JVM:
1.
2.
3.
Running the AutoProbe Connector
classpath.
JVM AutoProbe With WebSphere Version 6.0/5.1/5.0
The following instructions work with WebSphere 6.0, 5.1 or 5.0:
1.
In WebSphere, start the 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:
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:<pathto-Agent.jar>
3.
Click OK.
4.
Apply the changes in the Administrator’s Console.
5.
Restart the Web Application Server.
Page 109
6.
Proceed to the section, Configuring Basic Agent Settings on WebSphere, page 113 to
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>
4.
5.
6.
JVM AutoProbe With WebSphere Using HP HotSpot JVM
The following instructions work with HP HotSpot JVM:
Page 110
1.
2.
3.
Application Server AutoProbe With WebSphere
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.
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
Note: Although the examples above break across lines, make sure that your
argument does not have any breaks.
4.
Page 111
5.
6.
♦
lines:
//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.
2.
section for the application server you want to modify.
3.
Add the following two system properties:
Page 112
Name: com.ibm.websphere.classloader.plugin
Value: com.wily.introscope.api.websphere.WASAutoProbe
Name: com.wily.introscope.agentProfile
Value: <path-to-IntroscopeAgent.profile>
4.
5.
6.
be collected.
1.
Locate <WebSphere home>/wily/toggles-full.pbd.
2.
3.
4.
5.
Repeat steps 2-4 for <WebSphere home>/wily/toggles-typical.pbd
6.
The following section details how to configure the Introscope Agent. The Agent
configuration settings are found in the file, <WebSphere home>/wily/
IntroscopeAgent.profile. This guide will refer to the IntroscopeAgent.profile
file as the Agent profile.
Page 113
• 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
<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:
Note: If you use this option, AutoProbe will not be able to write to AutoProbe.log.
See AutoProbe ProbeBuilder Log, page 201.
• Agent Name
• Process Name
Agent Naming
if you have one Agent profile for each Agent already set up. You may also use automatic
Agent Naming, which is enabled by default for WebSphere 5.0 and higher.
To fully configure WebSphere to use automatic Agent naming, see Additional
Configuration Options, page 115. For more information on automatic Agent naming, see
Agent Naming Options, page 169.
Note: Automatic Agent Naming is enabled by default but not supported on WebSphere
4.0. If you are using WebSphere 4.0.x, disable this feature using the instructions in
the next section.
Page 114
Disabling Automatic Agent Naming for WebSphere 4.0
Agent automatic naming is enabled by default for all WebSphere platforms, but is not
supported in WebSphere 4.0.
To disable Automatic Agent Naming:
1.
Open the Agent profile, usually IntroscopeAgent.profile.
2.
Set the value of the property, introscope.agent.agentAutoNamingEnabled,
to false.
Property
introscope.agent.enterprisemanager.t
ransport.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.t
ransport.tcp.port.DEFAULT
The value should be the port on which the Enterprise
Manager listens for Agent connections.
The port specified in this setting must match the port
defined in the setting,
introscope.enterprisemanager.port.agentlistene
r in the introscopeEnterpriseManager.properties
file for each matching Enterprise Manager. See
Uninstalling Introscope, page 54.
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.
There are several additional WebSphere configuration options. You can configure
Introscope to extract WebSphere performance data through the JMX and PMI
management interfaces, or configure the Agent to find its name automatically from the
WebSphere application server instance. However, both of these options require a
WebSphere custom service to be configured. Note that only one custom service is
necessary to provide access to JMX, PMI and AutoNaming capabilities.
Use the following instructions to configure the custom service, then view the information
in the references in the next section to configure optional features that provide additional
performance data.
Page 115
Configuring a Custom Service in WebSphere
The following section describes how to create a custom service in WebSphere 5.0.
Consult your WebSphere documentation for instructions on creating a custom service in
previous versions, or for more information.
Configuring a Custom Service in WebSphere 6.0/5.0
1.
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.
8.
Restart the application server.
Optional WebSphere Configurations
See the following sections for information on optional WebSphere configurations.
• Advanced WebSphere Performance Data, page 189
Page 116
9 Configuring WebSphere on z/OS With Introscope
This chapter describes how to configure Introscope 6.0.1 for use with WebSphere version
5.0, 5.1 or 6.0 on the z/OS platform. It assumes that you are thoroughly familiar with
configuration of WebSphere on z/OS.
• Installing Introscope Agent on WebSphere on z/OS
• Configuring HTTP Servlet Tracing For Application Server AutoProbe
Configuring Introscope With WebSphere on z/OS Overview
options
You may also choose to configure to run your Enterprise Manager as a z/OS batch job.
Installing Introscope Agent on WebSphere on z/OS
To install the Introscope Agent on WebSphere on z/OS:
1.
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
3.
• Agent.jar
Page 117
• JVM AutoProbe
by the JVM.
Probebuilder)
manually does not.
The following table details the ProbeBuilder options available for each WebSphere
method:
1.
Choose the row containing your WebSphere Application Server version.
2.
3.
— WebSphere Application Server version 5.0 on z/OS
— JVM AutoProbe
— IBM JVM
you would use the instructions in the section, JVM AutoProbe With WebSphere Using
IBM JVM, page 119.
Page 118
Application
Server Version
ProbeBuilder
Configuration
Option
JVM
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
any
JVM AutoProbe With WebSphere Using IBM JVM
There are two steps required to configure and use JVM AutoProbe with IBM JVM:
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
Page 119
To create the AutoProbe connector:
1.
2.
3.
classpath.
JVM AutoProbe With WebSphere 5.x and 6.0 for z/OS
The following instructions work with WebSphere 5.x and 6.0 for z/OS:
1.
2.
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
6.
Page 120
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
♦
lines:
};
grant {
};
Application Server AutoProbe With WebSphere for z/OS
This section contains instructions specifically for configuring Application Server AutoProbe
for WebSphere on z/OS.
Page 121
Application Server AutoProbe With WebSphere 5.x and 6.0 for z/OS
The following instructions work with WebSphere 5.0.x on z/OS:
1.
2.
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
OR
-Dcom.wily.introscope.agentResource=<path to Resource containing
Note: Although the examples above breaks across lines, make sure that your
argument does not have any breaks.
5.
Place the Agent.jar file in the <WebSphere Instance dir>/lib/ext directory.
Note: Do not place the Agent.jar file in the WebSphere installation directory.
The following shows examples of the wrong and right directory:
NO: /usr/lpp/zWebSphere/V5R0M0/lib/ext
YES: /WebSphere/V5R0M0/AppServer/lib/ext
6.
The default for file encoding for WebSphere 5.x and 6.0 on z/OS is now ASCII, but
Introscope expects EBCDIC file format. Click on Custom Properties and add the
name value pair:
name: com.wily.introscope.default.encoding
value: Cp1047
Page 122
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.
10. Proceed to the section, Configuring HTTP Servlet Tracing For Application Server
♦
lines:
};
grant {
};
Page 123
Configuring Basic Agent Settings for WebSphere
be collected.
1.
Locate <WebSphere home>/wily/toggles-full.pbd.
2.
3.
4.
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
The following section details how to configure the Introscope Agent. Agent configuration
settings are found in the file, IntroscopeAgent.profile, located in the <working
directory>/wily directory. You will need to do this for each managed instance of
WebSphere:
• Agent Name
• Process Name
Agent Naming
if you have one Agent profile for each Agent already set up. Introscope also provides
additional methods for the Agent to find its name automatically. Automatic Agent Naming
is enabled by default for WebSphere 5.0 and higher.
To fully configure WebSphere to use automatic Agent naming, see Additional
Configuration Options, page 126, and for more information on automatic Agent naming,
see Agent Naming Options, page 169.
Note: Automatic Agent Naming is enabled by default but not supported on WebSphere
4.0. If you are using WebSphere 4.0.x, disable this feature using the instructions in
the next section.
Page 124
Disabling Automatic Agent Naming for WebSphere 5.x and 6.0 for z/OS
To disable Automatic Agent Naming:
1.
2.
Set the value of the property, introscope.agent.agentAutoNamingEnabled,
to false.
Property
introscope.agent.enterprisemanager.tra
nsport.tcp.host.DEFAULT
The host setting should be either the host name
or IP address of a machine with an Enterprise
Manager on it.
line.
introscope.agent.enterprisemanager.tra
nsport.tcp.port.DEFAULT
Enterprise Manager listens for Agent connections.
The port specified in this setting must match the
port defined in the setting,
introscope.enterprisemanager.port.agentli
stener in the
introscopeEnterpriseManager.properties file
for each matching Enterprise Manager. See
line.
Note: The “DEFAULT” segment of the two settings above is used in configuring Agent
Failover. For information on Agent Failover, see Agent Failover, page 173.
Enter a name for the application server the Agent
is monitoring.
alphabetical character, and cannot contain a “%”
character.
Page 125
New z/OS Properties
Beginning with Version 5.0, WebSphere for z/OS has changed its default encoding from
EBCDIC CP1047 to ASCII ISO8859-1. Because z/OS is normally an EBCDIC machine, any
logging data written by the Introscope Agent or AutoProbe must be tagged to use EBCDIC
as the final output stream, rather than ASCII.
Two new properties must be enabled in the IntroscopeAgent.profile to accomplish
this. These two properties are:
log4j.appender.console.encoding=IBM-1047
log4j.appender.logfile.encoding=IBM-1047
If these properties are not present in your existing IntroscopeAgent.profile, then
you need to add them.
In addition, a new property has been added for z/OS WebSphere Version 5.0 and above,
which is used to eliminate any startup timing window exposures that can occur with the
Introscope logging facilities. The following property should be added to your
IntroscopeAgent.profile:
introscope.agent.logger.delay=100000
The delay value is in expressed in milliseconds, so the default delay in this case is 100
seconds.
There are several additional WebSphere configuration options. You can configure
Introscope to extract WebSphere performance data through the JMX and PMI
management interfaces, or configure the Agent to find its name automatically from the
WebSphere application server instance. However, both of these options require a
WebSphere custom service to be configured. Note that only one custom service is
necessary to provide access to JMX, PMI and AutoNaming capabilities.
Use the following instructions to configure the startup class, then view the information in
the references in the next section to configure optional features that provide additional
performance data.
Using PMI with Introscope on z/OS
There are several ways to obtain additional WebSphere specific performance metrics on
z/OS. One solution is to add the Wily PowerPack for z/OS WebSphere which adds
additional probes and measurements that are specifically designed for key WebSphere
measurements. These utilize the standard Wily tracer technology and provide a low
overhead way to obtain additional WebSphere measurements, and do not require any PMI
facilities to be enabled inside WebSphere for z/OS.
PMI is another technique for obtaining performance measurements, with a somewhat
higher impact on performance. Wily does work with the IBM WebSphere z/OS PMI
associated PMI metrics toggles in the IntroscopeAgent.profile. For additional
details, see the section Enabling and Defining PMI Collection, page 191.
Page 126
Configuring a Custom Service in WebSphere 5.0
The following section describes how to create a custom service in WebSphere 5.0.
Consult your WebSphere documentation for instructions on creating a custom service in
previous versions, or for more information.
Configuring a Custom Service in WebSphere 5.0
1.
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.
10. Restart the application server.
Optional WebSphere Configurations
See 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 wilytech@custhelp.com.
Page 127
10 Configuring Sun ONE Application Server With
Introscope
This section describes how to configure (Introscope-enable) a Java Application with the
Sun ONE Application Server in the following sections:
• Configuring Introscope With Sun ONE Overview
• Installing Introscope Agent on Sun ONE
• Configuring Basic Agent Settings for SunONE
Configuring Introscope With Sun ONE Overview
options
Installing Introscope Agent on Sun ONE
To install the Introscope Agent on Sun ONE:
1.
Make sure that Sun ONE Application Server and any required updates have been
installed.
Note: For Sun ONE version 7.0, the following are the minimum Sun ONE versions
required for Introscope integration:
— Sun ONE AS Platform Edition 7.0.0_01 (update 1)
— Sun ONE AS Standard Edition 7.0.0_01 (update 1)
To download the appropriate application server versions, see the Sun website at
http://wwws.sun.com/software/download/app_servers.html.
2.
Find the Sun ONE installer file for your platform:
• IntroscopeAgentInstall6.0.1sunoneas.unix.tar
• IntroscopeAgentInstall6.0.1sunoneas.windows.zip
3.
Extract the installer file into the Sun ONE 7.0 Application Server installation directory,
<SunONE install dir>.
• Agent.jar
Page 128
• JVM AutoProbe
by the JVM.
Probebuilder)
manually does not.
The following table details the ProbeBuilder options available for each Sun ONE
method:
1.
Choose the row containing your Sun ONE Application Server version.
2.
3.
— Sun ONE Application Server version 7.0
— JVM AutoProbe
Page 129
— Sun JVM
you would use the instructions in the section, JVM AutoProbe With Sun ONE 7.0 Using
Sun JVM, page 130.
Application
Server Version
ProbeBuilder
Configuration
Option
JVM
Sun
JVM AutoProbe With Sun ONE 7.0 Using Sun
JVM, page 130
Sun ONE 7.0
JVM AutoProbe
any
Application Server AutoProbe With Sun ONE
7.0, page 131
Manual ProbeBuilder
any
JVM AutoProbe With Sun ONE 7.0 Using Sun JVM
There are two steps required to configure and use JVM AutoProbe with Sun JVM:
JVM used to run Sun ONE. There are two ways to specify the JVM:
1.
2.
Page 130
3.
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-toAgent.jar>
</jvm-options>
For example:
<jvm-options>
-Xbootclasspath/p:/sw/sun/sunone7/wily/connectors/
AutoProbeConnector.jar:/sw/sun/sunone7/wily/Agent.jar
</jvm-options>
4.
Modify the bootstrap classpath by adding the following option to the Java command
line:
5.
Proceed to the section, Configuring Basic Agent Settings for SunONE, page 133, to
Application Server AutoProbe With Sun ONE
Server AutoProbe.
Application Server AutoProbe With Sun ONE 7.0
The following instructions work with Sun ONE 7.0:
Page 131
Note: The use of “...” in the .xml examples below denotes that there is additional
information in the .xml code (not relevant to the example) that is not shown.
1.
2.
3.
Add the full path of wily/Agent.jar to the “server-classpath” property of the javaconfig element in the server.xml file. For example:
<java-config ... server-classpath="/sw/sun/sunone7/wily/
Agent.jar:..." ...>
4.
Add the following to the java-config element:
• Add the bytecode-preprocessors property and set it to the value
com.wily.introscope.api.sun.appserver.SunONEAutoProbe. For
example:
<java-config ... bytecodepreprocessors="com.wily.introscope.api.sun.appserver.SunONEAutoP
robe">
• Add a jvm-options element to define the location of the Agent profile. Define
either com.wily.introscope.agentProfile, or
com.wily.introscope.agentResource.
The following is an example of com.wily.introscope.agentProfile:
<java-config ...>
...
<jvm-options>-Dcom.wily.introscope.agentProfile=/sw/sun/sunone7/
wily/IntroscopeAgent.profile </jvm-options>
</java-config>
The following is an example of com.wily.introscope.agentResource:
<java-config ...>
...
<jvm-options>-Dcom.wily.introscope.agentResource=<virtual path
to>/IntroscopeAgent.profile</jvm-options>
</java-config>
5.
OPTIONAL: If you configured com.wily.introscope.agentResource, add the
resource file to the server classpath.
Page 132
6.
be collected.
1.
Locate <Sun ONE home>/wily/toggles-full.pbd.
2.
3.
4.
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
configuration settings are found in the file, <Sun ONE home>/wily/
Page 133
Defining Agent Profile Location in Sun ONE system.xml File
After you define the Agent profile location, you must add it to the system.xml file:
1.
2.
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
Property
Page 134
introscope.agent.enterprisemanager.transpor
t.tcp.host.DEFAULT
The host setting should be either the host name
or IP address of a machine with an Enterprise
Manager on it.
line.
introscope.agent.enterprisemanager.transpor
t.tcp.port.DEFAULT
Enterprise Manager listens for Agent
connections.
The port specified in this setting must match
the port defined in the setting,
introscope.enterprisemanager.port.agentl
istener in the
introscopeEnterpriseManager.properties
file for each matching Enterprise Manager. See
line.
Enter a name for the application server the
Agent is monitoring.
alphabetical character, and cannot contain a
“%” character.
For additional configuration options, see, Chapter 15, Optional Introscope Configurations.
Page 135
11 Configuring Oracle Application Server 10g With
Introscope
This section describes how to configure (Introscope-enable) a Java Application with the
Oracle Application Server 10g in the following sections:
• Configuring Introscope With Oracle 10g Overview
• Installing Introscope Agent on Oracle 10g
• Choosing ProbeBuilder Configuration Option
• Configuring Basic Agent Settings for Oracle 10g
Configuring Introscope With Oracle 10g Overview
options
Installing Introscope Agent on Oracle 10g
To 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
Page 136
• JVM AutoProbe
by the JVM.
Probebuilder)
manually does not.
The following table details the ProbeBuilder options available for each Oracle Application
Server 10g version and JVM combination. To find the appropriate ProbeBuilder method:
1.
Choose the row containing your Oracle Application Server 10g version.
2.
3.
— 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.
Page 137
Application
Server Version
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
Oracle Application Server 10g, page 139
any
Manual ProbeBuilder
JVM AutoProbe With Oracle 10g Using Sun JVM
There are two steps required to configure and use JVM AutoProbe with Sun JVM:
JVM used to Oracle 10g. There are two ways to specify the JVM:
1.
2.
3.
Page 138
classpath.
1.
Add the following option to the Java command line:
2.
Proceed to the section, Configuring Basic Agent Settings for Oracle 10g, page 140 to
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.
5.
be collected.
1.
Locate <Oracle 10g home>/wily/toggles-full.pbd.
2.
3.
4.
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
Page 139
Configuring Basic Agent Settings for Oracle 10g
configuration settings are found in the file, <Oracle 10g home>/wily/
Note: If you use this option, AutoProbe will not be able to write to
AutoProbe.log. See AutoProbe ProbeBuilder Log, page 201.
• Agent Name
Page 140
• Process Name
Property
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.
line.
introscope.agent.enterprisemanager.
transport.tcp.port.DEFAULT
introscope.enterprisemanager.port.agentlist
ener in the
monitoring.
character.
Page 141
12 Configuring SAP NetWeaver With Introscope
This section describes how to configure (Introscope-enable) a Java Application with SAP
NetWeaver in the following sections:
• Configuring Introscope With SAP NetWeaver Overview
Configuring Introscope With SAP NetWeaver Overview
options
Installing Introscope Agent
To install the Introscope Agent:
1.
Find the Agent installer file for your platform:
Operating
System
Installer Filename
Windows
IntroscopeAgentInstall6.0.1netweaver.windows.zip
Solaris
IntroscopeAgentInstall6.0.1netweaver.unix.tar
HP-UX
AIX
Linux
SAP Support Only
Operating
System
Installer Filename
Windows
IntroscopeAgentInstall6.0.1netweaver.windows.SAP.zip
Page 142
Solaris
IntroscopeAgentInstall6.0.1netweaver.unix.SAP.tar
HP-UX
AIX
Linux
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
by the JVM.
Probebuilder)
The JVM AutoProbe option installs probes dynamically into application code as it is
loaded. Whenever possible, using ProbeBuilder through AutoProbe will save time and
provide ease of use that Introscope-enabling an application manually does not.
The following table details the ProbeBuilder options available for use with SAP NetWeaver
versions 6.20 and 6.40. To find the appropriate ProbeBuilder method:
♦
Choose a ProbeBuilder configuration option:
• If using Manual ProbeBuilder, use the instructions associated with that option.
Page 143
Application
Server
ProbeBuilder
Configuration
Option
JVM
SAP NetWeaver v 6.20 or 6.40
JVM AutoProbe
Sun
JVM AutoProbe Using Sun or IBM JVM, page 144
IBM
HP
JVM AutoProbe Using HP HotSpot JVM, page 146
Manual ProbeBuilder
any
JVM AutoProbe Using 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.
JVM used to run the application server. There are two ways to specify the JVM:
1.
Change the working directory to wily/connectors.
2.
/<jvm_path>/java -jar CreateAutoProbeConnector.jar -current
java -jar CreateAutoProbeConnector.jar -jvm<directory>
Page 144
3.
After you have created the AutoProbe Connector, you must modify the boot class path by
adding JVM options. Typically, you will only want to activate the Agent on the SAP J2EE
server nodes, not on dispatchers and state controllers. Note that for class path and
directory paths, you can use forward slashes (/) on all platforms, even on Windows. For
SAP J2EE 6.40, you even cannot use backslash (\) on Windows. Furthermore, note that
on the classpath, the entries are separated by a semicolon (;) on Windows, but by a colon
(:)on Unix.
For Agent name, we recommend you use an identifier that uniquely identifies the J2EE
node in your landscape, e.g., <hostName>_<server0> or similar.
Note: The following path examples use the Windows convention.
Using SAP J2EE 6.20
1.
Open the file:
<drive>:\usr\sap\<J2EE_ENGINE_ID>\j2ee\j2ee_<INSTANCE>\cluster\
server\cmdline.properties
2.
Append the following commands to JavaParameters:
-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>;<path-toAgent.jar>
-Dcom.wily.introscope.agentProfile=<path-toIntroscopeAgent.profile>
-Dcom.wily.introscope.agent.agentName=<yourAgentName>
For example:
-Xbootclasspath/
p:C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\connectors\AutoProbeCon
nector.jar;C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\Agent.jar
Dcom.wily.introscope.agentProfile=C:\usr\sap\P602\j2ee\j2ee_00\c
cms\wily\IntroscopeAgent.profile
3.
Restart SAP server.
Using NetWeaver 04/SAP J2EE 6.40
1.
Run the SAP J2EE Configtool.
2.
Select the server to modify.
Page 145
3.
In the Java Parameters field, add the following new java parameters:
-Xbootclasspath/p:<path-to-AutoProbeConnector.jar>;<path-toAgent.jar>
-Dcom.wily.introscope.agentProfile=<path-toIntroscopeAgent.profile>
For example:
-Xbootclasspath/p:D:/usr/sap/ccms/wily/connectors/
AutoProbeConnector.jar;D:/usr/sap/ccms/wily/Agent.jar
-Dcom.wily.introscope.agentProfile=D:/usr/sap/ccms/wily/
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 JVM
The following instructions work with HP HotSpot JVM.
1.
2.
3.
Agent profile.
Page 146
Configuring Basic Agent Settings
configuration settings are found in the file, <Application server home>/wily/
• Agent Name
• Process Name
Page 147
Property
introscope.agent.enterprisemanager
.transport.tcp.host.DEFAULT
.transport.tcp.port.DEFAULT
in the introscopeEnterpriseManager.properties file
for each matching Enterprise Manager. See Uninstalling
Introscope, page 54.
monitoring.
introscope.agent.customProcessNa
me
Page 148
13 Configuring Other Application Servers or
Applications With Introscope
This section describes how to configure (Introscope-enable) a Java Application in the
following sections:
• Configuring Introscope With Other Application Servers Overview
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.
options
To install the Introscope Agent:
1.
• IntroscopeAgentInstall6.0.1default.unix.tar
• IntroscopeAgentInstall6.0.1default.windows.zip
• IntroscopeAgentInstall6.0.1default.zOS.tar
• IntroscopeAgentInstall6.0.1default.os400.zip
2.
Page 149
• Agent.jar
3.
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
by the JVM.
Probebuilder)
The JVM AutoProbe option installs probes dynamically into application code as it is
loaded. Whenever possible, using ProbeBuilder through AutoProbe will save time and
provide ease of use that Introscope-enabling an application manually does not.
The following table details the ProbeBuilder options available when not using WebLogic,
WebSphere, Sun ONE or Oracle 10g. To find the appropriate ProbeBuilder method:
1.
2.
• If using Manual ProbeBuilder, use the instructions associated with that option.
Page 150
ProbeBuilder
Configuration
Option
JVM
any Java 5.0 JVM
JVM AutoProbe Using Java 5.0 JVM, page 151
Sun
IBM
HP
JVM AutoProbe Using HP HotSpot JVM, page 152
JVM AutoProbe
Manual ProbeBuilder
any
Chapter 14, Configuring the Java Applications Manually
With ProbeBuilder
JVM AutoProbe Using Java 5.0 JVM
The following instructions work Java 5.0 JVM:
1.
Add the following command-line option to the JVM command line:
-javaagent:<path-to-Agent.jar>
2.
Agent profile.
JVM AutoProbe Using Sun or IBM JVM
JVM used to run the application server. There are two ways to specify the JVM:
1.
Change the working directory to wily/connectors.
2.
/<jvm_path>/java -jar CreateAutoProbeConnector.jar -current
Page 151
java -jar CreateAutoProbeConnector.jar -jvm<directory>
3.
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:
2.
Agent profile.
JVM AutoProbe Using HP HotSpot JVM
The following instructions work with HP HotSpot JVM.
1.
2.
3.
Agent profile.
configuration settings are found in the file, <Application server home>/wily/
Page 152
• Agent Name
• Process Name
Property
.transport.tcp.host.DEFAULT
.transport.tcp.port.DEFAULT
in the introscopeEnterpriseManager.properties file
for each matching Enterprise Manager. See Uninstalling
Introscope, page 54.
Page 153
monitoring.
introscope.agent.customProcessNa
me
Page 154
14 Configuring the Java Applications Manually With
ProbeBuilder
This section describes how to manually Introscope-enable a Java Application in the
following sections:
• Configuring Java Applications Manually Overview
• Configuring Java Applications With ProbeBuilder Wizard
• Configuring Java Applications With Command-Line ProbeBuilder
• Options for Running Introscope-enabled Code
• Switching Back to Your Non-Introscope-enabled Code
Configuring Java Applications Manually Overview
Enterprise Manager.
When you run ProbeBuilder manually, it Introscope-enables classes on disk before the
application server is run. You can use Manual ProbeBuilder when you want to:
• Introscope-enable a Java system other than those integrated with AutoProbe
(WebLogic, WebSphere, Sun ONE, Oracle 10g, HP HotSpot JVM)
• add probes to your code without using AutoProbe, even if you are using one of the
above systems.
Using AutoProbe offers dynamic instrumentation of bytecode. To Introscope-enable your
Java application using AutoProbe, see Chapter 6, Configuring Java Applications With
Introscope.
There are two methods available to Introscope-enable your bytecode manually:
• ProbeBuilder Wizard
ProbeBuilder Wizard walks you through the process of manually Introscopeenabling your application in a windowing environment.
• Command-line ProbeBuilder
Command-line ProbeBuilder is a command-line interface for Introscope-enabling
your applications manually.
Configuring Java Applications With ProbeBuilder Wizard
If your machine has a windowing environment, use the instructions in this section to add
Probes to your bytecode.
Page 155
• perform a full Introscope installation
• Introscope-enable the application code using ProbeBuilder Wizard
Installing Introscope
A 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.
1.
• If you are Introscope-enabling WebSphere, WebLogic, Sun ONE, Oracle 10g or HP
HotSpot JVM with Command-line ProbeBuilder, use one of the following Agent
installers:
— IntroscopeAgentInstall6.0.1weblogic.unix.tar
— IntroscopeAgentInstall6.0.1weblogic.windows.zip
— IntroscopeAgentInstall6.0.1weblogic.zOS.tar
— IntroscopeAgentInstall6.0.1weblogic.os400.zip
— IntroscopeAgentInstall6.0.1websphere.unix.tar
— IntroscopeAgentInstall6.0.1websphere.windows.zip
— IntroscopeAgentInstall6.0.1websphere.zOS.tar
— IntroscopeAgentInstall6.0.1websphere.os400.zip
— IntroscopeAgentInstall6.0.1hpjvm.hpux.tar
— IntroscopeAgentInstall6.0.1sunoneas.unix.tar
— IntroscopeAgentInstall6.0.1sunoneas.windows.zip
— IntroscopeAgentInstall6.0.1oracleas.unix.tar
— IntroscopeAgentInstall6.0.1oracleas.windows.zip
— IntroscopeAgentInstall6.0.1netweaver.windows.zip
— IntroscopeAgentInstall6.0.1netweaver.unix.tar
• If you are not using one of the above application servers, use one of the following
Agent installers for your platform:
— IntroscopeAgentInstall6.0.1default.unix.tar
— IntroscopeAgentInstall6.0.1default.windows.zip
Page 156
— IntroscopeAgentInstall6.0.1default.zOS.tar
— IntroscopeAgentInstall6.0.1default.os400.zip
2.
• 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).
3.
Proceed to Adding Probes to Bytecode With ProbeBuilder Wizard, page 157.
Adding Probes to Bytecode With ProbeBuilder Wizard
To add Probes to bytecode with ProbeBuilder Wizard:
1.
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.
Page 157
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.
Page 158
c.
6.
Click Select Java Bytecode to enter your desired directory and click Next.
Enter the name and location for the new directory to contain the Introscope-enabled
code, or click Browse to select a location. The default name is the original directory
with the suffix “isc.”
Page 159
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.
Page 160
9.
Click Next.
If you installed custom Directives files in your config/custompbd directory, they
appear in this window. The above screenshot shows an example where a user has
installed two custom .pbd files.
In the Custom Directives window, check the box next to any custom Directives that
you want to use with this bytecode.
Note: For information on creating custom Directives, see Chapter 17, ProbeBuilder
Directives.
10. Check the box for any custom .pbd files you want to use, then click Add Probes.
11. Introscope adds Probes to the specified bytecode. This operation may take several
minutes.
12. When the Finished screen appears, click Exit or Add Additional Probes to add
Probes to another directory.
Editing the Classpath
After adding Probes to the bytecode, update the classpath of the application startup script
to reflect the locations of the Introscope-enabled code and the Agent.
1.
Edit the classpath of the application startup script to include locations of the
directories containing the Introscope-enabled code created with the ProbeBuilder.
Make sure this reference precedes the reference to the original code in the classpath.
Page 161
Configuring Java Applications With Command-Line ProbeBuilder
2.
Edit the classpath in the application startup script to include the path to the
<Introscope home>/lib/Agent.jar.
For example, you might edit a classpath that looks like this:
java -classpath /<your-applicationpath>/classes:/<yourapplicationpath>/lib/app.jar MainClass
to look like this:
java -classpath /<your-applicationpath>.isc/classes:/<yourapplicationpath>.isc/lib/app.jar:/Introscope/lib/Agent.jar
MainClass
3.
Save the changes.
4.
Start your application with the new startup script.
5.
Proceed to the section, Configuring Basic Agent Settings, page 165.
Configuring Java Applications With Command-Line
ProbeBuilder
If your machine does not have a windowing environment, use the instructions in this
section to add Probes to your bytecode.
• Introscope-enable the application code using Command-line ProbeBuilder
1.
• 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
Page 162
— IntroscopeAgentInstall6.0.1hpjvm.hpux.tar
— IntroscopeAgentInstall6.0.1sunoneas.unix.tar
— IntroscopeAgentInstall6.0.1sunoneas.windows.zip
— IntroscopeAgentInstall6.0.1oracleas.unix.tar
— IntroscopeAgentInstall6.0.1oracleas.windows.zip
• If you are not using one of the above application servers, use one of the following
Agent installers for your platform:
— IntroscopeAgentInstall6.0.1default.unix.tar
— IntroscopeAgentInstall6.0.1default.windows.zip
— IntroscopeAgentInstall6.0.1default.zOS.tar
— IntroscopeAgentInstall6.0.1default.os400.zip
2.
• 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).
Adding Probes to Bytecode Using Command-Line ProbeBuilder
The Command-Line ProbeBuilder is activated by a command. The following code is an
example of the command. This example is being run from the /wily directory, so paths
are relative to the /wily directory. The syntax for the Java command depends on your
Java version and other settings in your environment.
Note: If you are processing a very large .jar file, you may need to increase the memory
in your JVM memory settings. Consult your JVM documentation for instructions.
Example:
java -classpath ext/ProbeBuilder.jar
com.wily.introscope.api.IntroscopeProbeBuilder
-directives default.pbl,stream.pbd
Page 163
-origdir /usr/myApp/classes -destdir /usr/myApp/classes.isc
–verbose
TABLE 4. Command Line ProbeBuilder Commands
Option
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
Specifies the original directory (including subdirectories)
-destdir directory
Specifies the destination directory
-origjar file
Specifies the original archive, including .jar, .zip, .war,
.rar and .ear archives
-destjar file
Specifies the destination archive
-origclass file
Specifies the original class
-destclass file
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.
Editing the Classpath
After adding Probes to the bytecode, update the classpath of the application startup script
to reflect the locations of the Introscope-enabled code and the Agent.
1.
Edit the classpath of the application startup script to include locations of the
directories containing the Introscope-enabled code created with the ProbeBuilder.
Make sure this reference precedes the reference to the original code in the classpath.
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
Page 164
to look like this:
java -classpath /<your-applicationpath>.isc/lib/app.jar:/
<appserver home>/wily/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.
The following section details how to configure the Introscope Agent. Agent configuration
settings for non-AutoProbe installations are found in the file, /wily/
IntroscopeAgent.profile. Before performing any Agent configurations, you may
want to copy the IntroscopeAgent.profile, and rename it to a name that identifies
the Agent, such as Petstoreagent.profile. You can place it in another directory,
You can customize the locatin of the Agent profile, as long as you define the new location
using one of the following methods:
Page 165
Options for Running Introscope-enabled Code
• Agent Name
• Process Name
Property
introscope.agent.enterprisemanager.transp
ort.tcp.host.DEFAULT
The host setting should be either the host name or
IP address of a machine with an Enterprise
Manager on it.
introscope.agent.enterprisemanager.transp
ort.tcp.port.DEFAULT
introscope.enterprisemanager.port.agentlis
tener in the
Enter a name for the application server the Agent
is monitoring.
character.
If an Agent is not named in the Agent profile, the
default name is Unknown Agent.
Options for Running Introscope-enabled Code
There are three ways to point to Introscope-enabled code instead of your original code:
• Replace original paths in classpaths with paths to the Introscope-enabled code.
In classpaths, replace original-class paths with Introscope-enabled code paths.
The instructions in this chapter directed you to perform this process when you
Introscope-enabled your application for the first time.
• Prepend paths to classpaths.
Page 166
Switching Back to Your Non-Introscope-enabled Code
If only part of the 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. NonIntroscope-enabled code still loads and works normally, but does not report
performance data.
• Place Introscope-enabled code in original classpath.
Use this method when classpaths are set in many places, or to conduct an
evaluation. Be careful of using this method in a production environment, as with
this method it is easy to forget whether you are using the original or the
Introscope-enabled code.
— Move the original code to a new location. Leave the classpaths unchanged.
Then move the Introscope-enabled code to the original location.
— On a UNIX machine, you could also create a symbolic link from the current
location of the Introscope-enabled code to the original location.
Switching Back to Your Non-Introscope-enabled Code
If you want to switch back to using non-Introscope-enabled code, undo the steps of
modifying classpaths to run Introscope-enabled code, as described below:
• If you put the paths to your Introscope-enabled code into the Java classpaths,
then replace paths to the Introscope-enabled code in Java classpaths with original
paths.
• If you added paths to the Introscope-enabled code in front of the paths to the
original code, remove prepended paths to classpaths
Remove the prepended portion of the classpath so that only the original classpath
remains.
• If you put Introscope-enabled code in original classpath, then remove the
Introscope-enabled code from the original path and place the original code in the
original classpath.
If you used symbolic links on a UNIX system, point the symbolic link to the
original directory, or remove the link and move the code into the original
classpath.
Page 167
15 Optional Introscope Configurations
This section describes optional Introscope configurations in the following sections:
• Agent Naming Options
• Agent Failover
• Switching Between “Full” and “Typical” Tracing Options
• Multiple Agent Options
• Other Optional Agent Settings
• Agent Logging Options
• Platform Monitors
• JMX Filters For Obtaining Advanced Performance Data
• Advanced WebSphere Performance Data
• Enterprise Manager Database Recording
• Optional Enterprise Manager Configurations
• Connecting Workstation to Enterprise Manager Behind Firewall
• Optional ProbeBuilder Configurations
• Miscellaneous Installation Options
Page 168
Agent Naming Options
Introscope allows multiple ways of specifying the Agent name, some that can pull the
Agent name from a system property already set in the JVM, or in some cases,
automatically from the application server. In most cases, this eliminates the need to
configure individual Agent names in separate Agent profiles.
Agent Name Location Sequence
The Introscope Agent will attempt to find a name for itself through the following sequence
of methods. If it finds a name using the first method, it will accept that name and connect
to the Enterprise Manager. If it 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 Properties
The following sections describe how to configure Agent naming using Java system
property options.
Specifying Agent Name Using Java System Property
This method is the first the Agent will use to look for its name. If this method is used, it
will override Agent names specified using any other method.
To specify an Agent name using the Java system property:
♦
On the Java command line, specify an Agent name using the following Java system
property:
Page 169
com.wily.introscope.agent.agentName
Specifying Agent Name Using System Property Key
This method is the second the Agent will use to look for its name. Use this method if you
want the Agent to be named from the value of an existing Java system property in your
deployment.
To specify an Agent name using the System Property Key:
1.
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.
3.
Obtaining Agent Name Automatically From Application Server
As 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.
Page 170
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.
Page 171
Enabling Automatic Agent Naming
There are some minor configurations you need to perform to enable Automatic Agent
Naming.
To enable Automatic Agent Naming, make sure the following pre-requisites have been
fulfilled:
1.
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:
1.
2.
Under the Agent Name section, configure the desired delay in the
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds
property.
3.
Agent Rename Check Interval
When using the Automatic Agent Naming feature, the Agent will periodically check to see
if the naming information from the application server has changed. The default interval is
ten minutes. To change this interval:
1.
2.
Under the Agent Name section, configure the desired interval in the
introscope.agent.agentAutoRenamingIntervalInMinutes property.
3.
Page 172
Agent Failover
Turning Off Agent Log File Automatic Naming
By default, when the Agent name is found automatically, either by information provided
by a Java system property or application server, the log files associated with that Agent
are named automatically using that same information. However, you can optionally turn
off this automatic log naming, and continue to use the Agent log name specified in the
IntroscopeAgent.profile.
To turn off Agent log file automatic naming:
1.
2.
Locate the property, introscope.agent.disableLogFileAutoNaming, and
enter a value of true.
3.
Agent Failover
Agent 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 Failover
In a basic Introscope configuration, you defined the host and port settings for one
Enterprise Manager. To enable Agent Failover, you must define a list of Enterprise
Managers that the Agent will try to connect to if it disconnects from its current Enterprise
Manager.
For each Enterprise Manager in the list, you will need to:
• set the host setting
• set the port setting
• assign it a name
After defining Enterprise Manager details, you will provide a desired connection order that
the Introscope Agent will use to reconnect to an Enterprise Manager if the connection to
the primary Enterprise Manager is lost.
1.
2.
Locate the Enterprise Manager Locations and Names section.
The default Enterprise Manager set in the
introscope.agent.enterprisemanager.tcp.host and
Page 173
Agent Failover
introscope.agent.enterprisemanager.tcp.port settings is named DEFAULT,
as seen here:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localh
ost
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001
3.
Duplicate these two settings for each Enterprise Manager in your list, and set their
host and port settings. The host setting should be either the host name or IP address
of a machine with an Enterprise Manager on it. The port can be any unused port for
this IP address, as it will listen for Agent connections. This port should be the same
as the configured Agent listening port on the Enterprise Manager.
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=enterpr
ise
introscope.agent.enterprisemanager.transport.tcp.port.MainEM=5001
introscope.agent.enterprisemanager.transport.tcp.host.BackupEM1=voya
ger
introscope.agent.enterprisemanager.transport.tcp.port.BackupEM1=5002
introscope.agent.enterprisemanager.transport.tcp.host.BackupEM2=spac
e9
introscope.agent.enterprisemanager.transport.tcp.port.BackupEM2=5003
5.
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.
Page 174
Switching Between “Full” and “Typical” Tracing Options
Configuring Automatic Agent Failback to Primary Enterprise
Manager
In the default Agent Failover scenario, if the Agent loses the connection to its primary
Enterprise Manager (the first one defined in the Enterprise Connection order list), it will
attempt to connect to the next Enterprise Manager defined in the Agent profile. You can
optionally configure the Agent to periodically attempt to reconnect to the primary
Enterprise Manager.
To configure the Agent to attempt to reconnect to the primary Enterprise Manager:
1.
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 Configuration
If you want to take advantage of Agent Failover functionality, and also have Users,
Domains, and authentication settings defined, you must make sure that this information
is in sync across the specified failover Enterprise Managers. For more information on
Domains and user permissions, see Chapter 5, Configuring Introscope Security and
Permissions.
Switching Between “Full” and “Typical” Tracing Options
In Introscope, Tracer groups cause the reporting of information about a set of classes.
Tracer groups are found in PBD files, and referred to in PBL (ProbeBuilder list) files. There
are two sets of PBL files available with each Agent installer:
• Full (default)= references PBD files in which a set of common Tracer Groups in
PBD files are turned on. Introscope uses this set by default to demonstrate full
Introscope functionality.
• Typical= references PBDs in which only a subset of Tracer Groups are turned on.
The typical set includes common settings, and is the set you can customize for a
particular environment.
For more information on full and typical system directives files and customizing the
TYPICAL settings, see Default Tracer Groups and Toggles Files, page 215.
Switching to “Typical” Tracing Options
To change to using a “typical” .pbl:
1.
2.
Locate the Directives Files section.
Page 175
Multiple Agent Options
3.
In the introscope.autoprobe.directivesFile property, enter the name of the
appropriate <appserver>-typical.pbl file. For example, if using WebLogic, you
the property may look like the following example:
introscope.autoprobe.directivesFile=weblogic-typical.pbl
4.
Restart the managed application.
Multiple Agent Options
You may at times run identical instances of your applications. In these situations,
Introscope will attempt to resolve the identical Agent names by appending the Agent
name with a character and a random number. However, it is better if you tell Introscope
how to resolve the naming.
The options for resolving identical Agent naming are:
• Tell Introscope that the Agents in question are cloned Agents by enabling cloned
Agent naming (described in Enabling Cloned Agent Naming, page 176)
• Define unique Agent names yourself and make separate Agent profiles for each
Agent (described in Running An Application Twice On One Machine, page 177)
• Let Introscope uniquely name each Agent using its own naming scheme
(described in How Introscope Resolves Agent Naming Conflicts, page 177)
Enabling Cloned Agent Naming
if two Agents exist with the same name monitoring the same host and process and are
not uniquely named by a user, the name is appended with a random number (described
in the section, How Introscope Resolves Agent Naming Conflicts, page 177). With this
random numbering scheme, it is not possible to track Agents in a cluster. Cloned Agent
Naming allows you to correlate an Agent with a particular instance in a cluster.
You are running cloned Agents if you:
• are running Agents that share a host, process and Agent Name with one or more
other Agents
OR
• are running two or more Agents that are using the same Agent profile
Scenario
If you have four Agents, all named AgentX, the Enterprise Manager may name them
AgentX, AgentX%475, AgentX%476 and AgentX%477. If for some reason AgentX%475
disconnects, when it comes back, it will be renamed another random number, such as
AgentX%845.
With the Agent cloning property turned on, in this same situation, the Agents in this
example would be named AgentX-1, AgentX-2, AgentX-3 and AgentX-4.
If Agents AgentX-2 and AgentX-3 disconnected, and another Agent with the same name
(AgentX) came back on, it would be given the name AgentX-2. With this naming, you will
never have more Agent names in the database than the number of Agents originally
cloned.
Page 176
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 Machine
You may sometimes run one application twice on the same machine. In this case, ideally
you should:
• create a separate Agent profile for each application
• uniquely name each Agent in the Agent profile
• specify which Agent profile each application should use.
How Introscope Resolves Agent Naming Conflicts
The Fully-Qualified Agent name makes each Agent unique, because it is composed of the
combination of host name, process name and Agent name. Even if a user 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 FullyQualified Agent name could technically happen if:
• both resided on the same host and were monitoring the same process, and
• neither of them had been uniquely named by the user, or for some reason they
happened to have the same Agent name.
If a duplicate Fully-Qualified Agent does attempt to connect to the Enterprise Manager, it
will be given a unique name by the Enterprise Manager by appending the Agent Name
with a “%” character and a random number, using the following syntax:
<AgentName>%<randomNumber1>
This uniquely generated name is only used while the Agent is connected. Subsequent
reconnects will generate yet another unique name. As you can see, this situation could
make it difficult to track that Agent when doing queries.
Other Optional Agent Settings
Using Custom ProbeBuilder Directives Files (AutoProbe installations
only)
If you have created Custom Probebuilder Directives (.pbd) files or want to use other
directives files, use the following steps.
Page 177
Agent Logging Options
1.
AutoProbe looks for any custom directives files in the directory that contains the
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 Bytecode
When you Introscope-enable application bytecode, by default, the AutoProbe or
ProbeBuilder preserves the bytecode line numbers. Preserving bytecode line number
information is helpful when using debuggers, or when obtaining stack trace information.
You can turn off this feature, (which will remove all line numbers when AutoProbe or
ProbeBuilder Introscope-enables the application code), by adding a system property on
the Java command line.
To remove line numbers in bytecode when using AutoProbe or ProbeBuilder:
♦
define the following system property on the Java command line with the -D option:
com.wily.probebuilder.removeLineNumbers=true
Turning Off Socket Input/Output Metrics
Metrics that trace per socket bandwidth have a potential for high overhead, and can be
turned off if you notice that collecting network Metrics is consuming a lot of processor or
I/O time.
To turn off the reporting of server and client socket input and output Metrics:
♦
In the IntroscopeAgent.profile, for the property,
introscope.agent.sockets.reportRateMetrics, enter a value of false.
The following section describes how to run the Agent in verbose mode and set logfile
details for the Agent. Introscope uses Log4J functionality for these functions. If you want
to use other Log4J functionality, please see Log4J documentation at http://
jakarta.apache.org/log4j/docs/documentation.html.
Page 178
Agent Log Files and Automatic Agent Naming
If you are using Automatic Agent Naming functionality, by default, when the Agent name
is found automatically, either by information provided by a Java system property, or
provided through the application server, the log files associated with that Agent are
named automatically using that same information.
The following examples show how the Agent logfile will be named. The examples use an
Agent name of DOM1//ACME42 (where DOM1 is the WebLogic domain, and ACME42 is
the instance). When an Agent log file is created (by default, named AutoProbe.log), if
the Agent name is not yet available, a timestamp will be included in the filename, as in:
AutoProbe20040416-175024.log
Once the Agent name becomes available, the logfile will be renamed, as in:
AutoProbeDOM1_ACME42.log
You can disable this automatic log naming. See Advanced Automatic Naming Options,
page 172.
Agent Logfile Automatic Naming Notes
The following notes apply to Agent logfile automatic naming:
• if the original name of the logfile does not end in .log, a period will be appended,
and “log” added.
• all characters not letters or digits will be replaced by underscores
• if advanced Log4J functionality is used, the Agent logfile automatic naming
capability may not work
Running Agent in Verbose Mode
Running the Agent in verbose mode records details to the log, which is helpful in
debugging.
To run the Agent in verbose mode:
1.
2.
In the property, log4j.logger.IntroscopeAgent, replace “INFO” with the
following:
3.
Save changes.
Redirecting Agent Output to a File
To redirect Agent output to a file:
1.
2.
In the property, log4j.logger.IntroscopeAgent, replace “console” with
“logfile.”
Page 179
Platform Monitors
For example, if you wanted the Agent to report in verbose mode to a logfile, the
property would look like this:
log4j.logger.IntroscopeAgent=VERBOSE#com.wily.util.feedback.Log4
JSeverityLevel,logfile
3.
If desired, change the name and/or location of the Introscope Agent logfile in the
property, log4j.appender.logfile.File.
Platform Monitors
Platform monitors enable the Agent to report platform Metrics, including CPU statistics, to
the Enterprise Manager. Operating systems that Introscope can monitor are:
• Solaris
• Windows Server 2003
• Windows 2000 Professional/Server/Advanced Server/Datacenter Server
• Windows XP Professional
• AIX
• Red Hat Enterprise Linux 2.1
• RedHat Enterprise Linux 3.0
The platform Metrics generated are:
• ProcessID
• Processor Count - the number of CPUs
• Utilization % (process) - for the Agent process, what percentage of total
capacity of all processors this process is using. No matter how many processors
there are, this Metric generates only one number.
• Utilization % (aggregate) - for this processor, its total utilization (as a
percentage) by all processes in the system. Each processor is shown as a
Resource in the Explorer tree. For example, in the following screenshot, statistics
are being shown for two processors:
Page 180
Platform Monitors
Platform monitors are included with the Introscope Agent installers.
Enabling Platform Monitors
Platform monitors on all platforms except Windows Server 2003 and AIX are
automatically enabled upon Agent installation. Windows Server 2003 and AIX platform
monitors require a minimal configuration to work. The following sections describe these
configurations.
Enabling Platform Monitors on Windows Server 2003
You must have “admin” privileges to run Platform Monitors on Windows Server 2003.
Enabling Platform Monitors on AIX
1.
After Agent installation, make sure the following files are installed in the
<appserver home>/wily/ext directory:
• introscopeAIXStats.jar
• introscopeAIXStats.so
2.
Install the Perfstat Library.
• AIX 5: Install the patch/fix APAR IY30022 from IBM at http://
techsupport.services.ibm.com/server/aix.fixsearch51.
• AIX 4.3.3 and higher: A Perfstat Library has been created to work with AIX 4.3.3.
Install the following packages from ftp://ftp.software.ibm.com/aix/fixes/v4/os:
— bos.perf.libperfstat
— bos.perf.perfstat
• AIX 4: Bring your system up to 4.3.3 and then install the above packages.
Note: Restart your machine to ensure the patches have taken effect.
Disabling Platform Monitors
To disable platform monitors on any platform, simply move the .jar file from the
<appserver home>/wily/ext directory to another directory.
The following table details the location of platform monitor files installed with an Agent
installer.
TABLE 5. Platform Monitor File Locations
Solaris
Windows
•
•
•
Server 2003
all Windows 2000
platforms
XP Professional
•
•
<appserver home>/wily/ext/introscopeSolarisStats.jar
<appserver home>/wily/ext/introscopeSolarisStats.so
•
•
<appserver home>\wily\ext\introscopeWindowsStats.jar
<appserver home>\wily\ext\introscopeWindowsStats.dll
Page 181
JMX Filters For Obtaining Advanced Performance Data
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
Platform Configuration Troubleshooting Option
In most cases, the platform monitor will successfully detect the operating system and run
if the operating system is supported. In rare cases where this does not occur, you can
explicitly specify your operating system in the Agent profile to ensure that the platform
monitor runs.
1.
2.
Under the Platform Monitor Configuration heading, locate the
introscope.agent.platform.monitor.system property and enter the value for
your operating system. Available values are:
• AIX
• Solaris
• Windows
• RedHat2.1
• RedHat3.0
3.
Introscope 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
Page 182
Introscope only polls the RuntimeServiceMBean, because it's the only one that supports
local access (an efficiency issue), and it contains most of the data we expect to be
relevant.
Metric Name Conversion and Filters
Information in MBeans is defined by a domain name and one or more key/value pairs.
Introscope converts this JMX information into Introscope-specific Metric format and
displays it in the Explorer under the following Resource:
<Domain>|<Host>|<Process>|<Agent>|JMX|
There are two methods Introscope uses to convert JMX MBean information to Introscope
Metrics:
• primary keys method
• default method
WebLogic 9.0 Metric Name Conversion
Normally a user can choose either the Primary Keys Conversion method or the default
method. However, WebLogic 9.0 does not have any universally available primary keys, so
WebLogic 9.0 will use the key/value pair Metric naming convention found in the Default
Conversion Method described in Default Conversion Method, page 184. This also means
the JMX Metric tree for WebLogic 9.0 will look different than that seen with other
WebLogic versions.
Primary Keys Conversion Method
Defining primary keys provides users a way to streamline JMX Metric name conversion,
and specify the order of key/value pair information in the generated Introscope-specific
Metrics.
In this method, a user defines primary keys in the
introscope.agent.jmx.primarykeys property in the Agent profile,
IntroscopeAgent.profile. A primary key defined here should uniquely identify an
MBean. For example, WebLogic uses the “Type” key (for the kind of component or
resource) and “Name” key (the name of the component or resource).
The primary keys conversion method is used to convert MBean attributes if Introscope
finds a match for one or more user-defined primary keys in an MBean.
When Introscope converts MBean attributes using the primary keys method:
• only the value information is displayed
• values are ordered in the sequence defined in the
introscope.agent.jmx.primarykeys property.
The following example shows the syntax used for the primary keys conversion method:
<Domain>|<Host>|<Process>|<Agent>|JMX|<domain
name>|<value1>|<value2>:<metric>
Page 183
For example, if an MBean has the following attributes:
Domain name
Key/Value Pairs
Metric Names
WebLogic
category=server, type=jdbc
connections
and a user sets the following values as primary keys:
introscope.agent.jmx.primarykeys=type,category
The MBean attributes in the table above would be converted to the following Introscope
Metric:
<Domain>|<Host>|<Process>|<Agent>|JMX|Weblogic|jdbc|server:connectio
ns
Default Conversion Method
The default conversion method is used to convert an MBean if:
• using WebLogic 9.0
• no primary keys are defined by the user, or
• no user-defined primary keys are found in the MBean information, or
• no user-defined primary keys are matched due to misspellings or incorrect case.
When Introscope converts MBean attributes using the default method:
• key and value information is displayed
• key/value pairs are placed in alphabetical order in the Introscope-generated
Metrics.
The following example shows the syntax used for the default conversion method:
<Domain>|<Host>|<Process>|<Agent>|JMX|<domain
name>|<key1>=<value1>|<key2>=<value2>:<metric>
For example, if an MBean has the following attributes:
Domain name
Key/Value Pairs
Metric Names
WebLogic
category=server, type=jdbc
connections
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.
Page 184
Filters are set in the introscope.agent.jmx.name.filter property in the Agent
profile file, IntroscopeAgent.profile. Filters are keywords, entered as
comma-separated strings in the property. Introscope tries to match the filter strings in
JMX-generated Introscope Metrics. If it finds a match, the Metrics that contain the strings
will be reported to Introscope.
Default JMX Filters for WebLogic
In the IntroscopeAgent.profile file shipped with WebLogic, the following keywords
are already defined:
• ActiveConnectionsCurrentCount
• WaitingForConnectionCurrentCount
• PendingRequestCurrentCount
• ExecuteThreadCurrentIdleCount
• OpenSessionsCurrentCount
Configuring JMX Functionality
Full JMX functionality is configured through the following steps:
• Step 1: enable JMX Support in the Agent profile
• Step 2: define primary keys for converting JMX MBean information into
Introscope-specific Metrics
• Step 3: define filters to streamline incoming JMX information
For WebLogic and WebSphere there are additional steps:
• for WebLogic, configure a startup class
• for WebSphere 5.0.x and higher, configure a custom service and modify the Java2
security policy
Step 1: Enabling JMX Support
To enable JMX support, follow these steps:
1.
For each application server, perform the following configuration:
• for WebLogic, configure a startup class. See Creating a WebLogic Startup Class,
page 105.
• for WebSphere, configure a custom service. See Configuring a Custom Service in
WebSphere, page 116.
2.
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:
Page 185
#introscope.agent.jmx.name.jsr77.enable=true
#introscope.agent.jmx.name.primarykeys=J2EEServer,Application,j2
eeType,JDBCProvider,name,mbeanIdentifier
#introscope.agent.jmx.name.filter=JSR77
#introscope.agent.jmx.ignore.attributes=server
4.
Continue to the next step, Step 2: Defining Primary Keys.
Step 2: Defining Primary Keys
To define primary keys, use the following steps:
1.
2.
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.
5.
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
Page 186
WebLogic Diagnostic Framework Data
permission com.tivoli.jmx.MBeanServerPermission "*";
permission com.tivoli.jmx.MBeanPermission "*";
permission com.tivoli.jmx.AllMBeanPermission "*";
};
Viewing JMX Data In Explorer
After 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.
The WebLogic Diagnostic Framework (WLDF) is a monitoring and diagnostic framework
that defines and implements a set of services that run within the WebLogic Server®
process and participate in the standard server life cycle. Using WLDF, you can create,
collect, analyze, archive and access diagnostic data generated by a running server and
the applications deployed within its containers. This data provides insight into the runtime performance of servers and applications and enables you to isolate and diagnose
faults when they occur.
Page 187
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 thirdparty 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 Conversion
Introscope WLDF Metric conversion is similar to that in JMX metric conversion. Where JMX
MBeans have multiple “Attributes” (metrics), WLDF has a set of “Data Accessors,” each
with multiple “Columns” (metrics). Introscope converts WLDF “Columns” to Introscope
Metrics.
Information in Data Accessors is defined by a domain name and one or more key/value
pairs. Introscope converts this WLDF information into Introscope-specific Metric format
and displays it in the Explorer under the following Resource:
<Domain>|<Host>|<Process>|<Agent>|WLDF|
Introscope converts Data Accessor “Columns” using the following method:
• key and value information is displayed
• key/value pairs are placed in alphabetical order in the Introscope-generated
Metrics.
The following example shows the syntax used:
<Domain>|<Host>|<Process>|<Agent>|WLDF|<domain
name>|<key1>=<value1>|<key2>=<value2>:<metric>
For example, this table shows the information for the BYTECOUNT Column from the
HTTPAccessLog Data Accessor:
Domain name
Key/Value Pairs
Metric Names
WebLogic
Name=HTTPAccessLog,
Type=WLDFDataAccessRuntime=Accessor,
BYTECOUNT
WLDFRuntime=WLDFRuntime
The Data Accessor information in the table above would be converted to the following
Introscope Metric:
<Domain>|<Host>|<Process>|<Agent>|WLDF|Weblogic|Name=HTTPAccessLog
|Type=WLDFDataAccessRuntime=Accessor|WLDFRuntime=WLDFRuntime:BYTECOUNT
Note that the key/value pairs are displayed alphabetically in the Introscope Metric.
Page 188
Advanced WebSphere Performance Data
Obtaining WLDF Data
No additional Introscope configuration is required to obtain WLDF data. However, you do
need to configure a WebLogic Startup Class in the WebLogic 9.0 Administrative Console.
See Creating a WebLogic Startup Class, page 105 for more information.
Introscope can provide WebSphere performance data by extracting WebSphere
performance Metrics via the PMI interface provided with WebSphere 4.0 and higher.
You must first enable PMI data collection in WebSphere before the data will be available
to Introscope. In WebSphere, all performance monitor settings are off by default.
These PMI Metrics can then be displayed as Introscope Metrics. Users can filter which
Metric categories to bring into Introscope, depending on their needs.
To begin collecting these Metrics, perform the following actions:
• turn on Performance Monitor Settings in WebSphere
• enable PMI settings in Introscope Agent profile
• configure an Introscope Custom Service in WebSphere
Turning on Performance Monitor Settings in WebSphere
Turning on Performance Monitor Settings in WebSphere 6.0/5.0.x
Please refer to the WebSphere 6.0/5.0.x documentation for instructions on enabling
Performance Monitoring Settings, and enabling Performance Monitoring for each desired
Metric category.
To enable PMI information, you will also need to configure a Custom Service in
WebSphere. See Configuring a Custom Service in WebSphere, page 116.
Modifying Java 2 Security Policy (WebSphere 6.0/5.0.x only)
If you are running WebSphere 5.0.x, you must modify the Java 2 Security Policy.
♦
lines:
// 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:
Page 189
1.
Open the WebSphere Administrative Console.
2.
Select the server you'd like to configure.
3.
Click the Services tab.
Page 190
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 Collection
Once 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.
2.
Page 191
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.
WebSphere 4.0 PMI Categories
WebSphere 5.0.x PMI Categories
introscope.agent.pmi.enable.threadPool=true
introscope.agent.pmi.enable.threadPool=true
introscope.agent.pmi.enable.servletSessions=true
introscope.agent.pmi.enable.servletSessions=true
introscope.agent.pmi.enable.connectionPool=true
introscope.agent.pmi.enable.connectionPool=true
introscope.agent.pmi.enable.bean=false
introscope.agent.pmi.enable.bean=false
introscope.agent.pmi.enable.transaction=false
introscope.agent.pmi.enable.transaction=false
introscope.agent.pmi.enable.webApp=false
introscope.agent.pmi.enable.webApp=false
introscope.agent.pmi.enable.jvmRuntime=false
introscope.agent.pmi.enable.jvmRuntime=false
introscope.agent.pmi.enable.jvmpi=false
introscope.agent.pmi.enable.jvmpi=false
introscope.agent.pmi.enable.system=false
Note: For data to be provided to the
jvmpiModule, JVMPI must be turned on in
WebSphere.
introscope.agent.pmi.enable.cache=false
introscope.agent.pmi.enable.orbPerf=false
introscope.agent.pmi.enable.j2c=false
introscope.agent.pmi.enable.webServices=false
introscope.agent.pmi.enable.wlm=false
5.
For each high level Metric category you want to report, enter a value of true.
Note: Do not enable the j2c module. Certain metrics in this module cause the
Enterprise Manager to run out of memory.
6.
Save the changes.
7.
Viewing WebSphere Agent PMI Data
After 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
Page 192
Enterprise Manager Database Recording
The following screenshot shows an example of WebSphere PMI Metrics in the Explorer
tree.
The Enterprise Manager can send information to an external data store, either a database
or a flat file. You will need to connect the Enterprise Manager to a database if you plan to
send Introscope data to a database for later analysis by third-party analysis software.
Note: Historical data displayed in Historical Views is provided by SmartStor™, which
constantly captures Introscope data. A database is not required if you only want to
view historical data. SmartStor can be used concurrently with Persistent
Collections (either sent to a flatfile or a database), as its data collection is
unrelated to any external data store.
Page 193
Upgrading Database Schema Tables From Previous Versions
The database schema in Introscope 6.0.1 has not changed from version 5.0.2. If you are
upgrading a database from a version previous to 5.0, please consult the Introscope 6.0.1
Upgrade Guide. Then, configure the database settings using the instructions in Setting
Database Properties, page 195.
Configuring a New Enterprise Manager to Database Connection
For a new Introscope installation, follow the steps in these sections:
• Running Database Creation Script
• Setting Database Properties
Note: Database configuration is no longer performed as part of Introscope installation.
You will need the following items that you collected earlier:
• Database URL
• Appropriate database driver
• Database user name and password
For more information on database properties that you can change, see
IntroscopeEnterpriseManager.properties File, page 242.
Running Database Creation Script
This step is commonly done by a Database Administrator (DBA). If you are not the DBA
for your organization, ask your DBA to complete this step. The DBA can control how
database structures are set up by editing the database creation script.
To create the database tables:
♦
Run the database script for your database from those in the <Introscope home>/
examples/database directory.
• Oracle: oracle.sql
• Sybase: sybase.sql
• DB2: db2.sql
• DB2 on z/OS (OS/390): db2_zOS.sql
Note: DB2: If you run the DB2 script through the DB2 Command Center, make
sure the statement termination character is set to semicolon.
• generic: generic.sql
Generic scripts can be used as a template to create a database creation script for
your specific database version, if you are not using Oracle, DB2, or Sybase.
Note: While a generic script provides all necessary database schema, you may
need to make specific script syntax modifications to make it run on your
particular database. Please contact your Wily sales representative for more
assistance.
Page 194
Setting Database Properties
To configure the Enterprise Manager to write to the database:
1.
2.
3.
In the Database Settings section, set these variables to correspond with any
variables required to access your database:
— Database URL
— Database driver
— Database user name and password
Configurations will differ slightly depending on your database type. The following
table shows configuration examples for Oracle, DB2, Sybase and Microsoft Access for
the database properties in the IntroscopeEnterpriseManager.properties file:
TABLE 6. Database Properties in IntroscopeEnterpriseManager.properties file
Database
Type
Sample Configurations
Oracle with
Oracle driver
introscope.enterprisemanager.db.driver=oracle.jdbc.driver.OracleDriver
introscope.enterprisemanager.db.url=jdbc:oracle:thin:@myDB:PortID:SID
Sybase
introscope.enterprisemanager.db.driver=com.sybase.jdbc2.jdbc.SybDriver
introscope.enterprisemanager.db.url=jdbc:sybase:Tds:myHost:PortID/database
DB2 database
on local
machine
introscope.enterprisemanager.db.driver=COM.ibm.db2.jdbc.app.DB2Driver
DB2 database
on remote
machine
introscope.enterprisemanager.db.driver=COM.ibm.db2.jdbc.net.DB2Driver
introscope.enterprisemanager.db.url=jdbc:db2:databasename
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
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.
Page 195
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
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
• 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 Database
The Introscope installation also provides a sample Microsoft Access database (located at
<Introscope home>/examples/database/msaccess.mdb) which already has tables
created for Introscope to use.
Note: Microsoft Access is not supported by Wily for use with the Enterprise Manager in a
production deployment. The sample Microsoft Access database is provided for
demonstration and training purposes only.
To use the sample Microsoft Access database, you must set it up as an ODBC DSN to
make it available to Sun’s JDBC ODBC bridge.
• On Windows 2000, use Start > Settings > Control Panel > Administrative
Tools > Data Sources (ODBC). Name the data source WILY01.
Page 196
Optional Enterprise Manager Configurations
Running Enterprise Manager Commands
In the Enterprise Manager terminal window, you can enter the following commands:
Command
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
Your 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
Page 197
Configuring Scheduled Export of Data
To configure scheduled export of flat file data based on time:
1.
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.
Page 198
Workstation Options
Defining Explicit Table Qualifier
By default, the Enterprise Manager assumes that the Introscope tables are located in the
tablespace associated with the username specified by the
introscope.enterprisemanager.db.username property in the Enterprise
Manager properties file.
However, in some deployments the DBA may have created tables in some location other
than the default schema associated with the username login. In this case, you can now
define an explicit table qualifier in Introscope so that the Enterprise Manager will specify
a fully-qualified table name when it accesses these tables. This step should be performed
by your 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.
3.
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.
6.
Workstation Options
Workstation Logging Options
The following sections describe Workstation logging options.
Running Workstation in Verbose Mode
Running the Workstation in verbose mode records details to the log, which is helpful in
debugging.
To run the Workstation in verbose mode:
1.
Open the file, IntroscopeWorkstation.properties.
Page 199
Optional ProbeBuilder Configurations
2.
In the property, log4j.logger.Workstation, replace “INFO” with the
following:
3.
Save changes.
Redirecting Workstation Output to a File
To redirect Workstation output to a file:
1.
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.Log4JSev
erityLevel,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 Firewall
This section describes how to connect a Workstation outside a firewall to an Enterprise
Manager that is behind one.
Workstations initiate connections on the Enterprise Manager port defined in the setting,
introscope.enterprisemanager.port.workstation.rmi (default value is 4500)
in the file, <Introscope home>/config/
IntroscopeEnterpriseManager.properties. Whichever port is defined in this
property must also be opened in the firewall.
Workstations also connect to an additional port in order to establish a secure connection
during user authentication. This port can be configured in the property,
introscope.enterprisemanager.port.workstation.rmi.secure in the
IntroscopeEnterpriseManager.properties file. The default value is 4550.
Whichever port is defined in this property must also be opened in the firewall.
You can disable the second port by setting the
introscope.enterprisemanager.workstation.disableSecureConnection
property to true. However, if you disable the secure port, usernames and passwords will
be sent unencrypted over the network.
Optional ProbeBuilder Configurations
Integrating ProbeBuilder into the Build Process
In your build cycle, you will want to run the ProbeBuilder after compiling classes and
before running qualification tests, as follows:
Page 200
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 Introscopeenabled classes in the appropriate place.
ProbeBuilder Log
The ProbeBuilder creates a log file that contains ProbeBuilder Directives used and Probes
added to the Java Application.
The location of the ProbeBuilder log file is determined by where you specify Java classes
with the ProbeBuilder Wizard or the with the Command-Line ProbeBuilder. For a directory,
the log file is located inside the destination directory. For a file, the log file is located next
to the destination file.
The ProbeBuilder log file is called:
<original-directory-or-original-file>.probebuilder.log
<original-directory> or <original-file> is the Java class location that you specify with the
ProbeBuilder Wizard or with the Command-Line ProbeBuilder.
Only the most recent log is kept. Any prior log file is overwritten.
AutoProbe ProbeBuilder Log
In addition, the AutoProbe log file name can be set in the IntroscopeAgent.profile
file with the property:
introscope.autoprobe.logfile=AutoProbe.log
The default value is AutoProbe.log.
AutoProbe Logging When Using Agent Resource Configuration
The AutoProbe.log file is generated relative to the location of the
IntroscopeAgent.profile file. When loading the IntroscopeAgent.profile from
a resource on a classpath, AutoProbe will be unable to write to the AutoProbe.log file,
because the IntroscopeAgent.profile file is located within a resource.
Miscellaneous Installation Options
Java2 Security Policy
If you are using Java2, you may need to modify the Java security policy file that is used
with your managed application. If there are insufficient grants to Introscope-enabled
code, you may get security exceptions and, likely, your application will not work correctly.
Page 201
16 Database Configuration and Reporting
This chapter describes the structure of Introscope® database tables, how to query
information, and the sample reports provided with Introscope.
This chapter is intended for a DBA or a database reporting expert who is familiar with SQL
and database reporting tools.
• Introscope 6.0.1 Database Schema
• Database Tables
• Database Record Types
• Querying Introscope Database Tables
• Creating Reports from Introscope Data
Other information relevant to database reporting can be found in these sections of the
Introscope Installation Guide:
• Information on configuring your database with Introscope can be found in
Enterprise Manager Database Recording, page 193.
• Information on upgrading your database to work with Introscope 6.0.1 can be
found in the Introscope 6.0.1 Upgrade Guide.
• Information on sending historical data to the database can be found in the section,
Sending Introscope Data to External Data Store With Persistent Collections, in the
chapter, Configuring Monitoring Logic, in the Introscope 6.0.1 Workstation Guide.
• Information on database settings can be found in:
— Introscope Enterprise Manager.lax File, page 247
— IntroscopeEnterpriseManager.properties File, page 242
— LDAPAuthenticationExtension.properties, page 252
• Database creation and upgrade scripts are located in <Introscope home>/
examples/database.
Page 202
Introscope 6.0.1 Database Schema
Introscope 6.0.1 Database Schema
Note: The database schema has not changed for 6.0.1.
Page 203
Database Tables
Database Tables
This document describes the underlying format used for database recording.
The version table maps a database schema version (not to be confused with an
Introscope version) to the corresponding index table.
The index table for a specific schema version maps logical names for the schema version
into the actual names of the tables in the database.
Each table has a unique index created for the fields listed in bold.
The view, WT_METRIC_VIEW, should always be used when accessing Metric data from the
database. Wily makes every effort to maintain the view with each release. The raw tables
are more likely to change between releases and should not be used directly for accessing
Metric data.
Version Table
The name for the version table is WT_VERSIONLIST.
The version table has two columns:
• SCHEMA_VERSION (INTEGER)
• INDEX_NAME (VARCHAR)
For each schema version there is an entry mapping the version number to the name of
the index table for that schema version.
You may want multiple schemas to support compatibility between Introscope versions.
Index Table
The default name for the index table is WT_INDEX.
The index table has two columns:
• LOGICAL_NAME (VARCHAR)
• ACTUAL_NAME (VARCHAR)
The primary purpose of the index table is to map logical names to the actual table names
used in the database. The logical names and the default actual names for this schema
version are shown in the following table.
Logical Name
Default Actual Name
propertytable
WT_PROPERTY
agenttable
WT_AGENT
resourcetable
WT_RESOURCE
metricnametable
WT_METRIC_NAME
metrictable
WT_METRIC
resourcemetrictable
WT_RESOURCE_METRIC
Page 204
Database Tables
Logical Name
Default Actual Name
recordtypetable
WT_RECORD_TYPE
metadatatable
WT_METADATA
tempquerytable_1
WT_TMP_Q_1
tempquerytable_2
WT_TMP_Q_2
tempquerytable_3
WT_TMP_Q_3
tempquerytable_4
WT_TMP_Q_4
tempquerytable_5
WT_TMP_Q_5
Property Table
The default name for the property table is WT_ PROPERTY.
The property table has two columns:
• PROPERTY_NAME (VARCHAR)
• PROPERTY_VALUE (VARCHAR)
The property table is a mapping of assorted name-value pairs which we wish to keep
persistent in the database. Current entries in the properties table include:
• varchar limits for each of the above tables with variable length string fields
• generated unique Agent IDs when non-unique Fully-Qualified Agent names are
encountered
• whether the database supports large integer values
Agent Table
The default name for the Agent table is WT_AGENT.
The Agent table has the following columns:
• AGENT_ID (INTEGER)
• HOST (VARCHAR)
• PROCESS (VARCHAR)
• FIRST_METRIC_TS (TIMESTAMP)
• LAST_METRIC_TS (TIMESTAMP)
• AGENT_NAME (VARCHAR)
• DOMAIN_NAME (VARCHAR)
The Agent table maps each distinct Domain, host, process and Agent name combination
to a unique ID.
The Agent Name is the name given by a user for a Fully-Qualified Agent. Several Agent
IDs may be associated with a single Agent Name.
Page 205
Database Tables
Resource Table
The default name for the resource table is WT_RESOURCE.
The resource table has three columns:
• RESOURCE_ID (INTEGER)
• SEGMENT_INDEX (INTEGER)
• SEGMENT_TEXT (VARCHAR)
The resource table maps the variable length segments of the Metric into a list, one
segment per entry. All entries with the same resource ID can be combined (ordered by
segment index) to generate the associated variable length resource.
Metric Name Table
The default name for the Metric name table is WT_METRIC_NAME.
The Metric name table has three columns:
• METRIC_NAME_ID (INTEGER)
• METRIC_NAME (VARCHAR)
• METRIC_TYPE (INTEGER)
The Metric name table maps each distinct Metric name and type pair to a unique ID.
Metadata Table
The default name for the metadata table is WT_METADATA.
The metadata table has three columns:
The metadata table saves the Metric and Agent structure for Metrics whose values have
been persisted to the value table.
Metric Table
The name for the Metric table is WT_METRIC.
The Metric table has 24 columns:
• RESOURCE_METRIC_ID (INTEGER)
• RECORD_TYPE_ID (INTEGER)
• PERIOD (INTEGER)
• INTENDED_END_TS (TIMESTAMP)
• ACTUAL_START_TS (TIMESTAMP)
Page 206
Database Tables
• ACTUAL_END_TS (TIMESTAMP)
• VALUE_COUNT (BIGINT)
• VALUE_TYPE (INTEGER)
• INTEGER_VALUE (BIGINT)
• INTEGER_MIN (BIGINT)
• INTEGER_MAX (BIGINT)
• FLOAT_VALUE (FLOAT)
• FLOAT_MIN (FLOAT)
• FLOAT_MAX (FLOAT)
• STRING_VALUE (VARCHAR)
• DATE_VALUE (TIMESTAMP)
• INTERVAL_COUNTER (INTEGER)
• SYS_VALUE_COUNT (VARCHAR)
• SYS_LONG_VALUE (VARCHAR)
• SYS_LONG_MIN (VARCHAR)
• SYS_LONG_MAX (VARCHAR)
The Metric table contains the actual collected data. There is one record for every data
point written to the database.
AGENT_ID (INTEGER)
RESOURCE_ID (INTEGER)
METRIC_NAME_ID (INTEGER)
The Agent ID, resource ID, and Metric name ID all reference the associated records in
their corresponding tables.
RESOURCE_METRIC_ID (INTEGER)
The Resource Metric ID references the associated record in the WT_RESOURCE_METRIC
table.
RECORD_TYPE_ID (INTEGER)
The Record Type ID references the associated record in the WT_RECORD_TYPE table.
PERIOD (INTEGER)
The period is the interval at which this collection is recorded in seconds.
INTENDED_END_TS (TIMESTAMP)
The intended end timestamp is the master clock time at which this record was scheduled
to be written.
ACTUAL_START_TS and ACTUAL_END_TS (TIMESTAMP)
The actual start timestamp is when the collection actually started aggregating data
points.
Page 207
Database Tables
The actual stop timestamp is when the collection actually stopped aggregating data
points.
VALUE_COUNT (BIGINT)
The value count is the number of data points accumulated in the record – only relevant
for numeric data that can be accumulated. If the database does not support large integral
values (large integral values refer to 8-byte signed integers), the count is stored in the
SYS_VALUE_COUNT field.
VALUE_TYPE (INTEGER)
The value type is the actual underlying type of the data. Unlike the Metric type which
encodes all the possible type information about a piece of data, the value type is one of
six values: Integer = 1, Long = 2, Float = 3, Double = 4, String = 5, and Date = 6.
INTEGER_VALUE (BIGINT)
INTEGER_MIN (BIGINT)
INTEGER_MAX (BIGINT)
The integer value, min and max columns store either integer or long data (Integer data
consists of 4-byte signed integers while long data consists of 8-byte signed integers). If
the type is long and the database does not support large integral values, the data is
stored in the SYS_LONG_VALUE, SYS_LONG_MIN and SYS_LONG_MAX columns instead.
FLOAT_VALUE (FLOAT)
FLOAT_MIN (FLOAT)
FLOAT_MAX (FLOAT)
The float value, min and max columns store either float or double data. (Float data
consists of 4-byte floating point values while double data consists of 8-byte values.)
STRING_VALUE (VARCHAR)
The string value stores the actual data for string types.
DATE_VALUE (TIMESTAMP)
The date value stores the actual value for timestamps.
INTERVAL_COUNTER (INTEGER)
The interval counter assigns a unique ID to every record written in a given clock
quantum.
Page 208
Database Record Types
SYS_VALUE_COUNT (VARCHAR)
SYS_LONG_VALUE (VACHAR)
SYS_LONG_MIN (VARCHAR)
SYS_LONG_MAX (VARCHAR)
The SYS_* columns are used to store long integral values as strings in order to support
databases which do not have a corresponding datatype. (Microsoft Access is the main
database which does not support 8-byte integer values.)
Resource Metric Table
The default name for the Resource Metric table is WT_RESOURCE_METRIC.
The Resource Metric table has three columns:
• RESOURCE_METRIC_ID (INTEGER)
• RESOURCE_METRIC (VARCHAR)
• METRIC_TYPE (INTEGER)
The Resource Metric Table saves the Metric structure of every Agent that connects,
regardless of what data gets stored to the database. This data is used primarily for
mounting historical Agents.
RESOURCE_METRIC (VARCHAR)
The resource Metric is the name of the Metric without the additional host|process|Agent
information. The same string can be rebuilt from the resource and Metric name tables.
Record Type Table
The default name for the Record Type table is WT_RECORD_TYPE.
The Record Type Table has two columns:
• RECORD_TYPE_ID (INTEGER)
• RECORD_TYPE (VARCHAR)
The Record Type Table stores record type descriptors used by each WT_METRIC data row.
RECORD_TYPE (VARCHAR)
The record type is a simple representation of the type of the data point intended to
simplify querying. For more information on record types, see Database Record Types,
page 209.
Database Record Types
Introscope includes database record types. This makes querying and reporting on the
historical data easier by identifying records as being of a type, in addition to being
records for a particular Metric.
For example, the Metric
MyDomain|MyHost|MyProcess|MyAgent|Servlets|MyServlet7|Average
Response Time(ms) may be in the database and available to query based on the FullyIntroscope® 6.0.1 Installation & Configuration Guide (9/15/05)
Page 209
Querying Introscope Database Tables
Qualified Metric name as well as its parts. However, it is easier to query if there is a type
like Servlet Average Response Time which can be used in query criteria. This would
identify all servlets’ average response time records easily.
Introscope comes with default database record types. You can set custom database
record types in the file, <Introscope home>/config/
CustomDBRecordTypes.properties. Any record type mappings specified in this file
take precedence over the defaults. For more information on custom datatypes, see
LDAPAuthenticationExtension.properties, page 252.
Querying Introscope Database Tables
This section contains information on querying Introscope database tables.
The view used for queries is typically WT_METRIC_VIEW.
Queries should always include a value for PERIOD, as the same Metric may have different
records written with different PERIODs that cover the same interval of time (e.g. oneand five-minute records).
The RECORD_TYPE column can be useful for selecting records which are well-described
by record type definitions.
The RESOURCE_METRIC column can be useful for selecting records based on their simple
Metric name.
The INTENDED_END_TS should be used to compare values from different Metrics against
other ones, since it is an “ideal”, exact, rounded time, whereas the ACTUAL_END_TS may
be slightly different.
When considering data over an interval of time, generally the WHERE conditions around
the INTENDED_END_TS values should be similar to the following so that data for the
interval is accurately queried. Be sure to include the end time and exclude the start time.
AND
INTENDED_END_TS > start_time_of_interval
INTENDED_END_TS <= end_time_of_interval
Records which hold average data have both the average and the number of values used
to determine the average in the VALUE_COUNT column. This value is useful in order to
weigh averages which combine Metric records. A simple average of INTEGER_VALUEs
would not correctly account for the different number of values combined to calculate the
average. An intermediate result of INTEGER_VALUE * VALUE_COUNT needs to be
computed and added together. That sum needs to then be divided by the sum of the
VALUE_COUNTs used to get the weighted average.
The VALUE_COUNT on average data records can also be used to calculate rates more
accurately (in floating point values) and in different units than responses/sec (like
responses per hour). This can be accomplished by dividing the VALUE_COUNT by the
difference between ACTUAL_START_TS and ACTUAL_END_TS.
The SYS_* columns may be used in numeric calculations if the values can be converted to
numbers.
Page 210
Creating Reports from Introscope Data
Numeric data is stored as numbers in this release only in the INTEGER columns. Large
integer values may or may not be stored in the INTEGER columns, depending on the
capabilities of the database.
Creating Reports from Introscope Data
To create database reports from Introscope data, you can use:
• SQL
• your 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 Reporting
Introscope provides built-in reporting capabilities, accessible directly from the
Workstation. For more information on using these built-in reports, see the chapter,
Introscope Reporting, in the Introscope 6.0.1 Workstation Guide.
Page 211
17 ProbeBuilder Directives
This chapter describes how to create and modify ProbeBuilder Directives.
• Introduction to Directives
• Default ProbeBuilder Directives Files
• Modifying Default ProbeBuilder Directives
• Creating Custom Tracers
• Creating Advanced Custom Tracers
• Directive Keywords
• Updating Introscope With Modified or New ProbeBuilder Directives Files
Page 212
Introduction to Directives
Introduction to Directives
ProbeBuilder Directives tell the ProbeBuilder how to add Probes, such as timers and
counters, to Java components, to create an Introscope-enabled application.
Introscope includes a set of default Directives that are generic to many Java systems, as
well as those that can extend support of default Tracers for WebLogic, WebSphere and
SUN ONE. You can create your own custom Directives that track classes and methods
unique to your application.
Components Tracked
By default, the ProbeBuilder supports tracking of the following:
• Oracle JDBC
• JSP Tag Libraries
• JSP IO Tag Libraries
• JSP DB Tag Tag Libraries
• Struts
• Servlets
• Java Server Pages (JSPs)
• Enterprise JavaBeans (EJBs)
• Java Database Connectivity (JDBC)
• Network Sockets
• Remote Method Invocation (RMI)
• Extensible Markup Language (XML)
• Java Transaction API (JTA)
• Java Naming and Directory Interface (JNDI)
• Java Message Service (JMS)
• Common Object Request Broker Architecture (CORBA)
• User Datagram Protocol (UDP)
• File Systems
• Threads
• System Logs
• Thrown and Caught Exceptions (off by default)
Single-Metric Tracers and Tracer Groups
In a Directives file, each line that causes the reporting of Metrics is called a Tracer. Tracers
can track methods, classes, and sets of classes.
A single-Metric Tracer causes the reporting of a specific Metric for a specific method. The
smallest unit that Introscope can track is a method.
Page 213
Default ProbeBuilder Directives Files
By default, Introscope traces many common Java and J2EE components using Tracer
Groups. A Tracer group consists of a set of Tracers that is applied to a set of classes. For
example, there are Tracer Groups which report the response times and rates for all RMI
classes.
You can turn Tracer Groups on or off, and/or add new classes to the set affected by the
Tracer Group. See the section, Modifying Default ProbeBuilder Directives, page 215.
Only Defined Methods Traced
Introscope can only track methods in classes that are seen by Introscope and that are
explicitly defined (not inherited). There are two ways that you can ensure that a method
is tracked:
• Explicitly define the method in the class (it can be a simple wrapper around the
inherited method)
• Trace the superclass that contains the method.
ProbeBuilder Directive Files
There are two kinds of files used to specify ProbeBuilder Directives. You specify one or
more of these files to tell the ProbeBuilder where to find the Directives to use.
• ProbeBuilder Directive files (.pbd files)
A ProbeBuilder Directives file contains ProbeBuilder Directives.
• ProbeBuilder List files (.pbl files)
A ProbeBuilder list file contains a list of ProbeBuilder Directives files. Different .pbl
files can reference the same .pbd files.
Multiple ProbeBuilder Directive files can be specified and are all used together.
Default System ProbeBuilder Files
If you are using AutoProbe, the relevant .pbd and .pbl files for your specific application
server are placed in the <appserver home>/wily directory when you install AutoProbe.
Introscope provides basic system ProbeBuilder Directives files. These files should
generally not be edited, but there are some modifications you can perform. See Modifying
Default ProbeBuilder Directives, page 215.
Custom ProbeBuilder Directives Files
While system ProbeBuilder Directives files track basic information, you can customize
Introscope to track any classes or methods to obtain specific information about your
application. See Creating Custom Tracers, page 220 and Creating Advanced Custom
Tracers, page 225.
Default ProbeBuilder Directives Files
Introscope provides a set of ProbeBuilder directives files that gather basic system
information. ProbeBuilder directives files included with the Agent for a specific application
server will contain ProbeBuilder directives files specific to that application server.
Page 214
Modifying Default ProbeBuilder Directives
Full and Typical ProbeBuilder Directives Sets
Tracer groups cause the reporting of information about a set of classes.
Tracer groups are found in PBD files, and referred to in PBL (ProbeBuilder list) files. There
are two sets of PBL files available with each Agent installer:
• Full (default)= references PBD files in which most Tracer Groups in PBD files are
turned on. Introscope uses this set by default to demonstrate full Introscope
functionality.
• Typical= a subset of Tracer Groups in the referenced PBD files are turned on. The
typical set includes common settings, and is the set you can customize for a
particular environment.
Note: For instructions on switching between full and typical .PBL files, see Switching
Between “Full” and “Typical” Tracing Options, page 175.
The ProbeBuilder Directive files included with Introscope generally should not be edited.
However, the Tracer Groups in the files can be modified in the toggles.pbd files
(explained in the following section) by:
• turning off Tracer Groups to save on system overhead (and turn back on)
• adding Classes to a Tracer Group
Default Tracer Groups and Toggles Files
The <appserver>-full.pbl and <appserver>-typical.pbl files reference
toggles-full.pbd and toggles-typical.pbd files. The Tracer groups are turned on
or off within the toggles-full.pbd or toggles-typical.pbd files.
In the toggles-full.pbd file, most of the Tracer groups are turned on by default. In
the toggles-typical.pbd file, only a subset of Tracer groups are turned on.
Page 215
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
HTTP servlet service responses
on
on
StrutsTracing
Execution times of actions in the
Struts framework
on
on
InstanceCounts
Counts number of instances of
object type identified with Tracer
group.
on
on
File system bytes written and
read
on
off
Note: If you are using
Application Server
AutoProbe, you will need to
turn on the following Tracer
group:
HTTPAppServerAutoProbeSer
vletTracing
Note: Nothing will be traced
until classes are identified
with this Tracer group.
FileSystemTracing
Page 216
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
Tracer Groups report information only when turned on (uncommented). Tracer groups are
activated with the keyword TurnOn.
Turning on Toggles To Gather Additional Metric Information
The following three toggles, when turned on, will collect additional Metrics across all APIs.
Name
Definition
Default
Full
Setting
Default stalled method
Tracers
Stalled method tracing
on
on
DefaultConcurrentInvocatio
nTracing
Concurrent invocation
information
on
off
Previous rate Metrics
Metric information by rate
(not interval count)
off
Default
Typical
Setting
Page 217
Turning Tracer Groups On or Off
Turning a Tracer Group On or Off
To turn a Tracer Group on:
1.
Locate the toggles-full.pbd or toggles-typical.pbd file (depending on which
file type (<appserver>-full.pbl or <appserver>-typical.pbl is in use by AutoProbe or
Agent). These files are found within the <appserver home>/wily directory or
<Introscope home>/config/systempbd directory.
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
Page 218
Agent Initialization
The Agent Initialization instrument point directive does not cause additional overhead and
is turned on by default in both full and typical PBD sets.
#InstrumentPoint: AgentInitialization
If multiple ProbeBuilder Directive files are used, any settings (such as Tracer Groups,
Skips, InstrumentPoints, Custom Method Tracers) turned on in any file take effect.
Adding Classes to a Tracer Group
You can turn on tracing for a particular class by adding the class to an existing Tracer
group. To identify a class as being part of a Tracer group, use one of the Identify
keywords.
For example, to add the class, com.myCo.ejbentity.myEJB1, to the Tracer group,
EntityBeanTracing:
IdentifyClassAs: com.myCo.ejbentity.myEJB1 EntityBeanTracing
The Identify keywords are:
• IdentifyInheritedAs
• IdentifyClassAs
• IdentifyCorbaAs
For details on the Identify keywords, see Directive Keywords, page 227.
EJB Subclass Tracing
By default, entity and session EJB-related Directives add Probes only for EJBs that
directly and explicitly implement the entity, session, or message-driven EJB interfaces.
Often, an 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:
Page 219
Creating Custom Tracers
mySessionEJB implements javax.ejb.SessionBean
mySessionEJBsubclass1 extends mySessionEJB
mySessionEJBsubclass1a extendsmySessionEJBsubclass1
mySessionEJBsubclass1b extendsmySessionEJBsubclass1
mySessionEJBsubclass2 extends mySessionEJB
The Tracer group, SessionBeanTracing, causes the tracking of mySessionEJB:
The following Tracer traces mySessionEJBsubclass1 and mySessionEJBsubclass2.
IdentifyInheritedAs: mySessionEJB SessionBeanTracing
The following Tracer traces mySessionEJBsubclass1a and mySessionEJBsubclass1b.
IdentifyInheritedAs: mySessionEJBsubclass1 SessionBeanTracing
Note: This example does not use packages. If your code is in a package, it needs to
include the package name with the class name. See Directive Keywords, page 227.
Custom Tracers are constructed using a specific syntax and keywords. This section
describes how to construct custom Tracers. Choose methods to trace carefully. More
methods traced means more overhead.
Custom Tracers must be saved in a custom Directives file (.pbd). Introscope includes an
example file with Custom Tracers in it, located in <Introscope home>/examples/
CustomTracerExample.pbd. You can use this file as a template for your own custom
.pbd file.
Custom Tracers and Keywords
To construct a Tracer, you must define:
• which method or class to trace
• information to collect about the method or class
There are four directives available for custom tracing:
• TraceOneMethodOfClass - traces a specified method in the specified class.
• TraceAllMethodsOfClass - traces all methods in the specified class.
• TraceOneMethodIfInherits - traces one method in all direct subclasses or direct
interface implementations of the specified class or interface.
• TraceAllMethodsIfInherits - traces all methods in all direct subclasses or direct
interface implementations of the specified class or interface.
Note: Only concrete, implemented methods can be traced and report Metric data while
running. An abstract method specified in a custom Tracer results in no Metric data
being reported.
You must use a specific syntax when constructing Custom Tracers, or Introscope® will not
be able to recognize and process your Tracers, and won’t collect the desired information.
This syntax is described in the next section.
Page 220
Tracer Syntax
A Tracer is composed of a directive and information about the method or class to trace, in
the following format:
<directive>: <class> <method> <Tracer-name> <metric-name>
TABLE 9. Tracer Components
Tracer component
Definition
<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.)
Specifies how the method is to be traced. See Table 10 on page 221 for
descriptions of tracer names.
<Tracer-name>
To use these Tracers with Blame Technology, use the Tracers with
names prefixed with Blamed. (See Custom Tracers in Blame
Technology, page 224.)
Controls how the collected data is displayed in the Workstation.
The following examples describe the three ways to specify the name
and location of a Metric at different levels of the Metrics tree.
•
•
•
<metric-name>
metric-name
The Metric appears immediately inside the Agent.
resource:metric-name
The Metric appears inside one Resource (folder) below the Agent.
resource|sub-resource|sub-sub-resource:metric-name
The Metric appears more than one Resource (folder) level deep
below the Agent, use pipe characters (|) to separate the
Resources.
The following table describes tracer names and what they trace.
TABLE 10. Tracer Names
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
Page 221
Average CPU time (in milliseconds) used during
method execution and reports it under <metricname> in the Metrics tree.
Note: This tracer requires a platform monitor on
MethodCPUTimer
the supported platform (either AIX 5.2 or RedHat
Enterprise Linux 3.0).
Average CPU time (in milliseconds) used during
method execution and also collects information
about runtime interactions between components.
Note: This tracer requires a platform monitor on
BlamedMethodCPUTimer
the supported platform (either AIX 5.2 or RedHat
Enterprise Linux 3.0).
PerIntervalCounter
Number of invocations per interval. This interval will
change based on the view period of the consumer of
the data (for example, the Preview pane in the
Explorer, and the Persistent Collection that records it
to a database). It is reported under <metric-name>
in the Explorer tree.
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
Page 222
Custom Method Tracer Examples
The following are Tracer examples found in the CustomTracerExample.pbd file. Quotes
are used around the Metric names in these examples because of spaces in the Metric
names.
Example Average Tracer
This Tracer tracks the average execution time of the given method in milliseconds.
TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search
BlamedMethodTimer "Petstore|Catalog|search:Average Method Invocation
Time (ms)"
Example Rate Tracer
This Tracer counts the number of times the method is called per second, and report this
rate under the specified Metric name.
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.
PerIntervalCounter "Petstore|Catalog|search:Method Invocations Per
Interval"
Example Counter Tracer
This Tracer counts the total number of times the method is called.
TraceOneMethodOfClass: com.sun.petstore.cart.ShoppingCart placeOrder
BlamedMethodTraceIncrementor "Petstore|ShoppingCart|placeOrder:Total
Order Count"
Example Combined Counter Tracers
These Tracers combine incrementor and decrementor Tracers to keep a running count.
TraceOneMethodOfClass: com.sun.petstore.account.LoginEJB login
MethodTraceIncrementor "Petstore|Account:Logged In Users"
TraceOneMethodOfClass: com.sun.petstore.account.LogoutEJB logout
MethodTraceDecrementor "Petstore|Account:Logged In Users"
Page 223
Custom Tracers in Blame Technology
Introscope’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:
Sockets
Input Bandwidth
Output Bandwidth
Servlets
Average Response Time
Responses Per Second
Responses Per Interval
Main Servlet
Called EJB
MyEJB
Average Method Invocation Time
Method Invocations Per Interval
Called Sockets
Input Bandwidth
Output Bandwidth
EJB
Average Method Invocation Time
Method Invocations Per Interval
MyEJB
Called JDBC
JDBC
Average Query Time
Queries Per Second
Page 224
Creating Advanced Custom Tracers
This section describes advanced custom Tracers:
• Advanced Single-Metric Tracers
— Signature Differentiation
— Metric-Name-Based Parameters
• Skips
• Combining Custom Tracers
Advanced Single-Metric Tracers
Signature Differentiation
Tracers can be applied to a method based on the method signature.
To trace a single instance of a method with a specific signature, append the signature to
the method name (including return type) specified using the internal method descriptor
format. For example, myMethod(Ljava/lang/String;)V traces the instance of the
method with a string argument and void return type.
For complete information about this format, see the Sun Java Virtual Machine
Specification, section 4.3.3, Method Descriptors, and section 4.3.2, Field Descriptors,
http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html.
Keyword-Based Substitution
Keyword-based substitution allows runtime substitution of values into the Metric name.
The parameters in the Metric name in the Tracer are substituted at runtime for the actual
values into the Metric name. This feature can be used with any directive.
TABLE 11. Keyword-based Substitution Parameters
Parameter
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
Note: If Introscope processes a class which does not have a package, it will replace
{packagename} with the string “<Unnamed Package>”.
Example 1:
If the Metric name for a Tracer in the pbd file is:
"{packagename}|{classname}|{method}:Response Time (ms)"
Page 225
and the Tracer is applied to method myMethod with a runtime class of myClass that is in
package myPackage, the resulting Metric name would be:
"myPackage|myClass|myMethod:Response Time (ms)"
Example 2:
If a Tracer with a Metric name in the .pbd file of
"{packageandclassname}|{method}:Response Time (ms)"
was applied to the same method, the resulting Metric name would be
"myPackage.myClass|myMethod:Response Time(ms)"
Note: Note the . between the package and class instead of the | in the first example.
Metric-Name-Based Parameters
You can create a single-method Tracer that creates a Metric name based on parameters
passed to a method using the TraceOneMethodWithParametersOfClass keyword.
TraceOneMethodWithParametersOfClass: <class-name> <method> <trace-classshorthand-name> <name>
Parameters can be used in the Metric name. This is accomplished by substituting the
value of parameters for placeholder strings in the Metric name. The placeholder strings to
use are “{#}” where # is the index of the parameter to substitute. The indices start
counting at zero. Any number of parameter substitutions can be used in any order. All
parameters are converted to strings before substitution into the Metric name. Object
parameters other than strings should be used with caution because they are converted
using the toString() method. If you are unclear about what string the parameter will be
converted to, you should refrain from using it in the Metric name.
Example:
A Web site uses a class named order, with a method named process. The method has
parameters for different kinds of orders, either book or music.
You can create a Tracer like this:
TraceOneMethodWithParametersOfClass: order process(LJava/lang/
string;)V MethodTimer “Order|{0}Order:Average Response Time (ms)”
This Tracer produces Metrics like these:
Order
BookOrder
Average Response Time (ms)
MusicOrder
Average Response Time (ms)
You can also use the TraceOneMethodWithParametersIfInherits keyword. For more
information on both keywords, see Directive Keywords, page 227.
Page 226
Directive Keywords
Skips
Certain packages and classes can be skipped by AutoProbe or ProbeBuilder by listing each
package or class to skip after SkipPackage: or SkipClass: as appropriate. By default,
Introscope Agent and fundamental Java classes and packages are skipped by AutoProbe
or ProbeBuilder. For more information, see Directive Keywords, page 227.
Combining Custom Tracers
You can use multiple Tracers that affect the same Metric, in effect combining them. This is
most commonly used with incrementors and decrementors.
Example:
This example creates a Metric named Logged-in Users. With a class user and methods
login and logout, create the following Tracers:
TraceOneMethodOfClass user login MethodTraceIncrementor “Logged-in
Users”
TraceOneMethodOfClass user logout MethodTraceDecrementor “Logged-in
Users”
This increments the Metric Logged-in Users when someone logs in and decrements
Logged-in Users when someone logs out.
Counting Object Instances
The new Tracer Group, InstanceCounts, counts the number of instances of the
particular object types associated with it (for information on associating object types with
the InstanceCounts Tracer Group using the standard IdentifyClassAs and
IdentifyInheritedAs directives, see Adding Classes to a Tracer Group, page 219). Any
instances explicity allocated in your code will be counted. Subtypes will also be counted.
Objects created through different mechanisms, such as deserialization or cloning, might
not be counted. Tracing using this Tracer Group could potentially incur incremental
performance (and memory) impact, depending on the number of instances counted.
Directive Keywords
This section contains a list of Introscope Directive keywords. Specifics for using these
keywords with arguments to create Directives are described in this section. Two Tracers,
StalledMethodTracer and ThresholdMethodTimer use their own keywords (see Threshold
ProbeBuilder Action Keywords, page 230).
The table below defines parameters used in the Directive keyword syntax.
TABLE 12. Directive Parameters
Parameter
Value
<package-name>
Period-separated, fully-qualified package name, such as
<class-name>
java.lang.
Period-separated, fully-qualified class name, such as
java.lang.Object.
Page 227
Directive Keywords
<Tracer-name>
Name of Tracer to use, one of the following in this list:
MethodTimer
BlamedMethodTimer
PerIntervalCounter
MethodRateTracer
BlamedMethodRateTracer
MethodTraceIncrementor
BlamedMethodTraceIncrementor
MethodTraceDecrementor
BlamedMethodTraceDecrementor
ConcurrentInvocationCounter
<method>
Method name with an optional descriptor, such as
Main([Ljava/lang/String;)V).
Main or
<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.
ProbeBuilder Skip Keywords
The two Skip keywords cause the ProbeBuilder to skip over a class or a package.
SkipClass: <class-name>
Prevents the listed class from being Introscope-enabled.
Only the specific class is skipped.
SkipPackage: <package-name>
Prevents the listed package from being Introscope-enabled.
All classes in the listed package are skipped.
ProbeBuilder Action Keywords
The keywords below cause the ProbeBuilder to take action:
IdentifyClassAs: <class-name> <Tracer-group>
Adds the specific class to the specified Tracer group.
IdentifyCorbaAs: <Tracer-group>
Adds all CORBA classes to the specified Tracer group.
IdentifyInheritedAs: <class-name> <Tracer-group>
Adds all direct subclasses or interfaces to the specified Tracer group.
If a class is specified, it adds all direct subclasses. If an interface class name is
specified, it adds all direct implementers of that interface.
InstrumentPoint: <ThrowException> or <CatchException>
ThrowException
Page 228
Directive Keywords
Track all exceptions at the location where they are thrown.
High performance impact, turned off by default.
CatchException
Track all exceptions at the location where they are caught.
High performance impact, turned off by default.
TraceAllMethodsIfInherits: <class-name> <Tracer-name> <name>
Traces all methods in direct subclasses or implementers of the named interface
with the given Tracer class and Metric name.
Only concrete, implemented methods are Introscope-enabled and report Metric
data while running.
The result is a single aggregate Metric for all methods traced. To get detail
results for particular methods, use one of the TraceOneMethod keywords.
An abstract method specified in a Tracer results in no Metric data being
reported.
TraceAllMethodsOfClass: <class-name> <Tracer-name> <name>
Traces all methods in the named class with the given Tracer class and Metric
name.
data while running.
The result is an aggregate Metric for all methods traced. To get detailed results
for particular methods, use one of the TraceOneMethod keywords.
reported.
TraceOneMethodOfClass: <class-name> <method> <Tracer-name> <name>
Traces the specific method in the named class with the given Tracer class and
Metric name.
data while running.
reported.
TraceOneMethodWithParametersIfInherits: <class-name> <method> <Tracername> <name>
Traces the specific method in direct subclasses or implementers of the named
superclass or interface with the given Tracer class and Metric name. Only
concrete, implemented methods are Introscope-enabled and report Metric data
while running. An abstract method specified in a Tracer results in no Metric data
being reported. The specified method name must include a signature.
The Metric name can include strings like “{#}” that are substituted with the
value of the parameter at index # (where 0 is the first parameter, 1 is the
second parameter, etc).
Page 229
Directive Keywords
TraceOneMethodWithParametersOfClass: <class-name> <method> <Tracername> <name>
Metric name.
data while running.
reported.
The specified method name must include a signature.
The Metric name can include strings like “{#}” that are substituted with the
value of the parameter at index # (where 0 is the first parameter, 1 is the
second parameter, etc).
TurnOn: <Tracer-group>
Enables the specified Tracer group.
There is no corresponding Directive to disable a Tracer group. To disable a
Tracer group, comment out the associated TurnOn Directive.
Threshold ProbeBuilder Action Keywords
The following directives, TraceOneMethodWithThresholdOfClass, and
TraceAllMethodsWithThresholdOfClass, only work with the following Tracers:
• StalledMethodTracer
• OverThresholdPerIntervalCounter
• UnderThresholdPerIntervalCounter
Action Keywords
TraceOneMethodWithThresholdOfClass: <class-name> <method> <Tracer-name>
<name> <threshold>
Metric name.
data while running.
reported.
TraceAllMethodsWithThresholdOfClass: <class-name> <Tracer-name> <name>
<threshold>
Traces all methods in the named class with the given Tracer class and Metric
name.
data while running.
The result is an aggregate Metric for all methods traced. To get detailed results
for particular methods, use one of the TraceOneMethod keywords.
Page 230
Updating Introscope With Modified or New ProbeBuilder Directives Files
reported.
Keyword Syntax
The table below defines parameters used in the keyword syntax for these specific
Directives.
TABLE 13. Threshold Directives Parameters
Parameter
<class-name>
Value
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:
StalledMethodTracer
ThresholdMethodTimer
<method>
Method name with an optional descriptor, such as
Main([Ljava/lang/String;)V).
Main or
<name>
Valid Metric name or Resource category depending on the specific Tracer
class, such as Resource|Sub-resource.
<threshold>
Length of threshold in milliseconds
Threshold Tracers
StalledMethodTracer traces the number of invocations of method which have exceeded
a user-defined threshold and have not finished. This number serves as an approximation
of the number of hung threads. The result is reported in the Metrics tree using the fullyqualified Metric name specified in the directives file. If desired, users can set up Alerts on
this Metric.
Over and Under Threshold Counter Tracers:
• OverThresholdPerIntervalCounter, which traces the number of invocations
greater than a user-defined threshold.
• UnderThresholdPerIntervalCounter, which traces the number of invocations
equal to or less than a user-defined threshold.
Each of these Tracers produces one Metric each, which is displayed in the Explorer tree.
The fully-qualified Metric name is specified in the directives file.
Updating Introscope With Modified or New ProbeBuilder
Directives Files
After 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.
Page 231
Adding New Custom ProbeBuilder Directives Files
After 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 Files
Whether you create new custom Directives files or modify existing Directives files, you
must update the probes in Introscope by rerunning the ProbeBuilder or relaunching your
managed application with AutoProbe. Specifically:
Using AutoProbe
1.
Make changes to Directives files.
Page 232
2.
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.
Page 233
A Introscope Properties Files
This appendix describes the properties files and settings you can customize in your
Introscope® deployment.
Note: In these files, on Windows machines, when adding a path, you must escape a
backslash (\) with another backslash (each one doubled), such as
C:\\Introscope\\lib\\Agent.jar.
• Introscope Agent Settings File
• Introscope Enterprise Manager Settings Files
• Introscope Workstation Settings Files
• Introscope WebView Settings Files
• Database Settings Files
• Extensions Settings Files
Introscope Agent Settings File
Agent configuration is done in the IntroscopeAgent.profile file. The properties
found in this file may differ, depending on whether the Introscope Agent is configured for
use with AutoProbe and a specific application server, or without AutoProbe, and used with
ProbeBuilder Wizard or command-line ProbeBuilder. The table at the end of this section
details all possible properties that may be found in this file.
Agent Settings with AutoProbe Installation
If you are using AutoProbe, the file, IntroscopeAgent.profile will be installed by
your Agent installer by default in the <appserver home>/wily directory. Use this file to
set configuration information for AutoProbe and the Agent.
Change the AutoProbe settings according to your deployment:
• If the Web Application Server and the Enterprise Manager are on the same
computer, no changes to the IntroscopeAgent.profile file are necessary.
• If they are on different computers (recommended for production), edit the
IntroscopeAgent.profile file and change the Enterprise Manager host name
and port.
• If other changes are desired, edit the IntroscopeAgent.profile file as
necessary.
If you edit the IntroscopeAgent.profile file, edit the version that is used by the
managed application (located by default in the wily directory in the Web Application
Server or Virtual Machine directory).
Page 234
Directives Files
The introscope.autoprobe.directivesFile property specifies the Directives files
that determine how AutoProbe places Probes. This is a required parameter. If the
property is not specified or the values are invalid, Introscope cannot run.
You can enter Directives files (extension .pbd), Directives list files (extension .pbl), and
directories. Separate multiple entries with commas. Non-absolute names are resolved
relative to the location of the IntroscopeAgent.profile file.
Agent Settings Common to Both AutoProbe and non-AutoProbe
Installations
Log 4J Settings
Two properties define the level of detail in the Agent logs and the name and location of
Introscope Agent log files.
See Log4J documentation at http://jakarta.apache.org/log4j/docs/documentation.html
for information on advanced Log4J functionality.
Enterprise Manager Connection Order
This setting defines the order in which the Agent will attempt to connect to the Enterprise
Managers listed in the Enterprise Manager Locations and Names section.
Enterprise Manager Locations and Names
These settings define the host, port, and unique names of the Enterprise Managers the
Agent can connect to.
Agent and Process Name Settings
These properties specify details on the Agent name and how it will be obtained. The
Agent and Process names used as part of the Fully-Qualified Agent Name (Domain | host
| process | Agentname) to track information of a single Agent over multiple Agent
sessions.
Note: These properties are optional. If the Agent name is not defined, it will be known as
UnknownAgent.
Agent Thread Priority
The Agent, by default, uses an average priority TCP/IP connection. This setting is usually
sufficient. However, if you know your managed application is designed to complete its
work as fast as possible (take highest priority), you should then set the
introscope.agent.thread.all.priority property to the same or higher priority as
the managed application, to prevent data starvation (where data never gets sent to the
Enterprise Manager).
PMI Configuration
These settings turn on the Introscope PMI data collection, and define which PMI Metrics
are collected in Introscope.
Page 235
To enable PMI collection functionality, you must first turn on Performance Monitor
Settings in WebSphere (see Turning on Performance Monitor Settings in WebSphere,
page 189).
For each high-level Metric category you want to collect PMI data for (eight for WebSphere
4.0, 15 for WebSphere 5.0.x), you must turn on the setting for that property (change
setting to true).
Note: Any time-related Metric collections are recorded in microseconds (1/1,000,000th
of a second), instead of milliseconds (1/1,000th of a second), which is the usual
Introscope time period.
JMX Support
These settings turn on JMX support, and define which JMX Metrics are collected in
Introscope. JMX support will only work if the Agent is running on JDK1.2 or higher. The
shipped JMX configuration in the IntroscopeAgent.profile file supports WebLogic
6.1 and higher, and WebSphere 5.0.x and higher.
LeakHunter Properties
These properties are used by the Agent to communicate with LeakHunter, an add-on
product.
Transaction Tracer Properties
These properties are used by the Agent to communicate with the Transaction Tracer.
TABLE 14. File:<Introscope home>/examples/IntroscopeAgent.profile
This Setting
Specifies
Default Setting
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.reportRateMetr
ics
Enables reporting of individual
Socket's Input/Output Bandwidth
rate Metrics
true
Page 236
This Setting
Specifies
Default Setting
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.con
nectionorder
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
introscope.agent.enterprisemanager.tran
sport.tcp.host.DEFAULT
The host name of machine running
the Enterprise Manager.
localhost
sport.tcp.port.DEFAULT
The port on the Enterprise
Manager machine that listens for
the Agent.
5001
sport.tcp.socketReadTimeoutInSecond
Network timeout value in seconds
when establishing Agent
connection to Enterprise Manager
60
introscope.agent.enterprisemanager.failb
ackRetryIntervalInSeconds
Number of seconds between
attempts by Agent to reconnect to
primary Enterprise Manager.
Commented out; 120
Name for process being monitored.
Commented out; set to
name of application
server for applicationserver 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.agentNameSystemProp
ertyKey
Specifies which Java system
property will contain Agent name.
blank
introscope.agent.agentAutoNamingEnabl
ed
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
; uncommented and
true in Agent profile
shipped with supported
application servers
introscope.agent.agentAutoNamingMaxi
mumConnectionDelayInSeconds
Specifies the amount of time in
seconds the Agent waits for
naming information before
connecting to the Enterprise
Manager.
120
Page 237
This Setting
Specifies
Default Setting
introscope.agent.agentAutoRenamingInt
ervalInMinutes
Specifies the time interval in
minutes during which the Agent
will check to see if it has been
renamed.
10
introscope.agent.disableLogFileAutoNam
ing
Specifies whether to disable
automatic naming of Agent log files
when using AutoNaming options.
false
Name of Agent
• For
IntroscopeAgent.prof
ile file included with
default installer,
commented out, and
provided Agent name
is Unknown Agent
• For
IntroscopeAgen.profil
e included with
AutoProbe installer,
provided Agent name
is same as
application server
(e.g. WebLogic
Agent)
•
•
•
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
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.servletSessi
ons
servletSessions data.
true
introscope.agent.pmi.enable.connection
Pool
connectionPool data.
true
introscope.agent.pmi.enable.bean
Enables collection of PMI bean
data.
false
introscope.agent.pmi.enable.transaction
transaction data.
false
introscope.agent.pmi.enable.webApp
Enables collection of PMI webApp
data.
false
introscope.agent.pmi.enable.jvmRuntim
e
Enables collection of PMI jvm
Runtime data.
false
Page 238
This Setting
Specifies
Default Setting
introscope.agent.pmi.enable.jvmpi
Enables collection of PMI jvmpi
data.
false
Note: For data to be provided to
this module, JVMPI must be
turned on in WebSphere.
introscope.agent.pmi.enable.system
WebSphere 5.0.x only; enables
collection of operating system-level
data.
false
introscope.agent.pmi.enable.cache
collection of data about the
effectiveness of WebSphere
caching layers.
false
introscope.agent.pmi.enable.orbPerf
collection of performance statistics
about the embedded Object
Request Broker (ORB).
false
introscope.agent.pmi.enable.j2c
collection of J2EE connector data.
false
introscope.agent.pmi.enable.webService
s
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
ile file
For WebLogic:
Type,Name
For WebSphere:
J2EEServer,Applica
tion,j2eeType,JDBC
Provider,name,mbea
nIdentifier
Page 239
This Setting
Specifies
Default Setting
introscope.agent.jmx.name.filter
Filtered string(s), separated by
commas
Commented out in
default
ile file
Note: IntroscopeAgent.profile
file installed with Agent for
WebLogic has the following filters
defined:
For WebLogic:
ActiveConnectionsCur
rentCount,WaitingFor
ConnectionCurrentCou
nt,PendingRequestCur
rentCount,ExecuteThr
eadCurrentIdleCount,
OpenSessionsCurrentC
ount
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
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
introscope.agent.clonedAgent
Unique name for cloned Agents
Commented out; false
introscope.agent.platform.monitor.syste
m
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.locati
on
Location of LeakHunter.log file.
Filename is relative to the
application working directory.
LeakHunter.log
introscope.agent.jmx.ignore.attributes
Commented out; server
Note: If property is commented
out or left blank, no log file will
be written.
introscope.agent.leakhunter.logfile.appe
nd
Specifies whether to replace log file
(value of false) or append
existing log file (value of true) on
application restart.
false
introscope.agent.leakhunter.leakSensitivi
ty
Sensitivity of LeakHunter (higher
sensitivity will report more
collections as potential leaks).
Must be integer value from 1-10.
5
Page 240
This Setting
Specifies
Default Setting
introscope.agent.leakhunter.timeoutInMi
nutes
Period (in minutes) during which
Introscope LeakHunter looks for
new potential leaks. Must be nonnegative integer. Value of zero
means no timeout.
120 minutes
introscope.agent.leakhunter.collectAlloca
tionStackTraces
Specifies whether to collect
allocation stack trace information.
false
Note: Turning on this option has
the potential to create higher
system overhead, in CPU usage
and memory.
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.getRemote
User method to specify User IDs.
Commented out;
.method
Specifies the
HttpServletRequest.getHeader
method to specify User IDs.
Commented out;
.key
User-defined key string
Commented out;
supplied by user
.method
Specifies the
HttpServletRequest.getValue
method to specify User IDs.
Commented out;
.key
User-defined key string
Commented out;
supplied by user
introscope.agent.transactiontracer.para
meter.httprequest.headers
Specifies (in comma-separated list)
httprequest header data to
capture. Comma separated list.
Commented out;
supplied by user
meter.httprequest.parameters
httprequest parameter data to
capture.
Commented out;
supplied by user
meter.httpsession.attributes
http session attribute data to
capture.
Commented out;
supplied by user
HttpServletReque
st.getRemoteUser
HttpServletReque
st.getHeader
HttpServletReque
st.getValue
Page 241
Introscope ProbeBuilder Settings File
Introscope ProbeBuilder Settings File
Introscope ProbeBuilder Wizard.lax File
TABLE 15. File: <Introscope home>/Introscope ProbeBuilder Wizard.lax
This Setting
Specifies
Default Setting
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
The files described in the following sections contain settings for the Introscope Enterprise
Manager. The Introscope Enterprise Manager reads these files at startup. If you make
changes, you must restart the Enterprise Manager for these changes to take effect.
IntroscopeEnterpriseManager.properties File
Ports
Agent listener and Workstation ports can be set to any available TCP port on the machine.
Firewalls may require that non-default ports be used.
Log 4J Settings
Two properties define the level of detail in the Enterprise Manager logs and the name and
location of Enterprise Manager log files.
See Log4J documentation at http://jakarta.apache.org/log4j/docs/documentation.html
for information on advanced Log4J functionality.
SmartStor Properties
These properties define how often SmartStor will collect Introscope Metric data, and how
long the data will remain before being aged out.
Page 242
Transaction Event Database
These properties define the directory the Enterprise Manager uses to store transaction
events (including transaction traces and error information), and how long to store them.
Database Properties
Database settings in this file determine whether and how performance data from
managed applications is stored in a relational database. These settings must be
uncommented and correctly set up for the database and historical queries to work.
Consult your JDBC driver documentation for specific information related to your driver.
See the example in commented lines in the <Introscope home>/config/
IntroscopeEnterpriseManager.properties file itself.
Database settings are:
• Fully-qualified class name of the JDBC driver that works with your database
• 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.
Page 243
TABLE 16. File: <Introscope home>/config/
This Setting
Specifies
introscope.enterprisemanager.agent.
metrics.limit
Number of Metrics Agent will report before it
is shut off.
Default
Setting
50000
Note: This property is not present in the
EM properties file, it must be typed in
manually.
introscope.enterprisemanager.port.w
orkstation.rmi
Enterprise Manager machine port that
communicates with Workstations.
4500
introscope.enterprisemanager.port.w
orkstation.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.workst
ation.disableSecureConnection
Disables the secure Workstation port.
false
Note: If this property is used, usernames
and password information will be sent
unencrypted over the network.
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
Name and location of Enterprise Manager
logfile
IntroscopeEnt
erpriseManage
r.log
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.smart
stor.enable
Enables SmartStor data collection.
true
Note: SmartStor does not interfere with
data being sent to Persistent Collections.
data
stor.directory
Specifies the directory SmartStor will use.
stor.tier1.frequency
Specifies the frequency (in seconds) of data
collection for the first data tier.
15
stor.tier1.age
Specifies the number of days after which
data in first tier ages out of SmartStor.
1
collection for the second data tier.
60
Note: Do not touch this.
Page 244
Default
Setting
This Setting
Specifies
stor.tier2.age
data in second tier ages out of SmartStor.
7
collection for the third data tier.
300
stor.tier3.age
data in third tier ages out of SmartStor.
7
introscope.enterprisemanager.transa
ctionevents.storage.dir
Specifies where to store transaction event
data.
traces
introscope.enterprisemanagter.trans
actionevents.storage.max.data.age
Specifies (in days) how long to store
transaction event data.
14 days
introscope.enterprisemanager.db.dri
ver
Name of your database driver
Commented
out
introscope.enterprisemanager.db.url
Name of your database URL.
Commented
out
introscope.enterprisemanager.db.use
rname
User name required for database access
Commented
out
introscope.enterprisemanager.db.pas
sword
Password required for database access
Commented
out
introscope.enterprisemanager.db.tab
lequalifier
Sets explicit table qualifier, for locating
database tables in locations other than
default locations associated with login.
This qualifier will be prepended (or
appended as appropriate) directly to
the table name so be sure to include any
separator required by the database.
Commented
out
introscope.enterprisemanager.db.rec
onnect.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.use
BatchInserts
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.bat
chInsertSize
Controls the size (in row insertion count) of
batch inserts, if they are enabled.
Commented
out
introscope.enterprisemanager.db.qu
eryTimeoutInSeconds
Number of seconds to wait for a query to
complete before giving up. A value of zero
means there is no timeout for queries.
Commented
out
Only used if supported by both the database
and JDBC driver.
Page 245
Default
Setting
This Setting
Specifies
introscope.enterprisemanager.db.ma
ximumTableCacheSize
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.qu
eryConnections
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.
Commented
out
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.
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
.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
.maxTimeInHours
Time in hours after which the flat file is
archived.
Commented
out; 24
.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.disabl
eInteractiveMode
Disables interactive console (whether
console accepts input).
true
Note: On many UNIX platforms, nohup will
not work if the application is trying to read
from standard input. Therefore, if you
choose to run in nohup mode, ensure the
value of this setting is set to true. You
must also change the
lax.stdin.redirect property in the
Introscope Enterprise Manager.lax File to
<blank>. If both of these properties are
not set exactly as stated above, it can
either render the application unable to
start up in nohup, or cause maximum CPU
utilization.
Page 246
Default
Setting
This Setting
Specifies
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.webvi
ew.disableLogin
Determines whether WebView can establish
a connection with Enterprise Manager.
false
introscope.enterprisemanager.webvi
ew.password
Specifies password WebView users to
connect to Enterprise Manager
WebView
The following four properties are duplicated for each authentication extension used.
introscope.enterprisemanager.authe
ntication.providers
Specifies which authentication extensions
are used during login
<Extension
type>
ntication.extensionName.<Extension
Name>
Specifies extension name
<Extension
name>
ntication.controlflag.<ExtensionNam
e>
Specifies control flag
<control flag
value>
ntication.configFile.<ExtensionName
>
Specifies name and location of extension
configuration file
<config-file
information>
Introscope Enterprise Manager.lax File
TABLE 17. File: <Introscope home>/Introscope Enterprise Manager.lax
This Setting
Specifies
Default Setting
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:la
x.
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.
Varies by operating
system
lax.nl.java.option.
additional
Initial minimum and maximum heap sizes
-ms128m -mx512m
lax.stderr.redirect
Standard Error Output. Leave blank for no
window, or any path to a file to save to the
file.
console
Page 247
Introscope Workstation Settings Files
This Setting
lax.stdin.redirect
Specifies
Default Setting
Standard Input.
console
Caution: Do not change.
Note: On many UNIX platforms, nohup
will not work if the application is trying to
read from standard input. If you choose to
run in nohup mode, change this setting to
<blank>. You must also ensure that the
introscope.enterprisemanager.disabl
eInteractiveMode=true property in the
File: is set to true. If both of these
properties are not set exactly as stated
above, it will either render the application
unable to start up in nohup, or cause
maximum CPU utilization.
lax.stdout.redirect
window, or any path to a file to save to the
file.
console
EMService.conf File
The EMService.conf file contains settings used when the Enterprise Manager is run as
a Windows Service.
Note: Before configuring these properties, you must deregister the Enterprise Manager
Service. After configuring properties, re-register the Enterprise Manager Service.
TABLE 18. <Introscope home>/EMService.conf
This Setting
Specifies
Default Setting
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
The files described in the following sections contain settings for the Introscope
Workstation.
Page 248
IntroscopeWorkstation.properties File
TABLE 19. File: <Introscope home>/config/IntroscopeWorkstation.properties
This Setting
Specifies
Default Setting
log4j.logger.Workstation
Workstation log
INFO, console
Name and location of Workstation
logfile
IntroscopeWorkstation.log
Introscope Workstation.lax File
TABLE 20. File: <Introscope home>/Introscope Workstation.lax
This Setting
Specifies
Default Setting
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_ARGUM
ENTS$
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.
Varies by operating
system
lax.nl.java.option.
additional
Other option settings for JVM
-classic -ms64m mx256m
Initial minimum and maximum heap sizes.
The classic setting
invokes Java 2 classic
VM.
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
Page 249
Introscope WebView Settings Files
Introscope WebView Settings Files
The files described in the following sections contain settings for Introscope WebView.
IntroscopeWebView.properties File
TABLE 21. File: <Introscope home>/config/IntroscopeWebView.properties
This Setting
Specifies
Default Setting
log4j.logger.WebView
WebView log
INFO, console
Name and location of WebView
logfile
logs/
IntroscopeWebView.log
introscope.webview.tcp.port
Port on which WebView listens for
HTTP traffic
8080
introscope.webview.enterprise
manager.tcp.host
Enterprise Manager hostname to
connect to
localhost
introscope.webview.enterprise
manager.tcp.port
Enterprise Manager port to connect
to
4500
introscope.explorer.refresh.int
erval
Frequency (in seconds) at which the
Explorer tree refreshes.
15
introscope.webview.password
Password WebView uses to connect
to the Enterprise Manager
WebView
Note: DO NOT
CHANGE.
Introscope WebView.lax File
TABLE 22. File: <Introscope home>/Introscope WebView.lax
This Setting
Specifies
Default Setting
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.
Varies by operating system
lax.nl.java.option.
additional
Other option settings for JVM
-classic -ms64m -mx256m
Initial minimum and maximum heap
sizes.
The classic setting invokes
Java 2 classic VM.
Page 250
Database Settings Files
This Setting
Specifies
Default Setting
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
window, or any path to a file to save
to the file.
blank
Database Settings Files
The file described in the following section contains settings related to database usage
with Introscope.
CustomDBRecordTypes.properties File
The default datatypes may not be sufficient to meet your needs. You can add custom
datatypes by adding lines to the file, CustomDBRecordTypes.properties. You are
more likely to be creating a custom datatype for use with a custom Tracer. (For more
information, see Database Record Types, page 209.)
Create a custom datatype with three properties:
• a regular expression to identify an Agent
• a regular expression to identify Metrics
• a new datatype name
To assign a datatype to a Metric, the 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.
Page 251
Extensions Settings Files
TABLE 23. File: <Introscope home>/config/customDBRecordTypes.properties
This Setting
Specifies
Default Setting
database.recordtypes.
agentexpression.#
Identifies an Agent
Regular Expression
database.recordtypes.
metricexpression.#
Identifies Metric
Regular Expression
introscope.enterprisemanager.d
atabase.recordtypes.
typestring.#
Datatype name assigned to a Metric
that matches both regular
expressions above
Record Type
LocalAuthenticationExtension.properties
This file contains the configuration properties for the local authentication extension.
LocalAuthenticationExtension.properties
This Setting
Specifies
Default Setting
authentication.extension.lo
cal.userFile
Pathname of the username/
password file
config/users.xml
This file contains the configuration properties for the LDAP authentication extension.
This Setting
Specifies
Default Setting
authentication.extension.ldap.url=
URL for the remote LDAP server
ldap://host:port
Note: If you are using SSL, the
SSL LDAP port should be part of
the server URL.
authentication.extension.ldap.useS
SL
Whether to use SSL to connect to
remote LDAP server
false
authentication.extension.ldap.bind
Name
Name used to bind to LDAP server.
If blank, anonymous bind is used.
IntroscopeLDAPUser
Page 252
This Setting
Specifies
Default Setting
Password
Password used to bind to LDAP
server. If anonymous bind is used,
this property is ignored.
password123
Authentication
Authentication type to use when
binding.
simple
Options are: none, simple, CRAMMD5.
authentication.extension.ldap.user.
nameSuffix
Suffix to append to Introscope
user name for use with LDAP
queries.
@dev.com
baseDN
Base distinguished name (DN) for
all user object queries
cn=Users, dc=dev,
dc=com
scopeDepth
Search depth when querying for a
user object
subtree
usernameAttribute
Name of LDAP attribute that will
match an Introscope username
userPrincipalName
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.
(&(userPrincipalNam
e=%u)(objectclass=
user))
authentication.extension.ldap.serv
erCertificate
Name of certificate file. Supported
certificate types are of type X.509,
and base64-encoded.
blank
If not specified, default certificate
authorities provided by the JVM
will be used.
Page 253
BLicenses
Apache Software License, Version 1.1
Copyright (c) 1999-2000 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
1.
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 apache@apache.org.
5.
Products derived from this software may not be called "Apache", nor may "Apache"
appear in their name, without prior written permission of the Apache Software
Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Page 254
License for JDOM Binary Distribution
This software consists of voluntary contributions made by many individuals on behalf of
the Apache Software Foundation and was originally based on software copyright (c) 1999,
International Business Machines, Inc., http://www.ibm.com. For more information on the
Apache Software Foundation, please see http://www.apache.org.
License for JDOM Binary Distribution
Copyright (C) 2000 Brett McLaughlin & Jason Hunter. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
1.
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 license@jdom.org.
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 (pm@jdom.org).
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE JDOM PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of
the Java Document Object Model Project and was originally created by Brett McLaughlin
<brett@jdom.org> and Jason Hunter <jhunter@jdom.org>. For more information on the
JDOM Project, please see http://www.jdom.org.
License for Tanuki Software Distribution
Copyright (c) 1999, 2003 TanukiSoftware.org
Page 255
License for Tanuki Software Distribution
Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sub-license , and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
Page 256
Index
A
Agent
cloned Agent naming 176
configuration
other settings 177
verbose mode 179
installing
on Oracle 10g 136
on other application servers 142, 149
on Sun ONE 128
on WebLogic 95
on WebSphere 106
on WebSphere on OS/390 117
naming options 169
automatic
automatically from application server
170
using Java system property 169
using system property key 170
redirecting output to a file 179
resolving Agent naming conflicts 177
running Agent twice on one machine 177
verbose mode 179
Agent Failover
Domains and User issues with 93
Agent failover
Domain/User configuration 175
AIX
platform monitors 181
audience 15
Authentication
LDAP 84
local 81
AutoProbe
Application Server AutoProbe 96
with Oracle 10g 139
with Sun ONE 131
with WebLogic 101
with WebSphere 111
with WebSphere on OS/390 121
definition 22
directives
using custom 177
JVM AutoProbe
with Oracle 10g 138
with other application servers 144, 151
with Sun ONE 130
with WebLogic 99
with WebSphere 108
with WebSphere on OS/390 119
properties file location
on WebLogic 102
B
batch job
running Enterprise Manager as in OS/390 67
Blame Technology 23
blamed tracers 221, 222
C
Command-Line ProbeBuilder
commands 164
configuring
other Java applications 162
Console 24
Console mode
49
custom Tracers. See ProbeBuilder Directives
Page 257
D
configuring
database 193
new database connection 194
installing and configuring
on OS/390
running as a batch job in OS/390 67
running as Windows Service 65
deregistering 66
running from command line
commands 197
starting 58
OS/390 59
UNIX 58
Windows 58
stopping 59
database
5.0 database schema 203
configuring Enterprise Manager for 193
creating reports 211
Enterprise Manager properties 195
explicit table qualifier 199
querying tables 210
record types 209
reporting 202–211
sample Microsoft Access database 196
scripts
creation 194
tables
Agent table 205
Index table 204
Metadata table 206
Metric name table 206
Metric table 206
Property table 205
Resource table 206
Version table 204
upgrading schema tables 194
Domain 23
Domains
Agent mapping 78
changing 79
associating Management Modules with 78
attributes and syntax 77
creating 77, 78
creation rules 77
deleting 79
Managing Domains 76
merging 80
moving between Introscope installations 80
Domains and Users
overview 76
with Agent Failover 93
E
Element 26
Enterprise Manager 22
F
firewall 32
connecting components behind 200
flat file properties 243
Fujitsu Interstage
using Introscope 5.0 with 94
G
GUI mode
36
GUI installation sequence 37
launching GUI mode installer 37
I
Installation
in Console mode 49
in GUI mode 36
GUI installation sequence 37
launching GUI mode installer 37
in Silent mode 51
launching silent mode installer 52
miscellaneous options 201
planning where to install 27
preparing for 27, 32
process 33
Page 258
system requirements 29
Interstage
using Introscope with 94
Introscope
components defined 21
JVMs bundled with 31
supported JVM versions 31
terms defined 21
Introscope.EnterpriseManager.properties
database properties 195
Introscope-enabled code 21
options 166
switching back to original code 167
J
Java2 Security Policy 201
on WebSphere 5.0 110, 112
JMX support 182–187
configuring 185
enabling 185
JMX filters 184, 186
Metric name conversion 183
default method 184
primary keys method 183
primary keys 183
primary keys, defining 186
viewing JMX data in Explorer 187
L
lax files
Introscope Enterprise Manager.lax 247
Introscope ProbeBuilder Wizard.lax 242
Introscope WebView.lax 250
Introscope Workstation.lax 249
License
Apache Software Version 1.1 254
JDOM Binary Distribution 255
license file
installing 58
Log4J
Agent settings 179
Enterprise Manager settings 63, 64
Workstation settings 199, 200
M
Managed Java Application 21
Management Module 26
Management Modules
moving 198
message URL http
//wrapper.tanukisoftware.org/doc/english/
properties.html 65
Metric 23
Metric Grouping 23
O
Oracle Application Server 10g
configuring with Introscope 136–141
basic Agent settings 140
installing Agent on 136
ProbeBuilder configuration options 137
organization of book 15
OS/390
base structure for Java 67
customizing UNIX shell script 71
DASD 70
DB2 68
DB2 considerations on 74
Enterprise Manager OS/390 files and partitioned dataset 71
installing Enterprise Manager on 70
JDBC 69
PROC
customizing 72
executing 72
running Enterprise Manager as a batch job in
67
running Enterprise Manager as started task
72
running Enterprise Manager on 72
security and authorization 68
software prerequisites for Java 67
Page 259
starting Enterprise Manager 59
starting Enterprise Manager automatically
on 74
OS/400
installing Introscope Agent with AutoProbe
WebLogic 95
P
platform monitor 180
troubleshooting 182
ports
specifying 242
ProbeBuilder 22
Command-line ProbeBuilder 162
configuring java applications manually with
155
customizing Directives 212
integrating into build process 200
list files 214
log 201
ProbeBuilder Wizard 155
ProbeBuilder Directives 212
applying changes to 232
components tracked 213
components tracked in 213
custom Tracers 220
combining 227
creating 220
examples template 223
files
custom 161, 214
updating Introscope with 232
system 160, 214
keywords 227
action 228
IdentifyClassAs 228
IdentifyCorbaAs 228
IdentifyInheritedAs 228
InstrumentPoint 228
TraceAllMethodsIfInherits 229
TraceAllMethodsOfClass 229
TraceOneMethodOfClass 229
TraceOneMethodWithParameterIfInherits 229
TraceOneMethodWithParametersOfClass 230
TurnOn 230
skip 228
SkipClass 228
SkipPackage 228
Threshold action 230
parameters 231
TraceAllMethodsWithThresholdOfClass 230
TraceOneMethodWithThresholdOfClass 230
Threshold Tracers
OverThresholdPerIntervalCounter
231
StalledMethodTracer 231
UnderThresholdPerIntervalCounter
231
modifying 215
EJB subclass tracing 219
Tracer groups
adding classes to 219
turning on or off 218
only defined methods traced 214
parameters 227
single-Metric Tracers 213
Tracer groups
default 216
turning on or off 213, 218, 219
updating probes 231
ProbeBuilder Wizard 22, 155–161
adding Probes to bytecode with 157
Probes 21
properties
database 243
Directives files to use 235
files 234
flat file 243
introscope.autoprobe.DirectivesFile 235
properties files
CustomDBRecordTypes.properties 251
Introscope Enterprise Manager.lax 247
Introscope ProbeBuilder Wizard.lax 242
Introscope WebView.lax 250
Introscope Workstation.lax 249
Page 260
242
IntroscopeWebView.properties 250
IntroscopeWorkstation.properties 249
R
RedHat
platform monitor 180
redirect output
Agent 179
Enterprise Manager in 64
Workstation 200
Resource 23
S
Silent mode 51
launching silent mode installer 52
Blame Technology and 224
BlamedMethodRateTracer 222
BlamedMethodTimer 221
BlamedMethodTraceDecrementor 222
BlamedMethodTraceIncrementor 222
ConcurrentInvocationCounter 222
default Tracer Groups 215
example template 223
full and typical tracing options 175
MethodCPUTimer 222
MethodRateTracer 222
MethodTimer 221
MethodTraceDecrementor 222
MethodTraceIncrementor 222
PerIntervalCounter 222
toggle files 215
Transaction Event Database
configuration during GUI installation 41
settings 62, 243
type conventions 17
SmartStor 60
and Persistent Collections 60, 193
requirements 61
SNMP Collections 243
Sun ONE Application Server
SuperDomain 23
system requirements
Introscope 29
JVM 31
memory 31
T
Tracer groups
Tracers
advanced custom
creating 225
advanced single-Metric 225
U
uninstalling Introscope 54
UNIX
Enterprise Manager
running in nohup mode 64
starting Enterprise Manager 58
User
modifiers and syntax 82
User permissions
creation rules 88
Users
access privileges
server permissions
creation rules 91
defining 81
defining a user 82
permissions 88
Domain access
defining permissions 90
server access
defining permissions 92
modifiers and syntax 91
Page 261
V
verbose mode
running Agent in 179
running Enterprise Manager in 63
running Workstation in 199
W
WebLogic Server
JMX data 182
WebSphere 6.0 109
Websphere 6.0 111
WebSphere Application Server
configuring custom service for 116, 127
PMI data 189–193
enabling and defining 191
viewing 192
WebSphere 4.0
disabling automatic Agent naming for
115
WebSphere Application Server on OS/
390
configuring as batch job 67–75
configuring with Introscope ??–127
Workstation 24
connecting to Enterprise Manager behind
firewall 200
installing on Windows 94
Page 262

Introscope 4.2 Installation Guide

Transcription

Similar documents

CA Wily Introscope Product Brief

Regions CD Check Viewer Installation Guide

CA Wily Introscope - SAP Support Portal

SAP Extended Diagnostics by CA Wily

Math Filler Games for Kindergarten

Xactimate System Requirements

Important Performance Analysis, SWOT, EFAS, IFAS

touring - Fuelpak

Installing SolidWorks Network Licenses

Xactimate 28 Installation Guide