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:
- General installation instructions
- Application server specific instructions
- Additional installation instructions (Maven, Gradle, etc)
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:
- General agent configuration
- Collecting default/custom Java agent attributes
- Adding custom instrumentation to your application
- Java agent API guides
- Java agent async instrumentation API guides
- Troubleshooting
- Java agent Javadocs
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:
jdk8=/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home
Additionally, the -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:
jdk17=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
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:
- Agent:
newrelic-agent/build/newrelicJar/newrelic.jar - Agent API:
newrelic-api/build/libs/newrelic-api-*.jar
The following modules have specific requirements to be built. The instructions for each is in the module's README.md.
- aws-wrap-0.7.0
- jboss-7
- jdbc-inet-merlia
- jdbc-inet-oranxo
- jdbc-ojdbc
- jdbc-sybase-6
- open-liberty-jakarta-21.0.0.12
- resin-3
- weblogic-12.2
- weblogic-12
- weblogic-jmx-12.2.1
- weblogic-jmx-12
- websphere-8
- websphere-jmx-7
- websphere-liberty-profile-8.5.5.5
- websphere-liberty-profile-dispatcher-8.5.5.5
- websphere-liberty-profile-environment-8.5.5.5
We recommend using IntelliJ IDEA for development on this project. Configure as follows:
- Select
File > Openand selectnewrelic-java-agent/build.gradle. - Select
Open as Project. - Wait for the builds, imports, and indexing to finish. This may take a few minutes due to the project's size and complexity.
- Import Code Style: from
dev-tools/code-style/java-agent-code-style.xml, selectPreferences > Editor > Code Style > gear cog > Import Scheme > IntelliJ IDEA code style XML. - Add Java 8 SDK: select
File > Project Structure... > Platform Settings > SDKs > Add New SDK. - Configure project SDK and target language level: select
File > Project Structure... > Project Settings > Project.- Set
Project SDKto JDK 1.8 - Set
Project language levelto 8
- Set
- Increase Intellij memory heap if you encounter "Low Memory" issues. Recommended: 2048 MB. To do this, select
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
The agent utilizes Jacoco and Spotbugs to measure and improve code quality. We also use Codecov to report code coverage. Jacoco and Spotbug tools are configured through the gradle build system. Codecov is configured and uploaded through a GitHub Actions workflow.
The jacocoTestReport task depends on the unit test task. It uses data generated by the test task to create the coverage reports. jacocoTestReport task creates an html and xml file of the output. We store these files locally in the respective module's build/reports/jacoco folder. The html file can be opened normally in a browser.
Some subprojects have not been configured to run because the code is either too trivial to test or it is code that is only compile time dependency and not necessary to test due to the nature
of how the agent instruments customer code.
To run jacoco, execute unit tests in the usual ways given under the section Convential unit tests. The jacocoTestReport task will run automatically after the unit tests complete.
We use a codecov github action to upload the jacoco coverage reports to codecov.io. Additionally, codecov will comment on pull requests (PRs) with a quick overview of how PRs (and relevant commits) will affect the code coverage as compared to the main branch.
Spotbugs is a static code analysis tool to identify bugs in Java programs. It utilizes the Spotbugs gradle plugin. The projects that are scanned by Spotbugs are:
- newrelic-agent
- newrelic-weaver
- agent-bridge
- agent-model
- newrelic-api
To run Spotbugs, execute the following command:
./gradlew spotbugsMain --parallel
The task will generate both XML and HTML files in the build/spotbugs folder underneath each subproject's top level folder.
The HTML file can be opened normally in a browser. The XML files can be imported into the Spotbugs UI.
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.
Support Channels
- New Relic Documentation: Comprehensive guidance for using our platform
- New Relic Community: The best place to engage in troubleshooting questions
- New Relic Developer: Resources for building a custom observability applications
- New Relic University: A range of online training for New Relic users of every level
- New Relic Technical Support 24/7/365 ticketed support. Read more about our Technical Support Offerings.
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.
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 opensource@newrelic.com.
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 our bug bounty program.
newrelic-java-agent is licensed under the Apache 2.0 License.
The 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.
