From eef5011ade982c485f5b01d213115cc07d357944 Mon Sep 17 00:00:00 2001 From: Cameron Thomas Date: Tue, 20 Aug 2024 10:40:48 -0700 Subject: [PATCH 1/7] [NR-303342] Update manual install steps for Android plugin The Android agent's Gradle plugin is now deployed to the Gradle Plugin Portal as well as MavenCentral(). --- .../install-android-agent-gradle.mdx | 152 +++++++++++------- 1 file changed, 96 insertions(+), 56 deletions(-) diff --git a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx index 65090b5c3af..93ee21fccdd 100644 --- a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx +++ b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx @@ -50,48 +50,18 @@ To install the Android agent, you need to use our [guided install](https://onenr These procedures appear in our guided install. Keep in mind that even if you're updating your build files through the docs, you still need to add your app to New Relic and grab your generated app token from the guided install. You cannot capture data about your Android apps otherwise. -1. Add the following code to your `build.gradle` files found in the Gradle & Android Studio tab. You need to update the top-level build snippet and each sub-module that you want to instrument. - - - In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. - - ```groovy - buildscript { - repositories { - mavenCentral() - } +## Resolve and apply the New Relic Android Agent Gradle plugin +```In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version.``` - dependencies { - classpath "com.newrelic.agent.android:agent-gradle-plugin:AGENT_VERSION" - } - } - ``` - +Starting with version 7.6.0, the New relic Android Gradle plugin is available on the [Gradle Plugin Portal](). This greatly simplifies the resolution and loading of community plugins. - - In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. +Newer apps should follow the instructions to [Apply the plugin using the plugins DSL block]](#plugin-dsl) to use agent plugin hosted on [Gradle Plugin Portal](https://plugins.gradle.org/). - ```groovy - repositories { - mavenCentral() - } +If adding the New Relic Android agent to an older app, follow the instructions to [apply the plugin using the buildscript](#buildscript) - apply plugin: 'android' - apply plugin: 'newrelic' +Gradle [guidance](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations) on the various approaches to resolving plugins. - dependencies { - implementation 'com.newrelic.agent.android:android-agent:AGENT_VERSION' - } - ``` - - 2. Set app permissions. Ensure that your Android app requests `INTERNET` and `ACCESS_NETWORK_STATE` permissions by adding these lines to your `AndroidManifest.xml` file: @@ -126,12 +96,94 @@ These procedures appear in our guided install. Keep in mind that even if you're 7. View your data for your Android app. Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**. + ## Configure the Android agent for Gradle Plugin Portal [#plugin-portal] -Because the Android agent isn't yet available as a community plugin, you need to provide the classpath through [MavenCentral](https://mvnrepository.com/artifact/com.newrelic.agent.android/agent-gradle-plugin) so the agent can instrument your Android app. If you've configured your app to look for plugins through Gradle Plugin Portal, you need to repeat this step in the `settings.gradle(.kts)` file. +Starting with agent version 7.6.0, the Android agent plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/) as a community plugin. The Gradle plugin DSL simpifies adding plugin dependencies to apps. + + + + + In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. -1. Add this snippet to your `settings.gradle(.kts)` file through `pluginManagement {}` block: + ```groovy + plugins { + // for binary Gradle plugins that need to be resolved + id("com.newrelic.agent.android") version "AGENT_VERSION" apply false + } + ``` + + + In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. + + ```groovy + plugins { + id 'com.newrelic.agent.android' + } + + dependencies { + implementation 'com.newrelic.agent.android:android-agent:AGENT_VERSION' + } + ``` + + + + +### Apply the plugin using the plugins DSL {} block [#plugin-dsl] + +The preferred and current approach to declaring plugin dependencies: apps must use the fully qualified form of the plugin id (`com.newrelic.agent.android`) in order to resolve the plugin. + + +1. Declare the New Relic plugin to the top-level `build.gradle(.kts)` file using the Gradle Plugin Portal plugin ID: + + ```groovy + plugins { + // for binary Gradle plugins that need to be resolved + id("com.newrelic.agent.android") version "AGENT_VERSION" apply false + } + ``` + +2. Apply the plugin to the app-level build file, as well as any other sub-module to be instrumented: + + ```groovy + plugins { + id("com.newrelic.agent.android") + } + ``` + + +Gradle provides guidance on [Applying plugins using the plugins{} block](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). + + +### Apply the plugin using the buildscript{} block [#buildscript] + +The New Relic Android Agent plugin is co-hosted on MavenCentral, but uses the legacy plugin ID ('newrelic'). Customers who prefer to use the legacy plugin ID must provide the classpath to [MavenCentral](https://mvnrepository.com/artifact/com.newrelic.agent.android/agent-gradle-plugin) to resolve the location of the plugin during builds. + + +To prefer MavenCentral over the Gradle Plugin Portal, you need to make the following changes to Gradle files: + +1. Add this snippet to your top-level `build.gradle(.kts)` file: + ```groovy + buildscript { + repositories { + mavenCentral() + } + + // not required if plugin classpath in resolutionStrategy{} below + dependencies { + classpath "com.newrelic.agent.android:agent-gradle-plugin:AGENT_VERSION" + } + } + ``` + +2. Add this snippet to your `settings.gradle(.kts)` file through `pluginManagement {}` block: ```groovy pluginManagement { repositories { @@ -139,42 +191,30 @@ Because the Android agent isn't yet available as a community plugin, you need to } resolutionStrategy { eachPlugin { - if (requested.id.id.startsWith("newrelic")) { + // not required if using `classpath dependency` above + if (requested.id.id.startsWith("newrelic") || requested.id.id.startsWith("com.newrelic.agent.android"))) { useModule("com.newrelic.agent.android:agent-gradle-plugin:${AGENT_VERSION}") } } } - - // optional: define as a community plugin here or in root level build file - - // for core Gradle plugins or plugins already available to the build script plugins { - id("newrelic") version "${AGENT_VERSION}" + id("newrelic") apply false } } ``` -2. Declare the New Relic plugin: +3. Apply the plugin to the app-level build file, as well as any other submodule to be instrumented: ```groovy plugins { - // for binary Gradle plugins that need to be resolved - id("newrelic") version "AGENT_VERSION" apply false - } - ``` - -3. Apply the plugin to the app-level build files: - - ```groovy - plugins { - id("com.android.application") - id("org.jetbrains.kotlin.android") id("newrelic") } ``` + In the above snippets, `AGENT_VERSION` represents your agent version number. We strongly recommend you use the latest agent for set up. + ## Android 4.x: Multidex support [#4x-multidex] Mobile monitoring for Android versions older than Android 5.0 (API level 21) use the Dalvik runtime to execute app code. By default, Dalvik limits apps to a single `classes.dex` bytecode file per APK. To get around this limitation, you must [enable multidex support](https://developer.android.com/studio/build/multidex.html). Then you can use the [multidex support library](https://developer.android.com/tools/support-library/features.html#multidex), which becomes part of the primary DEX file of your app. The library manages access to the additional DEX files and their containing code. From e0ac17c8ba28c66d9de608782f1ba832a1bd1dbb Mon Sep 17 00:00:00 2001 From: a-sassman Date: Wed, 21 Aug 2024 09:08:31 -0700 Subject: [PATCH 2/7] fix(mobile): tech writer review --- .../install-android-agent-gradle.mdx | 61 ++++++++++--------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx index 93ee21fccdd..064d64ac051 100644 --- a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx +++ b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx @@ -7,7 +7,7 @@ tags: translate: - jp - kr -freshnessValidatedDate: 2024-11-30 +freshnessValidatedDate: 2024-08-21 metaDescription: 'New accounts: Get Android app monitoring in New Relic at newrelic.com/signup. Existing accounts: Add mobile monitoring to your Android apps from the UI.' redirects: - /docs/mobile-apps/troubleshooting-eclipse-configurations @@ -51,50 +51,52 @@ To install the Android agent, you need to use our [guided install](https://onenr These procedures appear in our guided install. Keep in mind that even if you're updating your build files through the docs, you still need to add your app to New Relic and grab your generated app token from the guided install. You cannot capture data about your Android apps otherwise. -## Resolve and apply the New Relic Android Agent Gradle plugin -```In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version.``` +## Resolve and apply the New Relic Android agent Gradle plugin -Starting with version 7.6.0, the New relic Android Gradle plugin is available on the [Gradle Plugin Portal](). This greatly simplifies the resolution and loading of community plugins. +In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version.``` -Newer apps should follow the instructions to [Apply the plugin using the plugins DSL block]](#plugin-dsl) to use agent plugin hosted on [Gradle Plugin Portal](https://plugins.gradle.org/). +Starting with version 7.6.0, the New relic Android Gradle plugin is available on the [Gradle Plugin Portal](). This greatly simplifies the resolution and loading of community plugins. -If adding the New Relic Android agent to an older app, follow the instructions to [apply the plugin using the buildscript](#buildscript) +Newer apps should follow the instructions to [Apply the plugin using the plugins DSL block](#plugin-dsl) to use agent plugin hosted on [Gradle Plugin Portal](https://plugins.gradle.org/). -Gradle [guidance](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations) on the various approaches to resolving plugins. +If adding the New Relic Android agent to an older app, follow the instructions to [apply the plugin using the buildscript](#buildscript). For guidance on different approaches to resolving plugins, see [Resolving plugins](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations). -2. Set app permissions. Ensure that your Android app requests `INTERNET` and `ACCESS_NETWORK_STATE` permissions by adding these lines to your `AndroidManifest.xml` file: +1. Set app permissions. Update your `AndroidManifest.xml` file to allow your app to access the internet and check network state: ```xml ``` -3. Start the Android agent. In your default Activity found in your manifest, import the `NewRelic` class: +2. Start the Android agent. In your main Activity class (`onCreate` method), import the `NewRelic` class: ```java import com.newrelic.agent.android.NewRelic; ``` - We don't support starting the agent in other classes, as that can cause unexpected or unstable behavior. + + Starting the agent in other classes is not supported. + -4. After you've imported the `NewRelic` class, you need to add an additional snippet to the `onCreate()` method, which includes your app token, which is generated in the guided install. The snippet looks like this: +3. Replace `GENERATED_TOKEN` with your actual app token (obtained during guided install) and add this code: ```java NewRelic.withApplicationToken("GENERATED_TOKEN").start(this.getApplicationContext()); ``` -5. If you're using minification (for example, like with ProGuard or Dexguard), you need to add `newrelic.properties` file to your app-level directory (_projectname/app_). This step only applies to ProGuard and DexGuard users. +4. (Optional) Configure for minification: - ```ini - com.newrelic.application_token=GENERATED_TOKEN - ``` + 1. If you use ProGuard or Dexguard for code shrinking, create a `newrelic.properties` file in your app-level directory (`_projectname/app_`). + 2. Add this line to the file, replacing `GENERATED_TOKEN` with your actual token: + ```ini + com.newrelic.application_token=GENERATED_TOKEN + ``` + 3. To finish set up for minification, follow the steps in [configure ProGuard or DexGuard for Android apps](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-proguard-or-dexguard-android-apps). - To finish set up for minification, follow the steps in [configure ProGuard or DexGuard for Android apps](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-proguard-or-dexguard-android-apps). +5. Clean your project, then run your app in an emulator or device to generate traffic. Wait a few minutes as your agent captures that data. -6. Clean your project, then run your app in an emulator or device to generate traffic. Wait a few minutes as your agent captures that data. - -7. View your data for your Android app. Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**. +6. View your app's data on New Relic by going to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**. ## Configure the Android agent for Gradle Plugin Portal [#plugin-portal] @@ -105,7 +107,7 @@ Starting with agent version 7.6.0, the Android agent plugin is available on the In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. @@ -119,7 +121,7 @@ Starting with agent version 7.6.0, the Android agent plugin is available on the In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. @@ -136,9 +138,9 @@ Starting with agent version 7.6.0, the Android agent plugin is available on the -### Apply the plugin using the plugins DSL {} block [#plugin-dsl] +### Apply the plugin using the `plugins` DSL block [#plugin-dsl] -The preferred and current approach to declaring plugin dependencies: apps must use the fully qualified form of the plugin id (`com.newrelic.agent.android`) in order to resolve the plugin. +The recommended approach for managing plugin dependencies in Gradle utilizes the `plugins` DSL block. This section details applying the fully qualified form of the plugin id (`com.newrelic.agent.android`) within this structure. 1. Declare the New Relic plugin to the top-level `build.gradle(.kts)` file using the Gradle Plugin Portal plugin ID: @@ -150,7 +152,7 @@ The preferred and current approach to declaring plugin dependencies: apps must u } ``` -2. Apply the plugin to the app-level build file, as well as any other sub-module to be instrumented: +2. Apply the plugin explicitly to the app-level build file (and any sub-modules intended for instrumentation) using the following syntax: ```groovy plugins { @@ -159,13 +161,12 @@ The preferred and current approach to declaring plugin dependencies: apps must u ``` -Gradle provides guidance on [Applying plugins using the plugins{} block](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). - +For detailed information on applying plugins within Gradle, refer to the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). -### Apply the plugin using the buildscript{} block [#buildscript] -The New Relic Android Agent plugin is co-hosted on MavenCentral, but uses the legacy plugin ID ('newrelic'). Customers who prefer to use the legacy plugin ID must provide the classpath to [MavenCentral](https://mvnrepository.com/artifact/com.newrelic.agent.android/agent-gradle-plugin) to resolve the location of the plugin during builds. +### Apply the plugin using the `buildscript{}` block [#buildscript] +The New Relic Android agent plugin is co-hosted on MavenCentral, but uses the legacy plugin ID (`newrelic`). Customers who prefer to use the legacy plugin ID must provide the classpath to [MavenCentral](https://mvnrepository.com/artifact/com.newrelic.agent.android/agent-gradle-plugin) to resolve the location of the plugin during builds. To prefer MavenCentral over the Gradle Plugin Portal, you need to make the following changes to Gradle files: @@ -183,7 +184,7 @@ To prefer MavenCentral over the Gradle Plugin Portal, you need to make the follo } ``` -2. Add this snippet to your `settings.gradle(.kts)` file through `pluginManagement {}` block: +2. Add this snippet to your `settings.gradle(.kts)` file through the `pluginManagement {}` block: ```groovy pluginManagement { repositories { @@ -203,7 +204,7 @@ To prefer MavenCentral over the Gradle Plugin Portal, you need to make the follo } ``` -3. Apply the plugin to the app-level build file, as well as any other submodule to be instrumented: +3. Apply the plugin to the app-level build file, as well as any other sub-module to be instrumented: ```groovy plugins { From c63d197500407834961042c93c8baf5ca311a9ad Mon Sep 17 00:00:00 2001 From: a-sassman Date: Wed, 21 Aug 2024 09:09:38 -0700 Subject: [PATCH 3/7] fix(mobile): remove code block, add missing link --- .../install-configure/install-android-agent-gradle.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx index 064d64ac051..16b3b3aa2c5 100644 --- a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx +++ b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx @@ -53,11 +53,11 @@ These procedures appear in our guided install. Keep in mind that even if you're ## Resolve and apply the New Relic Android agent Gradle plugin -In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version.``` +In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. -Starting with version 7.6.0, the New relic Android Gradle plugin is available on the [Gradle Plugin Portal](). This greatly simplifies the resolution and loading of community plugins. +Starting with version 7.6.0, the New relic Android Gradle plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/). This greatly simplifies the resolution and loading of community plugins. -Newer apps should follow the instructions to [Apply the plugin using the plugins DSL block](#plugin-dsl) to use agent plugin hosted on [Gradle Plugin Portal](https://plugins.gradle.org/). +Newer apps should follow the instructions to [Apply the plugin using the plugins DSL block](#plugin-dsl) to use agent plugin hosted on the Gradle Plugin Portal. If adding the New Relic Android agent to an older app, follow the instructions to [apply the plugin using the buildscript](#buildscript). For guidance on different approaches to resolving plugins, see [Resolving plugins](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations). From 9bf01e9bf4fa236ad447378cdc5fb3992fc7105d Mon Sep 17 00:00:00 2001 From: a-sassman Date: Wed, 21 Aug 2024 09:13:07 -0700 Subject: [PATCH 4/7] fix(mobile): add anchor links --- .../install-configure/install-android-agent-gradle.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx index 16b3b3aa2c5..52d42f4d682 100644 --- a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx +++ b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx @@ -51,7 +51,7 @@ To install the Android agent, you need to use our [guided install](https://onenr These procedures appear in our guided install. Keep in mind that even if you're updating your build files through the docs, you still need to add your app to New Relic and grab your generated app token from the guided install. You cannot capture data about your Android apps otherwise. -## Resolve and apply the New Relic Android agent Gradle plugin +## Resolve and apply the New Relic Android agent Gradle plugin [#resolve-apply-plugin] In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. @@ -99,7 +99,7 @@ If adding the New Relic Android agent to an older app, follow the instructions t 6. View your app's data on New Relic by going to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**. -## Configure the Android agent for Gradle Plugin Portal [#plugin-portal] +## Configure the Android agent for Gradle Plugin Portal [#configure-plugin-portal] Starting with agent version 7.6.0, the Android agent plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/) as a community plugin. The Gradle plugin DSL simpifies adding plugin dependencies to apps. @@ -138,7 +138,7 @@ Starting with agent version 7.6.0, the Android agent plugin is available on the -### Apply the plugin using the `plugins` DSL block [#plugin-dsl] +### Apply the plugin using the `plugins` DSL block [#apply-plugin-dsl] The recommended approach for managing plugin dependencies in Gradle utilizes the `plugins` DSL block. This section details applying the fully qualified form of the plugin id (`com.newrelic.agent.android`) within this structure. From 3c37d4fdae646f481f57a9a6e4fce27e798f5ef7 Mon Sep 17 00:00:00 2001 From: a-sassman Date: Fri, 23 Aug 2024 13:14:25 -0700 Subject: [PATCH 5/7] chore(mobile): clean up the manual install page --- .../install-android-agent-gradle.mdx | 269 +++++++++--------- 1 file changed, 128 insertions(+), 141 deletions(-) diff --git a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx index 52d42f4d682..3dc2758ee43 100644 --- a/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx +++ b/src/content/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-agent-gradle.mdx @@ -38,183 +38,178 @@ redirects: - /docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-apps-gradle-android-studio --- -To install the Android agent, you need to use our [guided install](https://onenr.io/0kjnEoryzRo). Setting up the Android agent requires an [application token](/docs/mobile-apps/viewing-your-application-token) that authenticates each mobile app you want to monitor. The app token is only available by going through the guided install. - -## Install the Android agent with guided install [#guided-install] +To install the Android agent, we recommend you follow our guided install: 1. Go to **[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents > Mobile > Android**. 2. Follow the guided install steps to set up your Android agent. 3. Wait a few minutes, then view your data by going to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select your app)**. -## Manually install the Android agent [#manual-install] - -These procedures appear in our guided install. Keep in mind that even if you're updating your build files through the docs, you still need to add your app to New Relic and grab your generated app token from the guided install. You cannot capture data about your Android apps otherwise. - -## Resolve and apply the New Relic Android agent Gradle plugin [#resolve-apply-plugin] - -In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. +## Manually install the Android agent [#manual-install] -Starting with version 7.6.0, the New relic Android Gradle plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/). This greatly simplifies the resolution and loading of community plugins. +The steps below are outlined in our guided install. Note that even if you manually install the agent, you'll still need to create a New Relic app and obtain the generated application token. This token is essential for the agent to send data to New Relic. -Newer apps should follow the instructions to [Apply the plugin using the plugins DSL block](#plugin-dsl) to use agent plugin hosted on the Gradle Plugin Portal. + + +Add the Android agent plugin to your project. -If adding the New Relic Android agent to an older app, follow the instructions to [apply the plugin using the buildscript](#buildscript). For guidance on different approaches to resolving plugins, see [Resolving plugins](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations). +Regarding the location of the plugin, you have two options: +* Recommended: Using the Gradle plugin DSL + * Starting with agent version 7.6.0, the Android agent plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/) as a community plugin. The Gradle plugin DSL simpifies adding plugin dependencies to apps. The Gradle plugin DSL simplifies adding plugin dependencies to apps. + * This method involves adding the agent plugin dependency to your project's plugins DSL block. +* Legacy Plugin ID (`newrelic`) + * For older projects or specific use cases, you can use the legacy plugin ID. + * This method involves adding the agent as a dependency to your project's build script, specifying the MavenCentral repository. -1. Set app permissions. Update your `AndroidManifest.xml` file to allow your app to access the internet and check network state: +Follow the detailed steps below for your chosen installation method. - ```xml - - - ``` + + +The recommended approach for managing plugin dependencies in Gradle utilizes the plugins DSL block. This section details applying the fully qualified form of the plugin ID (`com.newrelic.agent.android`) within this structure. -2. Start the Android agent. In your main Activity class (`onCreate` method), import the `NewRelic` class: +1. Declare the New Relic plugin to the top-level `build.gradle(.kts)` file using the Gradle Plugin Portal plugin ID: - ```java - import com.newrelic.agent.android.NewRelic; - ``` +```groovy +plugins { + // for binary Gradle plugins that need to be resolved + id("com.newrelic.agent.android") version "AGENT_VERSION" apply false +} +``` - - Starting the agent in other classes is not supported. - +Make sure to replace `AGENT_VERSION` with your agent version number. We strongly recommend you use the [latest version](/docs/release-notes/mobile-release-notes/android-release-notes/). -3. Replace `GENERATED_TOKEN` with your actual app token (obtained during guided install) and add this code: +2. Apply the plugin explicitly to the app-level build file (and any sub-modules intended for instrumentation) using the following syntax: - ```java - NewRelic.withApplicationToken("GENERATED_TOKEN").start(this.getApplicationContext()); - ``` +```groovy +plugins { + id("com.newrelic.agent.android") +} +``` -4. (Optional) Configure for minification: +For detailed information on applying plugins within Gradle, refer to the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). - 1. If you use ProGuard or Dexguard for code shrinking, create a `newrelic.properties` file in your app-level directory (`_projectname/app_`). - 2. Add this line to the file, replacing `GENERATED_TOKEN` with your actual token: - ```ini - com.newrelic.application_token=GENERATED_TOKEN - ``` - 3. To finish set up for minification, follow the steps in [configure ProGuard or DexGuard for Android apps](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-proguard-or-dexguard-android-apps). + -5. Clean your project, then run your app in an emulator or device to generate traffic. Wait a few minutes as your agent captures that data. + +The Android agent plugin is available on MavenCentral and uses the legacy plugin ID `newrelic` for compatibility with older projects. If you choose to leverage this legacy ID for an existing app, you'll need to explicitly configure the classpath to MavenCentral. This ensures Gradle can locate the plugin during your build process. For further details on various methods for resolving plugins, refer to the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:binary_plugin_locations). -6. View your app's data on New Relic by going to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**. +To prefer MavenCentral over the Gradle Plugin Portal, you need to make the following changes to Gradle files: +1. Add this snippet to your top-level build.gradle(.kts) file: -## Configure the Android agent for Gradle Plugin Portal [#configure-plugin-portal] +```groovy +buildscript { + repositories { + mavenCentral() + } -Starting with agent version 7.6.0, the Android agent plugin is available on the [Gradle Plugin Portal](https://plugins.gradle.org/) as a community plugin. The Gradle plugin DSL simpifies adding plugin dependencies to apps. + // not required if plugin classpath in resolutionStrategy{} below + dependencies { + classpath "com.newrelic.agent.android:agent-gradle-plugin:AGENT_VERSION" + } +} +``` - +2. Add this snippet to your `settings.gradle(.kts)` file through the `pluginManagement {}` block: - - In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. +```groovy +pluginManagement { + repositories { + mavenCentral() // adds repo for NewRelic artifacts + } + resolutionStrategy { + eachPlugin { + // not required if using `classpath dependency` above + if (requested.id.id.startsWith("newrelic") || requested.id.id.startsWith("com.newrelic.agent.android"))) { + useModule("com.newrelic.agent.android:agent-gradle-plugin:${AGENT_VERSION}") + } + } + } + plugins { + id("newrelic") apply false + } +} +``` + +Make sure to replace `AGENT_VERSION` with your agent version number. We strongly recommend you use the [latest version](/docs/release-notes/mobile-release-notes/android-release-notes/). - ```groovy - plugins { - // for binary Gradle plugins that need to be resolved - id("com.newrelic.agent.android") version "AGENT_VERSION" apply false - } - ``` - - - - In this example, `AGENT_VERSION` represents your agent version number. See the [agent release notes](/docs/release-notes/mobile-release-notes/android-release-notes), and use the latest version. - - ```groovy - plugins { - id 'com.newrelic.agent.android' - } +3. Apply the plugin to the app-level build file, as well as any other sub-module to be instrumented: - dependencies { - implementation 'com.newrelic.agent.android:android-agent:AGENT_VERSION' - } - ``` - - +```groovy +plugins { + id("newrelic") +} +``` + + + -### Apply the plugin using the `plugins` DSL block [#apply-plugin-dsl] + +In your `AndroidManifest.xml` file, add the following permissions: -The recommended approach for managing plugin dependencies in Gradle utilizes the `plugins` DSL block. This section details applying the fully qualified form of the plugin id (`com.newrelic.agent.android`) within this structure. +```xml + + +``` + + +In your main `Activity` class within the `onCreate` method, add this import statement: -1. Declare the New Relic plugin to the top-level `build.gradle(.kts)` file using the Gradle Plugin Portal plugin ID: +```java +import com.newrelic.agent.android.NewRelic; +``` - ```groovy - plugins { - // for binary Gradle plugins that need to be resolved - id("com.newrelic.agent.android") version "AGENT_VERSION" apply false - } - ``` +Note: You must add this import statement to the `Activity` class. We don’t support starting the agent in other classes. + -2. Apply the plugin explicitly to the app-level build file (and any sub-modules intended for instrumentation) using the following syntax: + +In the `onCreate` method, add the following line, making sure to replace `GENERATED_TOKEN` with your actual app token (created during the guided install): - ```groovy - plugins { - id("com.newrelic.agent.android") - } - ``` +```java +NewRelic.withApplicationToken("GENERATED_TOKEN").start(this.getApplicationContext()); +``` + -For detailed information on applying plugins within Gradle, refer to the [Gradle documentation](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). + +(Optional) Additional configurations for Proguard/Dexguard +If you use ProGuard or Dexguard for code shrinking, follow these steps: -### Apply the plugin using the `buildscript{}` block [#buildscript] +1. Create a `newrelic.properties` file in your app-level directory (ex: `/projectname/app/newrelic.properties`). +2. In this new file, add the following line, replacing `GENERATED_TOKEN ` with your actual token: -The New Relic Android agent plugin is co-hosted on MavenCentral, but uses the legacy plugin ID (`newrelic`). Customers who prefer to use the legacy plugin ID must provide the classpath to [MavenCentral](https://mvnrepository.com/artifact/com.newrelic.agent.android/agent-gradle-plugin) to resolve the location of the plugin during builds. + ```java + com.newrelic.application_token=GENERATED_TOKEN + ``` +3. Follow the steps decribed on [Configure ProGuard or DexGuard for Android apps](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-proguard-or-dexguard-android-apps/). + -To prefer MavenCentral over the Gradle Plugin Portal, you need to make the following changes to Gradle files: + +Clean your project, then run your app in an emulator or device to generate traffic. Wait a few minutes as your agent captures that data. + -1. Add this snippet to your top-level `build.gradle(.kts)` file: - ```groovy - buildscript { - repositories { - mavenCentral() - } - - // not required if plugin classpath in resolutionStrategy{} below - dependencies { - classpath "com.newrelic.agent.android:agent-gradle-plugin:AGENT_VERSION" - } - } - ``` - -2. Add this snippet to your `settings.gradle(.kts)` file through the `pluginManagement {}` block: - ```groovy - pluginManagement { - repositories { - mavenCentral() // adds repo for NewRelic artifacts - } - resolutionStrategy { - eachPlugin { - // not required if using `classpath dependency` above - if (requested.id.id.startsWith("newrelic") || requested.id.id.startsWith("com.newrelic.agent.android"))) { - useModule("com.newrelic.agent.android:agent-gradle-plugin:${AGENT_VERSION}") - } - } - } - plugins { - id("newrelic") apply false - } - } - ``` - -3. Apply the plugin to the app-level build file, as well as any other sub-module to be instrumented: - - ```groovy - plugins { - id("newrelic") - } - ``` + +View your app's data on New Relic by going to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app)**. + + +## What's next? -In the above snippets, `AGENT_VERSION` represents your agent version number. We strongly recommend you use the latest agent for set up. +Congratulations! You've successfully installed the Android agent. You have a few options for next steps: +* Configure agent behavior during Gradle builds with the [New Relic Gradle plugin](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-new-relic-gradle-plugin). +* [Upgrade the Android agent SDK](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/upgrading-new-relic-mobiles-android-sdk) to keep your Android agent up to date. +* Having problems with your Android installation? Follow the [troubleshooting procedures](/docs/mobile-monitoring/new-relic-mobile-android/troubleshoot/no-data-appears-android). ## Android 4.x: Multidex support [#4x-multidex] @@ -222,7 +217,7 @@ Mobile monitoring for Android versions older than Android 5.0 (API level 21) use When building each DEX file for a multidex app, the build tools perform complex decision making to determine which classes are needed in the primary DEX file so that your app can start successfully. If, during start up, the required classes aren't available in the primary DEX file, your app will crash with the error `java.lang.NoClassDefFoundError`. @@ -252,12 +247,4 @@ Mobile monitoring for Android versions older than Android 5.0 (API level 21) use ``` For more information, see the [Android Developers documentation](https://developer.android.com/studio/build/multidex.html#keep) on declaring classes required in the primary DEX file. - - -## What's next? - -Congratulations! You've successfully installed the Android agent. You have a few options for next steps: - -* Configure agent behavior during Gradle builds with the [New Relic Gradle plugin](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/configure-new-relic-gradle-plugin). -* [Upgrade the Android agent SDK](/docs/mobile-monitoring/new-relic-mobile-android/install-configure/upgrading-new-relic-mobiles-android-sdk) to keep your Android agent up to date. -* Having problems with your Android installation? Follow the [troubleshooting procedures](/docs/mobile-monitoring/new-relic-mobile-android/troubleshoot/no-data-appears-android). + \ No newline at end of file From e2262274be8b315d0d18694675d416687260f37e Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Mon, 26 Aug 2024 13:54:36 -0500 Subject: [PATCH 6/7] Fix OTLP endpoint in micrometer-metrics-registry.mdx --- .../micrometer/micrometer-metrics-registry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/apm/agents/java-agent/related-integrations/micrometer/micrometer-metrics-registry.mdx b/src/content/docs/apm/agents/java-agent/related-integrations/micrometer/micrometer-metrics-registry.mdx index fe7edbea9ad..ede6888b8b1 100644 --- a/src/content/docs/apm/agents/java-agent/related-integrations/micrometer/micrometer-metrics-registry.mdx +++ b/src/content/docs/apm/agents/java-agent/related-integrations/micrometer/micrometer-metrics-registry.mdx @@ -104,7 +104,7 @@ These are generalized steps to set up Micrometer metrics forwarding. You may wan .registerMetricReader( PeriodicMetricReader.builder( OtlpHttpMetricExporter.builder() - .setEndpoint("https://otlp.nr-data.net") + .setEndpoint("https://otlp.nr-data.net/v1/metrics") .addHeader("api-key", Optional .ofNullable(System.getenv("NEW_RELIC_LICENSE_KEY")) From 1dac4cd5fe31a94ef368a5f356869c258a06ce0e Mon Sep 17 00:00:00 2001 From: Tabatha Zeitke Date: Mon, 26 Aug 2024 16:18:46 -0500 Subject: [PATCH 7/7] fix: add handler for `span` --- scripts/actions/utils/handlers.mjs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/actions/utils/handlers.mjs b/scripts/actions/utils/handlers.mjs index 27349c9167d..e5624a45350 100644 --- a/scripts/actions/utils/handlers.mjs +++ b/scripts/actions/utils/handlers.mjs @@ -479,6 +479,10 @@ export default { deserialize: deserializeComponent, serialize: serializeComponent, }, + span: { + deserialize: deserializeComponent, + serialize: serializeComponent, + }, sup: { deserialize: deserializeComponent, serialize: serializeComponent,