The New Relic Android agent provides performance monitoring instrumentation for Android applications. With New Relic's Android agent, you can track everything from performance issues to tiny errors within your code. Our agent monitors your Android app and provides visibility into its behavior during runtime.
Agent releases follow semantic versioning conventions. See agent release notes for full details on releases and downloads. Agent artifacts can also be found on Maven.
The Android agent is comprised of several modules that are used together to instrument client applications:
Agent (:agent)
The agent module wraps agent-core and instrumentation modules into an Android-compatible library project.
The output is android-agent-<version>.jar
Agent Core (:agent-core)
The agent-core module contains common runtime artifacts collected and embedded into a single JAR:
- The SDK interface (API)
- The agent model
- Instrumentation and metrics
- Data collection and reporting
- Crash detection
- Events and analytics management
The output is agent-core-<version>.jar
Instrumentation (:instrumentation)
The instrumentation module performs instrumentation during builds on client code using bytecode rewriting.
The output is instrumentation-<version>.jar
Gradle plugin (:plugins:gradle)
The Gradle plugin auto-instruments client code during builds when applied to Android build configurations.
The output is agent-gradle-plugin-<version>.jar
Prior to building the agent, update the repo's submodules from the command line
git submodule update --init --recursive
NDK agent (:ndk:agent-ndk)
The NDK agent submodule captures native crashes resulting from raised signals and uncaught runtime exceptions from C and C++ code. After building, Android native agent artifacts are located in agent-ndk/build/outputs/aar
The output is agent-ndk-<variant>.aar
Tool dependencies must to be installed and configured for your environment prior to building. The Android agent requires the following tools to build:
| Dependency | Version |
|---|---|
| Java | JDK 11 |
| Android Gradle Plugin | 7.1 |
| Gradle | 7.2 |
| minSDK | 24 |
| compileSDK | 28 |
| targetSDK | 28 |
| buildtools | 28.0.2 |
| Dependency | Version |
|---|---|
| NDK | 21.4.7075529 or higher |
| Cmake | 3.18.1 or higher |
- Download the Android Studio IDE.
- Install SDK Platforms. SDK Manager left pane: Appearances & Behavior -> System Settings -> Android SDK. Right Pane selects the SDK Platforms.
Android Studio must be configured with the Android Native Development Kit (NDK) installed. Update
cmakeinTools->SDK Manager->SDK Tools - From Android Studio's main menu, select
File->Import Project->Next. Provide the full path to your cloned agent repo.
The JDK 11 implementation provided by Android Studio is the default JDK used when building from the IDE.
See Configure with Gradle and Android Studio as well as the Android agent compatibility and requirements documentation for an overview of what is supported by the Android agent.
The agent can be built from either the command line Gradle or Android Studio.
The agent version is contained in gradle.properties, but can be overridden by adding -Pnewrelic.agent.version={version} to the Gradlew command line.
To build the android-agent JAR, run the following command from the project root directory:
./gradlew clean assemble
To build and run all checks:
./gradlew clean build
From Android Studio, each module should be built using the Release configuration.
The agent uses JUnit, Mockito and Robolectric to mock and test agent functionality.
./gradlew test
| Module | Reports |
|---|---|
agent |
agent/build/reports/tests/testReleaseUnitTest/index.html |
agent-core |
agent-core/build/reports/tests/test/index.html |
instrumentation |
instrumentation/build/reports/tests/test/index.html |
./gradlew :plugins:gradle:check -P regressions
| Module | Reports |
|---|---|
plugins:gradle |
plugins/gradle/build/reports/tests/test/index.html |
./gradlew lint
| Reports | |
|---|---|
Lint |
file://agent/build/reports/lint-results-release.html |
The simplest way to debug the agent is at runtime through its test app.
- Create a test app that has been configured to use the agent.
- Run a debugging session of the test app, but before you start execution, browse the
External Librariesdependencies from the ASProjectpane (all the way at the bottom). - Drill down to
External Libraries/android-agent-{version}/android-agent-{version}.jar/com/newrelic/agent/android/NewRelic - Open the file, and set a break point just inside the start() method. Now debug the app and execution will break inside the agent.
Debugging the class rewriter or plugins is more difficult but you can use a Remote debugging session and command line Gradle builds.
-
In Android Studio, create a
RemoteRun/Debug configuration. -
From your command line, export the
GRADLE_OPTSenvironment variable:export GRADLE_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5050"
-
Initiate a command line build of your test app:
./gradlew clean assembleDebug
You should then see
Listening for transport dt_socket at address: 5005 -
Set some breakpoints in the agent or class rewriter, and start the remote debugging session
-
You are now live-debugging the Gradle build, specifically those tasks that interact with Agent code
-
To remove GRADLE_OPTS from the environment,
unset GRADLE_OPTS
Starting in version 3.0, Android Studio has made it easier to debug client builds using remote debugging. You no longer have
to declare a GRADLE_OPTS environment variable. Simply start a command line build with
-Dorg.gradle.debug=true --no-daemon
declared on the build command line, or as properties in the gradle.properties file.
When set to true, Gradle will run the build with remote debugging enabled, listening on port 5005. Note that this is the equivalent of adding GRADLE_OPTS above.
This will suspend the virtual machine until a debugger is attached. You will no longer see Listening for transport dt_socket at address: 5005, but instead now see > Starting Daemon when the build waits for a remote debugger to attach. Simply run your Remote configuration (created above) and the debugger will stop at any breakpoints set.
The easiest way to debug the Agent Gradle Plugin is to run a plugin functional test.
When the GradleRunner is created with withDebug(true), the Gradle process is available for debugging and breakpoints can be set anywhere in the plugin code.
When the test is run, the breakpoints will be triggered and the state of the plugin available for inspection.
Properties are configurable values used throughout the agent. At present, these include:
| Property | Use decscription |
|---|---|
newrelic.agent.version |
The Semantic version of the agent, i.e., 7.0.0 |
newrelic.agent.build |
The build number of the agent. Usually provided by CI, will appear as SNAPSHOT when built locally |
The agent's Gradle tasks represent pipeline targets, in other words, what parts of the agent should be built.
Specify the target task after any properties settings, i.e., ./gradlew -Pnewrelic.agent.version=6.10.0 {task} {task} ...
Build the agent project
Build the agent project and run all tests
Build and test the agent project
Build and install artifacts to the in-project Maven local repository (${rootProject.buildDir}/.m2/repository)
Agent pre-release snapshots will be posted to https://oss.sonatype.org/content/repositories/comnewrelic-{snapshotId}
The Agent SDK provides information on thw various agent SDK methods available to clients.
New Relic hosts and moderates an online forum where customers, users, maintainers, contributors, and New Relic employees can discuss and collaborate:
- 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.
Github Issues are not open to the public at the moment. Please contact our support team or one of the support channels to submit your issues, feature requests, etc.
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 the New Relic Android Agent! Keep in mind that 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 would like to contribute to this project, review these guidelines.
To all contributors, we thank you! Without your contribution, this project would not be what it is today. If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), 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 our bug bounty program.
If you would like to contribute to this project, review these guidelines.
To all contributors, we thank you! Without your contribution, this project would not be what it is today. We also host a community project page dedicated to New Relic Android Agent.
newrelic-android-agent is licensed under the Apache 2.0 License.
The New Relic Android agent also uses source code from third-party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third-party notices.