WebSphere Application Server

To complete the installation and initial configuration, the steps are:
To complete the installation and initial configuration, the steps are:
Configure WebSphere Application Server
Configure the application server that you are instrumenting to include the path to the agent primary .jar file and the agent profile. You typically edit the application server startup script, then restart the application server. When the application server restarts, the Java agent instruments the classes discovered for default components of the JVM and application environment. The specific steps that are involved depend on the application server.
If you are planning to install CA APM for IBM z/OS or CA APM for IBM CICS Transaction Gateway to extend the monitoring capabilities, be aware that these agent extensions use legacy mode traces. Therefore you must use the Agent Legacy Package
. Never run the agent in mixed mode, as it often consumes extra memory heap resulting in application outages.
Configure WebSphere Application Server to Use the Java Agent
You can configure your WebSphere application server on different JVMs. On an IBM JVM, use the AgentNoRedefNoRetrans.jar file instead of Agent.jar.
IBM JVM does not support the Agent.jar file. Use the AgentNoRedefNoRetrans.jar file that deactivates class redefinition and retransformation when running the Java agents in IBM JVMs.
Using the AgentNoRedefNoRetrans.jar file has following limitations:
  • Metrics are not reported for system classes (java.*), NIO (Sockets and Datagrams), and SSL sockets because the class redefinition and retransformation functions are deactivated.
  • Instrumentation on sockets reverts to pre-Introscope 9.0.
  • ManagedSocket style remote dynamic instrumentation is disabled.
  • Changes to the PBD files require the instrumented JVM to be restarted before being applied.
  • Deep inheritance and hierarchy support instrumentation features are disabled.
  • Automatic entry point detection is disabled.
  • If you are using the AllAppServer agent distribution with the AgentNoRedefNoRetrans.jar file, the alternate profile is named IntroscopeAgent.websphere.NoRedef.profile.
  • If you have both instrumented and noninstrumented applications on the same computer, include the
    setting in the Generic JVM Argument. This setting avoids errors on AIX. A unique directory is required when there is more than one version of WebSphere using the same agent directory.
  • If you use a non-IBM JVM or an IBM JVM version other than 1.5, not all metrics and messages are output.
Follow these steps:
  1. Open the WebSphere Administrator Console.
  2. Navigate to
    Application Servers
    your server
    Server Infrastructure
    Java and Process Management
    Process Definition
    Java Virtual Machine
  3. Set the
    Generic JVM Argument
    field as follows:
    > -DagentProfile=<
    Where the <
    and <
    Path To AgentProfile>
    , respectively:
    -javaagent:<Agent_Home>/AgentNoRedefNoRetrans.jar -DagentProfile=<Agent_Home>/core/config/IntroscopeAgent.NoRedef.profile
  4. Restart the WebSphere application server.
AgentNoRedefNoRetrans.jar is not supported by APM Command Center.
Modify Java2 Security Policy
You might need to add permissions to your Java2 Security Policy for AutoProbe. The permissions allow Java2 Security Policy for AutoProbe to run correctly in IBM WebSphere environments with Java2 Security enabled.
Follow these steps:
  1. Open the $WebSphere home/properties/server.policy file in a text editor.
  2. Add the following permissions to the file.
    : In this example, the line breaks are shown for user readability. You do not need to add line breaks when adding the permissions to the server.policy file.
    // 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";
  3. Save and close the file.
Enable the Collection of IBM WebSphere PMI Metrics
Introscope can provide IBM WebSphere performance data. Introscope uses the IBM WebSphere PMI interface to extract IBM WebSphere Performance Monitoring Infrastructure (PMI) metrics.
You enable the PMI data collection in IBM WebSphere before the data can be available to Introscope. In IBM WebSphere, all performance monitoring settings are off by default.
Follow these steps:
  1. Configure a custom service for Introscope in IBM WebSphere.
  2. Enable PMI data collection in IBM WebSphere.
  3. Configure the reporting of PMI data in the IntroscopeAgent.profile.
Configure a Custom Service in IBM WebSphere
You can create or modify a custom service in the IBM WebSphere Application Server. The custom service enables the Java agent to collect additional information from the application server. If you configure a custom service, the Java agent can automatically determine its name. The custom service also enables the Java agent to report JMX and Performance Monitoring Infrastructure (PMI) metrics. The Workstation on the Application Overview tab uses these metrics to determine application health. The custom service can encrypt the user credentials that you want to use to access JMX metrics in Introscope.
Follow these steps:
  1. Open the IBM WebSphere Administrator Console.
  2. Select the server that you want to configure and navigate to Server Infrastructure, Administration, Custom Services.
  3. Modify the custom service that you want or create one.
  4. Complete the following fields on the Configuration page and click
    • Enable service at server startup
      This field specifies that the service starts during the server startup.
    • Classname
      This field specifies the name of the custom service class.
    • Display Name
      This field specifies the name to display in Introscope, for example: Introscope Custom Service.
    • Classpath
      This field specifies the fully qualified pathname of the properties file, for example:
  5. Configure metrics reporting when SIBus or new PMI modules are added to IBM WebSphere Application Server.
    1. Disable the Custom Service. 
    2. Create the Introscope Custom Service.
  6. Restart the application server.
