2011

SAP

Active Global Support

[INTROSCOPE AGENT SETUP

GUIDE FOR IBM WEBSPHERE ]
Wily Introscope Agent setup guide for IBM WebSphere Application Server.
Content
Overview ________________________________________________________________________ 3
Introscope Overview _____________________________________________________________ 4
Installation procedure ____________________________________________________________ 5
Download the Latest Updates from the Service Marketplace ____________________________ 5
Extract Introscope Agent files _________________________________________________________ 5
Set user permissions for Agents directory________________________________________________________6

Configure Introscope Agent ___________________________________________________________ 6

Set Agent connection properties ________________________________________________________________6
Choose the Right Instrumentation Packages _____________________________________________________7
Set user permissions for Agents log files ________________________________________________________7

Configure JVM AutoProbe (optional) ___________________________________________________ 7

Activate Introscope Agent: set Java VM parameters ___________________________________ 8
The Agent Name ______________________________________________________________________________9
Configure Introscope Agent to report JMX metrics. ________________________________________________9
Configure Intorscope Agent to report WebSphere PMI metrics (optional) ___________________________10

Restart WebSphere Application server ________________________________________________ 11

Verify Introscope Agent installation___________________________________________________ 11

Additional Information __________________________________________________________ 11

Diagnostics at service.sap.com ________________________________________________________________11
Wily Introscope Release Notes _________________________________________________________________11
CSS XX-PART-WILY _________________________________________________________________________11
SAPCAR Tool _______________________________________________________________________________12

Page |2

Copyright/Trademark
Overview
This document covers the installation and configuration of CA Wily Introscope agent for IBM WebSphere
Application Server.

Page |3

Copyright/Trademark
Introscope Overview
Introscope is an application management solution created to manage Java Application performance. The
Java Agent is the component of Introscope that collects performance data from your applications running
on Java Virtual Machines (JVMs), and sends it to the Introscope Enterprise Manager.

The Enterprise Manager processes the data received from the Java Agent and sends it to the Introscope
Workstation where you can review the information and set up actions and alerts based on the data
received. The Java Agent allows Introscope to collect minute details about how your applications are
performing. Data is collected from your applications by the Java Agent. What types of data collected
depends on which ProbeBuilder Directives (PBDs) files you choose to implement. Several standard PBDs are
included when you install the Java Agent, as well as specific PBDs for your application server. Fine tuning
the tracers and directives in the PBD files will deliver the metric information you want to monitor for your
environment.

The figure below illustrates the key components in the Introscope environment.

The Right to View (RTV) version of CA-Wily Introscope supplied with SAP Solution Manager is a restricted,
read-only form of the full product and is bundled with SAP Solution Manager. With the RTV version,
support is limited to products that are licensed and supported by SAP. The instrumentation, dashboards,
Probe Builder Directives (PBDs), management modules, and Smartstor data contained within the RTV
version of CA-Wily Introscope as provided by SAP is the intellectual property of SAP. Use of these functions
is restricted by SAP and may only be used in an unrestricted manner by licensing SAP Extended Diagnostics
by CA-Wily from SAP.

Page |4

Copyright/Trademark
Installation procedure
This section describes installation and configuration of Wily Introscope ByteCode Agent for Java for IBM
WebSphere Application Server. The installation instructions are valid for IBM WebSphere as of version 6.0
or higher. If Java 4 is used an additional installation step is required.

The instructions in the following section are applicable to both Windows and UNIX systems.

Note: Use Unix-like forward slashes (/) as path separators on all platforms (including Windows) (e.g. in
Introscope configuration files and in the JVM parameters). Windows-like backslash (\) separators has to be
escaped with double backslashes (\\).

The following steps are required to install and configure the Introscope Java Agent to report information to
the Enterprise Manager:

1. Download the latest Intorscope Agent installation files

2. Extract the Introscope Agent files on the WebSphere host.
3. Configure the Introscope Agent (customize _websphere profile file)
4. Activate the Introscope Agent in the application servers (set the Java VM parameters)
5. Restart WebShere Application Server(s)
6. Verify Introscope Agent installation

