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: From the New Relic menu bar, select APM > Applications > (selected 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 follow these installation instructions for your specific application server:
- The Java agent self-installer (Tomcat, Jetty, JBoss, and Glassfish)
- Manual installation (Apache Geronimo, Play, etc.)
- Java agent Frameworks (installing on AWS Elastic Beanstalk, ColdFusion, Glassfish, Tomcat on Windows, Websphere, etc.) Even if you do not see your app server here, New Relic's Java agent should work on any application server by passing the
-javaagent:/full/path/to/newrelic.jarswitch to the JVM.
As part of the installation, change the default application name to a meaningful name, and change the default newrelic.yml file permissions to be read/write only for the owner of the app server process.
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
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 (
app_name) in the local config file.
Extend your instrumentation
After installing the Java agent, extend your instrumentation:
- Custom instrumentation: Implement Java custom instrumentation via annotation or XML.
- Collect custom attributes: Collect custom attributes via API or XML file.
- Java agent API: Use the API to control, customize, or extend the functionality of the Java agent.
- Page load timing process: Integrate the Java agent with New Relic Browser to gain visibility into end-user activity.
- Circuit breaker for Java custom instrumentation: Use a circuit breaker to protect applications from over-instrumentation.
- Custom JMX instrumentation by YAML: View custom JMX metrics with a YAML custom instrumentation file.
- JVM metrics page: Collect metrics from the most common application servers via JMX.
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
audit_modein 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 adding the
ignore_status_codesto the newrelic.yml file when using the Java agent version 3.20.0 or higher. (If using an agent version lower than 3.20.0, a restart will still be required.)
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:
- No data appears: Find solutions when your Java application is not reporting data.
- Error starting app server: If you encounter an error starting the app server, the path to the agent jar file may not be correctly specified.
- Generating logs for troubleshooting: Generate
finestlogs to investigate errors while troubleshooting.
For more help
Additional documentation resources include:
- Java agent self-installer (how to install the New Relic Java agent)
- Upgrading the Java agent (how to upgrade New Relic for Java)
- Troubleshooting: No data appears (what to do if your Java application isn't reporting data)
- Web transaction naming (how transactions are named)
- Compatibility and requirements for the Java agent (system requirements for New Relic's Java agent)