Enable PMI Data Collection in IBM WebSphere
To monitor performance data through the Performance Monitoring Infrastructure (PMI), you must first enable PMI. Follow these steps:
  1. Open the administrative console.
  2. Click 
    Server Types
    WebSphere application servers,
  3. Click the 
  4. Click 
    Performance Monitoring Infrastructure (PMI)
  5. Select the 
    Enable Performance Monitoring Infrastructure (PMI)
     check box.
  6. Optionally, select the check box 
    Use sequential counter updates
     to enable precise statistic update.
  7. Optionally, choose a statistic set that needs to be monitored under 
    Currently Monitored Statistic Set
  8. Optionally, click on 
    to selectively enable or disable statistics. Choose a component from the tree and enable or disable statistics on the opposite table. Go back to the main PMI configuration page by clicking the 
    Performance Monitoring Infrastructure
  9. Click 
  10. Click 
  11. Restart the application server. The changes you make will not take effect until you restart the application server.
After you have enabled PMI data collection in IBM WebSphere, the PMI data can be displayed as Introscope metrics. You can filter which metric categories to bring into Introscope, depending on your needs.
 For IBM WebSphere on z/OS, we recommend that you use CA APM for IBM WebSphere z/OS. CA APM for IBM WebSphere z/OS provides IBM WebSphere-specific PBDs and metrics. These PBDs and metrics use a low-overhead tracer technology to retrieve IBM WebSphere-specific metrics. CA APM for IBM WebSphere z/OS does not require you to enable PMI in IBM WebSphere for z/OS. You can also enable PMI reporting in IBM WebSphere for z/OS, but this approach consumes more system resources.
Configure the Reporting of IBM WebSphere PMI Metrics in Introscope
After you turn on the Performance Monitoring Settings in IBM WebSphere, enable PMI data collection in Introscope. Enable the metric categories that you want.
Follow these steps:
  1. Shut down your managed application.
  2. Open the IntroscopeAgent.profile in a text editor.
  3. Locate the
    property in the IBM WebSphere PMI Configurations section, and verify that it is set to 
  4. Locate the following properties for high-level PMI metric categories:
    # introscope.agent.pmi.enable.jvmpiModule=false
    These four high-level PMI metric categories are set to 
     by default: threadPool, servletSessions, connectionPool, and j2c. You can enable more metric categories by setting the appropriate properties to 
    . You can reduce the metrics reported by commenting out categories.
  5. Save the changes and close the file.
  6. Restart the managed application.
    Available PMI metrics are displayed under the
    IBM WebSpherePMI
    node in the Investigator tree.
Configure the Reporting of Resource Metric Map Data for IBM WebSphere
Various agents can report and display resource metric categories when IBM WebSphere PMI data collection is enabled. You can configure the application server to report Resource Metric Map data.
Follow these steps:
  1. Log in to the IBM WebSphere console.
  2. Select
    Monitoring and Tuning, Performance Monitoring Infrastructure
  3. Select the server to use for reporting, such as server1.
  4. Click the
    tab, and select the
  5. Click the
    A configuration tree of options appears.
  6. Select
    JDBC Connection Pools
    on the tree, and enable
    on the right pane.
  7. Select
    on the tree, and enable
    on the right pane.
  8. Save the configuration and restart the application server.
    More information
    : Resource Metric properties
Enable EJB Over Java RMI Cross-Process Tracing in IBM WebSphere
Introscope lets you trace and correlate transactions for an application with these characteristics:
  • The application runs in the IBM WebSphere Application server.
  • The application uses Java Remote Method Invocation (Java RMI) to call EJBs. These EJBs are hosted in another IBM WebSphere Application server instance of the same version.
Follow these steps:
  1. Create a custom service.
  2. Turn on the work area service:
    1. From the administration page, Servers > Application servers, click server1, Business Process Services, Work Area Service.
    2. Select the "Enable service at server startup" check box.
  3. Open the IntroscopeAgent.profile file in a text editor.
  4. Locate and set introscope.agent.websphere.crossjvm property to true as follows:
  5. Save and close the IntroscopeAgent.profile file.
    Cross-process transaction tracing in IBM WebSphere is enabled.
Logging Factors for IBM WebSphere for z/OS
Consider these factors when logging in an IBM WebSphere z/OS environment.
More information
: Java Agent Logging
Tagging log Output as EBCDIC
Typically, z/OS is an EBCDIC computer. However, IBM WebSphere for z/OS changed its default encoding from EBCDIC CP1047 to ASCII ISO8859-1. Tag logging data that the Java Agent or AutoProbe write to use EBCDIC, not ASCII, as the final output stream.
To tag data as EBCDIC instead of ASCII
  1. Open the IntroscopeAgent.profile, located in the 
    \core\config directory.
  2. Add these properties to the IntroscopeAgent.profile:
  3. Save the IntroscopeAgent.profile
Eliminate Startup Timing Issues with Logging Facilities
You can configure IBM WebSphere for z/OS to eliminate startup timing-window exposures that can occur due to Introscope logging.
Follow these steps:
  1. Open the IntroscopeAgent.profile, located in the 
    \core\config directory.
  2. Add this property to the IntroscopeAgent.profile:
  3. The value is in milliseconds, so the default delay in this example is 100 seconds
  4. Save the IntroscopeAgent.profile.
Verify Your Configuration
If needed, you can verify your configuration by running a Transaction Trace session in WebView or Workstation. 
To begin, specify the Java agent whose transactions you want to trace and how long to capture the data. When the Transaction Trace Session starts, the agent captures the specified transaction trace data for each transaction. Introscope displays the transaction metrics in the Transaction Trace Viewer. The transaction metrics are saved in the Transaction Events database.