Old Introscope Agents

It is recommended to uninstall old Introscope Agent installations before new installation. To uninstall
Introscope Agent remove JVM options and agent directory, and restart WebSphere application server(s).

Download the Latest Updates from the Service Marketplace

Download the latest Wily Introscope Agent for Java installation package from the SAP Service Marketplace.
Please refer to the SAP Note 1418638 for more information. The note provides instructions on which files
are necessary and how to download them.

Extract Introscope Agent files

To install the Introscope Agent please extract the installation .SAR package on the WebSphere application
server hosts. The same Introscope Agent installation can be used for multiple WebSphere application
servers. Thus, Introscope Agent needs to be installed and configured for WebSphere application servers per
each physical host.

SAP recommends to install Introscope Agent into the directory /usr/sap/ccms/wily.

Page |5

Copyright/Trademark
 cd /usr/sap/ccms
SAPCAR xvf ISAGENT.8.2*.SAR

Please check that the Agents files are properly extracted. Make sure that the /wily sub-directory exists in
the specified folder. For example

<drive>:/usr/sap/ccms/wile.

The Introscope Agent installation directory will be referred as the AGENT_HOME directory through this
guide.

Set user permissions for Agents directory

When you install the Agent, the installation directory <AGENT_HOME> is created with permissions in
accordance with the machine policy. The user starting the WebSphere Application Server must have read
permissions for the <AGENT_HOME> directory and its subdirectories.

Configure Introscope Agent

The following section describes how to configure the Introscope Agent.

Set Agent connection properties

The agent refers to properties in the <IntroscopeAgent>.profile file for its basic connection and naming
properties. When you install an agent, the agent profile is installed in the <AGENT_HOME> directory.

For Apache Tomcat SAP delivers the default Agent profile in the <AGENT_HOME> directory in
IntroscopeAgent_websphere.profile file. This file contains some SAP-specific settings.

The agent profile file contains different properties. You have to specify the connections properties to the
Enterprise Manager. All other settings can usually remain to the default values.

To configure the Introscope Agent:

Open the agents profile <AGENT_HOME>/IntroscopeAgent_websphere.profile.

Locate the property introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT.
Set the value to the host name (or IP address) of the machine where Enterprise Manager resides.
Locate the property introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT.
Set the value should be the port on which the Enterprise Manager listens for Agent connections. The
default value for that property is 6001.
Save changes to the agent profile.

Page |6

Copyright/Trademark
Choose the Right Instrumentation Packages
The property introscope.autoprobe.directivesFile specifies the (PBD) Directives files for AutoProbe.
ProbeBuilder Directive (PBD) files tell the Introscope ProbeBuilder how to add probes, such as timers and
counters, in order to instrument an application. SAP delivers the (PBD) Directive files packaged into .jar
files. Following package is used for Apache Tomcat by default:

introscope.autoprobe.directivesFile = sap_typical.jar,
sap_websphere_typical.jar

This instrumentation package covers standard J2EE (e.g. Servlets, database/JDBC, web services, threads,
etc.), functionality. Another instrumentation package for WebSphere is the sap_websphere_full.jar file. It
covers the same functionality but more in detail. Please use this file only if detailed analysis is needed.
Nether specify both typical and full together.

Set user permissions for Agents log files

The Introscope agent writes log files into the logs - subdirectory in the agent installation folder.

<AGENT_HOME>/logs.

Please make sure that the Apache Tomcat has read and write access to this directory. The location there
Introscope Agents wtites its logs is specified by the properties introscope.autoprobe.logfile and
log4j.appender.logfile.File

Configure JVM AutoProbe (optional)

If the WebSphere Application Server runs on Java 4 (e.g. WebSphere 6.0) you have additionally to create a
AutoProbe connector that fits for the Java VM that you use.

This step is only required for Java 4 and is not necessary for Java 5 and above.

