WebSphere installation for Java

These directions for WebSphere supplement the Java installation directions:

This doc describes how to install the Java agent from your WebSphere admin console, how to configure New Relic and Java 2 Security, and how to collect PMI metrics.

Compatibility and requirements

New Relic instruments WebSphere versions 7.0 through 8.5.5. Some variants of 8.5.0 are incompatible with the Java agent; for more information, get support at support.newrelic.com.

Install on WebSphere

To install the New Relic agent on WebSphere:

  1. Log in to the admin console.
  2. Select Servers > Application servers > (selected server).
  3. Select Configuration > Service Infrastructure > Java and Process Management > Process Definition > Additional Properties.
  4. From the Process Definition > Additional Properties, select Java Virtual Machine.
  5. On the Java Virtual Machine page, in the Generic JVM arguments textbox, add the -javaagent switch for your newrelic.jar file. Use the full path to newrelic.jar.
    -javaagent:/FULL/PATH/TO/newrelic.jar
  6. Select Apply, then select Save.
  7. Restart your server.

After your server has restarted, wait a few minutes, then check your app's performance!

If you use Java 2 Security, configure Java 2 Security to grant New Relic necessary permissions.

Screen websphere agent 1 normal.jpg
Servers > Application servers > Java and Process Management > Process Definition > Additional Properties > Java Virtual Machine: Add your -javaagent switch for the full path to your newrelic.jar file to the WebSphere Java Virtual Machine page.

Enable browser monitoring

WebSphere users must use manual instrumentation for page load timing (also known as real user monitoring or RUM). Auto instrumentation is not available for WebSphere.

Configure Java 2 Security and/or Administrative Security

If you are using Java 2 Security or WebSphere Admin Security, you must grant all jars inside the New Relic install folder the proper permissions. You can enable New Relic for all app servers by editing your java.policy file. Or, you can enable New Relic for each app server individually by editing that server's server.policy file:

Enable New Relic for all app servers

To enable New Relic for all app servers, edit java.policy:

  1. Open your java.policy file, located inside your WebSphere install directory at:

    YOUR_WEBSPHERE_INSTALL_DIRECTORY/java/jre/lib/security/java.policy
  2. Append the following text to your policy file, customizing the file: path to point to the folder containing newrelic.jar. Ensure you preserve the dash - at the end of the path, which grants all jars in the target folder the necessary permissions.

    grant codeBase "file:/PATH/TO/NEWRELIC/FOLDER/-" {
           permission java.security.AllPermission;
           permission java.net.SocketPermission "*.newrelic.com", "connect,accept,resolve";
    };

    The codeBase value must use slashes, not backslashes, as the directory separator, even on Windows systems.

  3. Restart your application server.
Enable New Relic for individual app servers

To enable New Relic for a single app server, edit that server's server.policy:

  1. Open your server.policy file, located inside your WebSphere install directory at:

    YOUR_WEBSPHERE_INSTALL_DIRECTORY/profiles/YOUR_APP_SERVER_NAME/properties/server.policy
  2. Append the following text to your policy file, customizing the file: path to point to the folder containing newrelic.jar. Ensure you preserve the dash - at the end of the path, which grants all jars in the target folder the necessary permissions.

    grant codeBase "file:/PATH/TO/NEWRELIC/FOLDER/-" {
           permission java.security.AllPermission;
           permission java.net.SocketPermission "*.newrelic.com", "connect,accept,resolve";
    };

    The codeBase value must use slashes, not backslashes, as the directory separator, even on Windows systems.

  3. Restart your application server.

For each app, Java security permissions are determined by the union of java.policy and server.policy. Do not put the same permission settings in multiple files.

For more on policy file syntax, see Default Policy Implementation and Policy File Syntax.

Enable PMI metrics access

To enable New Relic to access WebSphere PMI metrics you will need to configure WebSphere to monitor the necessary statistic sets.

Enable all statistic sets (recommended)

