Our Java APM agent auto-instruments your code so you can start monitoring applications. Read this for an overview of the generic APM installation process. For more specific instructions, use monitor your Java app to find the specific resource for your Java app configuration.
1. Prepare to install
Check the following:
- Review the compatibility and requirements.
- Check if your environment requires additional or alternative install steps.
When you're ready, use the guided installation for an automated install. If you're in the EU, select that option. Or for a manual approach, follow the instructions in this document to complete a basic Java agent installation. Either way, you need a New Relic account. (It's free, forever.)
2. Get the agent
Download newrelic-java.zip
using curl
, Invoke-WebRequest
(PowerShell), or the New Relic UI:
3. Configure the agent
Here's how to do a basic setup with agent configuration settings in newrelic.yml
.
Tip
For an advanced installation, you can pass settings with environment variables, Java system properties, or server-side configuration. To understand the precedence of these configuration settings, see Java agent configuration: Config file.
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 newrelic.yml
:
Find the line with
license_key
.Replace '<%= license_key %>' with your license. For example:
license_key: 456n20n1367ov2s174v51nvn789d21s67v26NRALFind the line with
app_name
.Replace
My Application
with a name that helps you identify the application. For example:app_name: Tax CalculatorTip
If you need tips about how to name your application, see Name your application.
Add optional settings that you want, such as agent logging and distributed tracing (or add them later).
Save and close
newrelic.yml
.
4. Install the agent
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
java.endorsed.dirs
.
To install the Java agent:
In your application server/container directory structure, create a directory for New Relic files (for example,
/opt/newrelic
).Copy all the New Relic files from your unzipped
newrelic
directory into your new directory.Make sure that your application server/container includes this option when it starts Java (for tips on how to do this with your tool or framework, see JVM arguments):
-javaagent:/full/path/to/newrelic.jar
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 Summary page. If nothing appears, follow the troubleshooting procedures.
5. Post-installation tasks
If you are using newrelic.yml
to make configuration settings, consider the following:
- We recommend you change the default
newrelic.yml
file permissions to read/write only for the owner of the application server process. - As you would with other important files, be sure
newrelic.yml
is part of your backup routine. - We recommend using New Relic Diagnostics to validate your settings, either before or after you deploy.
View logs for your APM and infrastructure data
You can also bring your logs and application's data together to make troubleshooting easier and faster. With logs in context, you can see log messages related to your errors and traces directly in your app's UI. You can also see logs in context of your infrastructure data, such as Kubernetes clusters. No need to switch to another page in the New Relic UI.
What's next?
Here are some additional topics to consider:
- For Docker questions, see Install New Relic Java agent for Docker.
- View your app in New Relic and get comfortable with the user interface.
- Read the documentation about APM. For example, read about the Summary page, the JVM metrics page, the Transactions page, and performance monitoring with CodeStream.
- Query your data using NRQL (New Relic Query Language).
- Learn about setting up custom instrumentation and async instrumentation for application activity not monitored by default.