With New Relic's Java agent for bytecode instrumentation, you can track everything from performance issues to tiny errors within your code. Our Java agent monitors your Java app and provides visibility into the behavior of your JVM. After installing, you can quickly monitor transactions, dive deep into errors, and more.
Java agent releases follow semantic versioning conventions. See Java agent release notes for full details on releases and downloads. Java agent artifacts can also be found on Maven.
To install the Java agent you need to configure your JVM to load the agent during your application's
premain start-up by passing the
-javaagent:/full/path/to/newrelic.jar command-line argument. This process varies depending on your environment/application server.
For full details see:
See the getting started guide as well as the compatibility and requirements documentation for an overview of what is supported by the Java agent.
See the following documentation for specific use cases of the Java agent:
The Java agent uses a variety of JDK versions when building and running tests. These need to be installed and configured for your environment.
Edit or create the
~/.gradle/gradle.properties file and add the following JDKs, ensuring that the vendors/versions match what is installed in your environment (Mac OS X examples shown).
JDK 8 is required to build the agent:
-PtestN Gradle property can be used to run tests on a specific JDK version which may require further JDK configuration.
To keep test times reasonable the project only allows testing against supported LTS Java releases as well as the latest non-LTS release of Java.
For example to run tests with Java 17, the
-Ptest17 Gradle property would cause the test to use
jdk17 as configured below:
The Java agent requires JDK 8 to build; your
JAVA_HOME must be set to this JDK version.
To build the agent jar, run the following command from the project root directory:
./gradlew clean jar --parallel
To build and run all checks:
./gradlew clean build --parallel
After building, Java agent artifacts are located here:
We recommend using IntelliJ IDEA for development on this project. Configure as follows:
File > Openand select
Open as Project.
Preferences > Editor > Code Style > gear cog > Import Scheme > IntelliJ IDEA code style XML.
File > Project Structure... > Platform Settings > SDKs > Add New SDK.
File > Project Structure... > Project Settings > Project.
Project SDKto JDK 1.8
Project language levelto 8
Help > Change Memory Settings > Save and Restart.
The Java agent utilizes the following four distinct test suites, each of which is supported by a test framework. Each has specific strengths and weaknesses and each serves a particular purpose.
The unit tests are conventional JUnit tests. The supporting framework is the industry-standard JUnit dependency. Unit tests rely on a variety of different mock object frameworks combined with complex test initialization patterns that simulate agent initialization. Scala test tasks are excluded by default. Including the -PincludeScala project property includes Scala test tasks.
Run all unit tests:
./gradlew -PnoInstrumentation clean test --continue --parallel
Run an individual unit test:
./gradlew -PnoInstrumentation clean newrelic-weaver:test --tests "com.newrelic.weave.LineNumberWeaveTest.testRemoveWeaveLineNumbers" --parallel
Run an individual unit test on a specific version of Java:
./gradlew -Ptest17 -PnoInstrumentation clean newrelic-weaver:test --tests "com.newrelic.weave.LineNumberWeaveTest.testRemoveWeaveLineNumbers" --parallel
The functional tests are JUnit tests for which Gradle ensures that each test class runs in a separate subprocess that initializes the agent. The test framework is a combination of industry-standard JUnit, Gradle, a small Gradle test executor task, and some special classes that address limitations of the base framework.
Note: Functional tests require that the Java agent jar artifact is present in the build directory.
Functional tests are located in
newrelic-java-agent/functional_test/src/test/ and are run from the root
newrelic-java-agent directory as follows:
Run all functional tests:
./gradlew functional_test:test --continue --parallel
Run an individual functional test:
./gradlew functional_test:test --tests test.newrelic.test.agent.AgentTest --parallel
The instrumentation module tests are also JUnit tests. The framework is the industry-standard JUnit dependency modified by a custom test runner and class loader that support bytecode weaving within the test without the need to fully initialize the agent. Note: fully initializing the agent is not possible when running in an uninstrumented reusable test process like an IntelliJ test subprocess or Gradle daemon. There is also an "introspector" (somewhat equivalent to a local mock collector) for test assertions.
Some of the instrumentation tests use Testcontainers so you might need to have Docker installed to run them locally.
Instrumentation tests are located in each instrumentation module at
newrelic-java-agent/instrumentation/<INSTRUMENTATION MODULE>/src/test and are run from the root
newrelic-java-agent directory as follows:
Run all instrumentation module tests:
./gradlew instrumentation:test --continue --parallel
Run all tests for a specific instrumentation module:
./gradlew instrumentation:akka-http-core-10.0.11:test --parallel
Run a single test for a specific instrumentation module:
./gradlew instrumentation:vertx-web-3.2.0:test --tests com.nr.vertx.instrumentation.RoutingTest --parallel
Run all tests for a specific Scala instrumentation module:
./gradlew -PincludeScala instrumentation:sttp-2.13_2.2.3:test --parallel
Should you need assistance with New Relic products, you are in good hands with several diagnostic tools and support channels.
This troubleshooting framework steps you through common troubleshooting questions.
New Relic offers NRDiag, a client-side diagnostic utility that automatically detects common problems with New Relic agents. If NRDiag detects a problem, it suggests troubleshooting steps. NRDiag can also automatically attach troubleshooting data to a New Relic Support ticket.
If the issue has been confirmed as a bug or is a Feature request, please file a Github issue.
At New Relic we take your privacy and the security of your information seriously, and are committed to protecting your information. We must emphasize the importance of not sharing personal data in public forums, and ask all users to scrub logs and diagnostic information for sensitive information, whether personal, proprietary, or otherwise.
We define “Personal Data” as any information relating to an identified or identifiable individual, including, for example, your name, phone number, post code or zip code, Device ID, IP address and email address.
Please review New Relic’s General Data Privacy Notice for more information.
See our roadmap, to learn more about our product vision, understand our plans, and provide us valuable feedback.
We encourage your contributions to improve
newrelic-java-agent. Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].
A note about vulnerabilities
As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.
newrelic-java-agent is licensed under the Apache 2.0 License.
newrelic-java-agent also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document and our Java agent licenses public documentation.