Introduction to New Relic for Java

With New Relic's Java agent, you can track everything from performance issues to tiny errors within your code. New Relic's Java agent monitors your Java app, and provides visibility into the behavior of your JVM. After installing, you'll be able to quickly monitor transactions, dive deep into errors, and more.

To view your app's performance in the New Relic UI: Go to > (select an app) > Monitoring > Overview.

Compatibility and requirements

Before installing the Java agent, ensure your system meets the system requirements.


To use the Java agent, sign up for a New Relic account, and then see Install the Java agent. Or, see the documentation on Heroku, Maven, or Scala.

Startup configuration

The agent reads the startup configuration from the newrelic.yml file, which must be in the same directory as newrelic.jar. You can also override settings using Java system properties.

The agent needs the license_key and app_name settings at startup (bootstrap). You can customize the location of the log file and other settings in your newrelic.yml file.

If your app server runs multiple applications in the same JVM, see Java agent configuration for multiple applications.

Edit the configuration

You can configure application reporting from the New Relic web interface using server-side configuration. Changes will be applied to all agents reporting for your application when the JVM restarts. However, if you use server-side config, you must still maintain required settings (license_key and app_name) in the local config file.

Extend your instrumentation

After installing the Java agent, extend your instrumentation:

When to restart your JVM

When you make a change to your configuration or to your custom XML, in almost all cases it is necessary to restart your JVM.

There are only four situations where a restart is not necessary:

  • You are changing the log_level or audit_mode in the Java agent configuration file.
  • You are updating a custom instrumentation XML file in the extensions folder when using Java agent version 3.15.0 or higher. Updates will be reloaded within a minute. (If using an agent version lower than 3.15.0, a restart will still be required.)

  • You are changing the circuit breaker, as described in the troubleshooting tips for the circuit breaker for Java custom instrumentation.
  • You are ignoring or expecting errors by configuring the newrelic.yml file. This includes adding ignore_status_codes, expected_status_codes, ignore_classes, or expected_classes to the newrelic.yml file when using the Java agent version 3.38.0 or higher.

All other changes require an agent restart, which means restarting the JVM.

Troubleshoot your installation

If you encounter problems with the Java agent, see our troubleshooting information:

You can also view all troubleshooting docs. If you need additional assistance, get support at

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