New Relic Java Agent for IBM WAS
This describes how to configure New Relic's Java agent if you are using IBM WebSphere Application
Server.
Compatible IBM JVM versions
New Relic supports all versions of WebSphere that are compatible with the Java agent. However,
certain versions of the IBM JVM are incompatible with the Java agent due to known issues in the
IBM JVM.
New Relic's Java agent is compatible with these major versions of the IBM JVM:
• 8: All versions
• 7: Version 7.0.0 SR3 or higher
Download New Relic Agent
Download [Link] using curl, Invoke-WebRequest (PowerShell), or the New Relic
UI:
Using CURL
Complete the following:
1. Start a command-line session.
2. Change to a temporary directory where you can download the zip file.
3. Execute this curl command:
curl -O [Link]
4. Unzip [Link]
Using New Relic UI
Complete the following:
1. Sign in to your New Relic Account
2. Go to APM main screen and click “add more”
3. Select the java web agent:
4. Get a license key:
5. Download the java agent:
Configure the agent
Here's how to do a basic setup with agent configuration settings in [Link].
The Java agent requires the license_key and app_name settings at startup. All the other settings
are optional, and you can review them in Java agent configuration: Config file.
Go to the unzipped installation file, and inside the newrelic subdirectory, edit [Link]:
1. Find the line with license_key.
2. Replace '<%= license_key %>' with your license.
3. Find the line with app_name.
4. Replace My Application with a name that helps you identify the application.
5. Add optional settings that you want, such as agent logging and distributed tracing (or add
them later).
6. Save and close [Link].
Install the agent (Basic)
The Java agent installation involves copying all the unzipped New Relic files into the directory
structure of your application server/container. For example, you can create a /opt/newrelic
directory, but if you want to put the files elsewhere, make sure of the following:
• The .jar files in the directory cannot be on the classpath.
• The .jar files cannot be in directories specified in [Link].
To install the Java agent:
1. In your application server/container directory structure, create a directory for New Relic files
(for example, /opt/newrelic).
2. Copy all the New Relic files from your unzipped newrelic directory into your new directory.
3. Make sure that your application server/container includes this option when it starts Java:
-javaagent:/full/path/to/[Link]
4. Start or restart your application server/container.
Generate some traffic for your app, and then wait a few minutes for data to appear in the APM
Overview page. If nothing appears, follow the troubleshooting procedures.
WebSphere
To pass the -javaagent argument on WebSphere:
1. From the admin console, select Servers > Application servers > (select a server) >
Configuration > Service Infrastructure > Java and Process Management.
2. Select Process Definition > Additional Properties, then select Java Virtual Machine.
3. In the Generic JVM arguments field, add the -javaagent argument for your
[Link] file:
-javaagent:/full/path/to/[Link]
4. Select Apply, then select Save.
5. Restart your server.
For more information, see the documentation about collecting WebSphere PMI metrics.
WebSphere Liberty Profile
To pass the -javaagent argument on WebSphere Liberty Profile:
1. Edit ${[Link]}/[Link].
2. Add the -javaagent argument to point to your [Link] file:
-javaagent:/full/path/to/[Link]
3. Restart your server.
Post-installation tasks
If you are using [Link] to make configuration settings, consider the following:
We recommend you change the default [Link] file permissions to read/write only for the
owner of the application server process.
As you would with other important files, be sure [Link] is part of your backup routine.
Java 2 Security
If you are using Java 2 Security and WebSphere, you must grant the Java agent additional
permissions before it can execute properly.
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 [Link] file. Or, you can enable New Relic for each app server individually by editing that
server's [Link] file:
To enable New Relic for all app servers, edit [Link]:
1. Open your [Link] file, located inside your WebSphere install directory at:
YOUR_WEBSPHERE_INSTALL_DIRECTORY/java/jre/lib/security/[Link]
2. Append the following text to your policy file, customizing the file: path to point to the
folder containing [Link]. 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 [Link];
permission [Link] "specifyStreamHandler";
permission [Link] "*.[Link]", "connect,accept,resolve";
};
3. Restart your application server.
To enable New Relic for a single app server, edit that server's [Link]:
1. Open your [Link] file, located inside your WebSphere install directory at:
YOUR_WEBSPHERE_INSTALL_DIRECTORY/profiles/YOUR_APP_SERVER_NAME/properties/[Link]
2. Append the following text to your policy file, customizing the file: path to point to the
folder containing [Link]. 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 [Link];
permission [Link] "specifyStreamHandler";
permission [Link] "*.[Link]", "connect,accept,resolve";
};
3. Restart your application server.
New Relic Browser
To use New Relic Browser monitoring when running the Java agent on WebSphere, you must
manually enable Browser monitoring.
WebSphere PMI metrics
You can configure the Java agent to capture additional WebSphere PMI metrics. These metrics will
appear on the New Relic JVM metrics page.
Instance and display names
You can configure the Java agent to change the default behavior of instance names or display
names.