The AutoProbe connector is created by the CreateAutoProbeConnector.jar tool provided in the Agents
connector folder. You have to specify the JVM used by the WebSphere application server. There are two
ways to specify the JVM:

use the same JVM to run tool as of WebSphere

pass in the JVM home directory to the tool as parameter -jvm on the command line

Please perform following steps

Change the working directory to <AGENT_HOME>/connectors.

Run the Create AutoProbe Connector tool using the following command:
java -jar CreateAutoProbeConnector.jar -jvm <JAVA_HOME> -output
connector.jar

Page |7

Copyright/Trademark
Example:

java -jar CreateAutoProbeConnector.jar -jvm C:/soft/jdk14 -output

connector.jar

As result this command will create a connector.jar in the same directory. You will specify the path to the jar
in Java VM options for the Introscope Agent.

Note: For AIX with IBM J9 Hybrid VM please refer to SAP Note 1015184there are additional parameters
to be used for creation of the AutoProbe connector on that Java VM.

Note: For IBM VM on Linux x86_64 please see note 1149214 there are additional parameters to be
used for creation of the AutoProbe connector on that Java VM.

Important Note

You must re-create the AutoProbe connector every time the used JVM is updated. Even if only JVM patch
level changes (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 WebSphere Application Server.

Activate Introscope Agent: set Java VM parameters

To activate the Introscope Agent for a WebSphere application server you have to add following additional
Java VM options:

On Java 5:

-javaagent:<AGENT_HOME>/Agent.jar
-Dcom.wily.introscope.agentProfile=<AGENT_HOME>/IntroscopeAgent_websphere.profile
-Dcom.wily.introscope.agent.agentName=<AgentName>

On Java 4 with AutoProbe connector:

-Xbootclasspath/p:<AGENT_HOME>/connectors/connector.jar;<AGENT_HOME>/Agent.jar
-Dcom.wily.introscope.agentProfile=<AGENT_HOME>/IntroscopeAgent_websphere.profile
-Dcom.wily.introscope.agent.agentName=<AgentName>

Note
Remember the difference in the class path separator between Unix and Windows. Class path
entries are separated by ; on Windows but by : on Unix.

You can use WebSphere Administrators UI Integration Solutions Console to specify Java VM parameters
for IBM WebSphere application server as follows:
Go to Servers > Application servers and select the server you want to modify.

Page |8

Copyright/Trademark
 From the right-side menu, click Server Infrastructure > Java and Process Management > Process
Definition > Java Virtual Machine
Specify new Java VM parameters in the field Generic JVM arguments

The Agent Name

Each Java Agent running in your Introscope environment has a name, whether you assigned one explicitly,
configured a method of automatically assigning a name, or simply started up an instrumented application
that the Java Agent monitors.

The Java Agent name is important because it is central to many views and presentations in the Introscope
clients, and it is the key to the process of associating monitoring logic with target applications.

You should assign a unique name to each Introscope Agent running in your landscape. The agent name is
set by the <AgentName> Java VM parameter (see above). SAP Solution Manager requires following agent
naming convention to be applied to WebSphere Application Server systems.

<AgentName>=<CELL _NAME>_<NODE_NAME>_<APP_SERVER_NAME>

there

<CELL_NAME> - the name of the WebSphere CELL, like diagp010Cell01

< NODE_NAME> - the name of WebSphere Node of the application server, like diagp010Node01
<APP_SERVER_NAME> -name of WebSphere application server, like server1

For example

-com.wily.introscope.agent.agentName =
diagp010Cell01_diagp010Node01_server1

Configure Introscope Agent to report JMX metrics.

In WebSphere environment, the Java Agent can additionally obtain and report management information
from the application server. For example, you can configure the Introscope agent to:

report JMX metrics from the application server

report Performance Monitoring Infrastructure (PMI) from WebSphere
obtain its name from the application server

To enable the Java Agent to obtain and use data from the application server you have to configure an
Introscope startup class as a custom service in the application server.

To configure Introscope custom service in the WebSphere Administrators UI Integration Solutions

Console, navigate to application server you want to set up and open its details screen.

1. Expand the right pane and navigate to Server Infrastructure > Administration > Custom Services.

Page |9

Copyright/Trademark
 2. Click New to add a new custom service.
3. Check the check box Enable service at server startup.
4. In the field Classname enter:
com.wily.introscope.api.websphere.IntroscopeCustomService

5. In the field Display Name enter, for example:

Introscope Custom Service
6. In the Classpath field, enter:
<AGENT_HOME>/WebAppSupport.jar
7. Click OK to create new custom service
8. Open the details screen for new Introscope Custome Service again and navigate to Additional
Properties->custom properties
9. Add following properties
jmxusername user account name in WebSphere with the user role Monitor
jmxpassword user password

Configure Intorscope Agent to report WebSphere PMI metrics (optional)

Introscope can provide WebSphere performance data by extracting WebSphere Performance Monitoring
Infrastructure (PMI) metrics via the PMI interface provided with WebSphere 5.1 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 enable PMI reporting:

enable PMI in WebSphere

enable PMI in the Introscope Agent profile
configure an Introscope Custom Service in WebSphere (see before)

To configure PMI collection, open the Introscope Agent profile file (e.g.
IntroscopeAgent_websphere.profile) and locate the property, introscope.agent.pmi.enable, under the
WebSphere PMI Configurations heading, and verify it is set to true.

introscope.agent.pmi.enable = true

Introscope can report data from the different high-level PMI metric categories. These categories are
represented by commented-out properties under the WebSphere PMI Configuration heading. For example,
introscope.agent.pmi.enable.threadPool=true
introscope.agent.pmi.enable.servletSessions=true
introscope.agent.pmi.enable.connectionPool=true

For each high level metric category you want to report, enter a value of true.

P a g e | 10

Copyright/Trademark
Restart WebSphere Application server
Restart the Apache Tomcat server. The Introscope Agent will send periodically performance data to the
configured Enterprise Manager

Verify Introscope Agent installation

Check that the WebSphere application server is started up and running and that the J2EE applications
are available. For troubleshooting Java Agent start-up problems, review the basic WebSphere
Application Server log (i.e native_stderr.log). If an incorrect configuration is placed in the Generic JVM
Arguments section and you experience errors starting the server, please review and correct the generic
JVM arguments in the server.xml file.

Look for the Agent log files (e.g. in the logs subdirectory of the Introscope agent installation directory
<AGENT_HOME>/logs). Make sure that a log file for configured Introscope Agent exists. The name of
the log file must be
IntroscopeAgent.<AgentName>.log
, there <AgentName> is the name of the Agent. Open the log file with a text editor and check the last
log messages in the file.

EXAMPLE

The last few lines of the agent log file should similar to the following:

12/06/06 01:41:46 PM PST [INFO] [IntroscopeAgent.IsengardServerConnectionManager] Connected Agent

to the Introscope Enterprise Manager at
localhost:6001,com.wily.isengard.postofficehub.link.net.DefaultSocketFactory. Host = "<emhost>", Process
= "WebSphere", Agent Name = "diagp010Cell01_diagp010Node01_server1".

Check that the Agent delivers data to the Enterprise Manager. Launch the Introscope Workstation and
make sure that the data provided by the agent is available in the Enterprise Manager.

Additional Information
Diagnostics at service.sap.com
Browse at the quick link service.sap.com/diagnostics for installation manuals

Wily Introscope Release Notes

See SAP Note 797147 for Wily Introscope release notes

CSS XX-PART-WILY
Please open a CSS message on XX-PART-WILY in case of problems

P a g e | 11

Copyright/Trademark
SAPCAR Tool
To extract .SAR file use the sapcar toll. See details in Support Package Stack Guide at
http://service.sap.com/instguidesNW04 -> Operations

P a g e | 12

Copyright/Trademark