The simplest approach is to enable the collection of all statistic sets:

  1. If you are using Java 2 Security, ensure you have granted New Relic proper permissions.
  2. From the WebSphere admin console, select Monitoring and Tuning > Performance Monitoring Infrastructure (PMI) > (your server name).

    screen-websphere-pmi-metrics.png
    WebSphere Admin Console > Monitoring and Tuning > Performance Monitoring Infrastructure: To configure statistic sets, select your server name from the Performance Monitoring Infrastructure panel.
  3. Select the Enable Performance Monitoring Infrastructure (PMI) checkbox.
  4. In the Currently monitored statistic set section, select All.

    screen-websphere-select-all.png
    WebSphere Admin Console > Monitoring and Tuning > Performance Monitoring Infrastructure > (selected server): Select Enable Performance Monitoring and All to enable all PMI metrics.
  5. Select Apply to save your changes
Enable custom statistic sets (advanced)

You can also collect only the PMI metrics that New Relic monitors by default. To collect only some PMI metrics:

  1. If you are using Java 2 Security, ensure you have granted New Relic proper permissions.
  2. From the WebSphere admin console, select Monitoring and Tuning > Performance Monitoring Infrastructure (PMI) > (your server name).

    screen-websphere-pmi-metrics.png
    WebSphere Admin Console > Monitoring and Tuning > Performance Monitoring Infrastructure: To configure statistic sets, select your server name from the Performance Monitoring Infrastructure panel.
  3. Select the Enable Performance Monitoring Infrastructure (PMI) checkbox.
  4. Select Custom. From the custom statistic set list, enable the following metrics:
    1. In the ThreadPool category, select the ActiveCount and PoolSize checkboxes. Select Enable.
    2. In the Servlet Session Manager category, select the ActiveCount and LiveCount checkboxes. Select Enable.
    3. In the Transaction Manager category, select the CommittedCount, RolledbackCount, and GlobalTimeoutCount checkboxes. Select Enable.
  5. From the Messages panel, select Save directly to the master configuration to save your changes

Default PMI metrics

By default, New Relic collects the following PMI metrics, which appear in the JVM Metrics Page.

stats.ActiveCount
Attribute stats.ActiveCount
Object name pattern
WebSphere:type=ThreadPool,name=*,process=*,platform=*,node=*,*
New Relic metric
JmxBuiltIn/ThreadPool/WebContainer/Active
Type Simple
maximumSize
Attribute maximumSize
Object name pattern
WebSphere:type=ThreadPool,name=*,process=*,platform=*,node=*,*
New Relic metric
JmxBuiltIn/ThreadPool/WebContainer/Max
Type Simple
stats.CommittedCount
Attribute stats.CommittedCount
Object name pattern
WebSphere:j2eeType=JTAResource,type=TransactionService,name=*,process=*,platform=*,node=*,*
New Relic metric
JmxBuiltIn/JTA/TransactionService/Committed
Type Simple
stats.RolledbackCount
Attribute stats.RolledbackCount
Object name pattern
WebSphere:j2eeType=JTAResource,type=TransactionService,name=*,process=*,platform=*,node=*,*
New Relic metric
JmxBuiltIn/JTA/TransactionService/Rolled Back
Type Simple
stats.GlobalTimeoutCount
Attribute stats.GlobalTimeoutCount
Object name pattern
WebSphere:j2eeType=JTAResource,type=TransactionService,name=*,process=*,platform=*,node=*,*
New Relic metric
JmxBuiltIn/JTA/TransactionService/Timed Out
Type Simple
stats.LiveCount
Attribute stats.GlobalTimeoutCount
Object name pattern
WebSphere:type=SessionManager,name=*,process=*,platform=*,node=*,*
New Relic metric
JmxBuiltIn/Session/DefaultApplication#DefaultWebApplication.war/Active
Type Simple

If you want other PMI metrics besides these to be displayed in Custom Dashboards, they will need to be manually collected using JMX instrumentation.

For more help

Additional documentation resources include:

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.