This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


On this page:

Watch the video:

Start Monitoring with the Android Agent

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
54 rates

The Maven Central build is currently supported only for Gradle and Maven-based builds. For builds using Ant, please see Instrument an Android Application - Manual

1. Access the instrumentation window

  1. Open the application in which you are interested. This can be an instrumented server-side application with which your mobile app interacts or a "container" application that holds your mobile application's information in the Controller UI.
  2. On the left navigation bar,  click Configuration > Instrumentation > End User Monitoring.
  3. Click the Mobile Apps tab.

2. Record the Application Key

Record the application key generated for this application, displayed in step .

You will need this key when you modify the source code.

3. Set Up Your Environment

Follow the instructions based on your build environment.

Setup for Gradle

 Click here to expand...

If you are using Gradle, you need to modify both your build.gradle files.

Modify your top-level build.gradle

Make the following changes to your top-level build.gradle file:

  1. Edit or create the "buildscript" section and add the AppDynamics plugin as a dependency as follows:

    buildscript {
        repositories {
            jcenter()
        }
        dependencies {
            classpath 'com.android.tools.build:gradle:1.1.0'
            classpath 'com.appdynamics:appdynamics-gradle-plugin:4.+' // this line added for AppDynamics
    
            // NOTE: Do not place your application dependencies here; they belong
            // in the individual module build.gradle files
        }
    }
    
    allprojects {
        repositories {
            jcenter()
        }
    }

    (info)To stay on a particular version of the agent, replace "4.+" with the desired version number.

Modify your module-level build.gradle

  1. Apply the "adeum" plugin immediately after the "com.android.application" plugin.

  2. Add "com.appdynamics:appdynamics-runtime:4.+" as a compile-time dependency. 
  3. Optional: to automate uploading Proguard mapping files so that they are updated every time you build,  add the Proguard snippet. You can use this instead of the manual options discussed in Step 8 below.

After you have added all the AppDynamics Android Agent requirements, your module-level build.gradle resembles this: 

apply plugin: 'com.android.application'
apply plugin: 'adeum' // this line added for AppDynamics

android {
    compileSdkVersion 21
    buildToolsVersion "21.1.2"

    defaultConfig {
        applicationId "com.appdynamics.example"
        minSdkVersion 15
        targetSdkVersion 21
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    compile 'com.appdynamics:appdynamics-runtime:4.+' // this line added for AppDynamics
}

adeum { // this section added for AppDynamics
    //Optional. Uploads Proguard mapping files with each build
      url "https://example.com:7001" //Use this to point to the Collector of an on-prem instance of the EUM Server
  
      account {
         name "The EUM Account Name from the License screen"
         licenseKey "The EUM License Key from the License screen"
       }
  
      proguardMappingFileUpload {
          failBuildOnUploadFailure true //should build fail if upload fails? Defaults to false.
          enabled true //enables automatic uploads.  Defauts to true.
       }
}

Optional: Enable/Disable Instrumentation with Build Types

In certain cases you might want to be able to select whether or not a particular build is instrumented, for example, if you are tracking down an issue in your code.  You can modify your module-level "build types" section to support two options, one of which is instrumented and the other not.  You need to add information to two sections of the module-level build.gradle: the android "build-types" section and the adeum section, if you already have one.

 Click here to expand...
android {
    // usual stuff
    buildTypes {
    // usual stuff
        release {//these lines added for AppDynamics
            //release based configuration
            buildConfigField "boolean", "CHECK_ENABLED", "true"
        }
        debug {
            buildConfigField "boolean", "CHECK_ENABLED", "false"
        }
    }
}

adeum {
    //other stuff, if it exists
    //Optional. By default, instrumentation is enabled for both debug & release builds
      enabledForDebugBuilds   = false
      enabledForReleaseBuilds = true
}

If you use this option, you need to do a bit more work when you set up instrumentation in your code.  See Optional: Modify the source if you are using Build Types

Setup for Maven

 Click here to expand...

If you are using Maven you must:

  1. Add the Maven runtime dependency
  2. Add the Maven plugin

These instructions assume you are building your application using the android-maven-plugin with Maven 3.1.1+.

Add the Maven runtime dependency

Add the following code to the <dependencies> section:

<dependency>
     <groupId>com.appdynamics</groupId>
     <artifactId>appdynamics-runtime</artifactId>
     <version>4.1.2.0</version>//this version changes with each new releases
</dependency>

Add the Maven plugin

Add the following code to the <plugins> section:

<plugin>
    <groupId>com.appdynamics</groupId>
    <artifactId>appdynamics-maven-plugin</artifactId>
    <version>4.1.2.0</version>//this version changes with each new releases
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>adinject</goal>
            </goals>
        </execution>
    </executions>
</plugin>

4. Integrate ProGuard, if Necessary

If you use ProGuard to verify or optimize your code, add the following lines to your ProGuard configuration file, by default proguard.cfg.

(info) Depending on your environment, this file may renamed by your build.

-keep class com.appdynamics.eumagent.runtime.DontObfuscate
-keep @com.appdynamics.eumagent.runtime.DontObfuscate class * { *; }

If you use Proguard to obfuscate your code, note the name and location of the mapping file that ProGuard produces, because AppDynamics needs this file to create human-readable stack traces for crash snapshots. For details about why you should do this, see Get Human-Readable Crash SnapshotsFor more information on the process, see Upload the ProGuard Mapping File.

Every time the application is changed and recompiled the ProGuard mapping file changes, so you need to upload the new mapping file to AppDynamics every time you modify your app, either manually or as a part of your build process.

5. Modify the Source

In the source file that defines your application's primary Activity, add the following import:

import com.appdynamics.eumagent.runtime.Instrumentation;

 In your primary Activity's onCreate() method, add the following lines, passing in the App Key from step 2 above: 

Instrumentation.start("$CURRENT_APP_KEY", getApplicationContext());

Save the file.

Your code should look something like this.

import com.appdynamics.eumagent.runtime.Instrumentation;
...

@Override
public void onCreate(Bundle savedInstanceState)
{
    ...
    Instrumentation.start("$CURRENT_APP_KEY", getApplicationContext());
}

Optional: Point to an on-prem EUM Server

 Click here to expand...

If you are using an on-prem EUM Server instead of the EUM Cloud, you need to tell the Agent where to send its beacons. To do that, you need to create an Agent Configuration object and pass it into the Instrumentation.start call. The AgentConfiguration object allows you to customize the configuration of the Agent in various ways. To set a URL for an on-prem Server, use the withCollectorUrl method. You also need to pass in the App Key, as in the simpler process above.

In your primary Activity's onCreate() method, use this form of the Instrumentation.start call:

Instrumentation.start(AgentConfiguration.builder()
	.withContext(this)
 	.withAppKey("$CURRENT_APP_KEY")
	.withCollectorURL("$URL_OF_YOUR_EUM_SERVER")
	.build());

The full JavaDocs that describe the available options using this method are available here.

Optional: Modify the source if you are using Build Types (Gradle only)

 Click here to expand...

(info)  If you are using Gradle and have used the "build types" option in your build.gradle file to enable/disable instrumentation, you will need to do a little additional work.  Instead of the above, in your primary Activity's onCreate() method, add the following lines:

Instrumentation.start(
        AgentConfiguration config = AgentConfiguration.builder()
            .withAppKey($CURRENT_APP_KEY")
            .withContext(this)
            .withCompileTimeInstrumentationCheck(BuildConfig.CHECK_ENABLED)
            .build();
);

Save the file.

Your code should then look something like this.

import com.appdynamics.eumagent.runtime.Instrumentation;
...

@Override
public void onCreate(Bundle savedInstanceState)
{
    ...
    Instrumentation.start(
        AgentConfiguration config = AgentConfiguration.builder()
            .withAppKey($CURRENT_APP_KEY")
            .withContext(this)
            .withCompileTimeInstrumentationCheck(BuildConfig.CHECK_ENABLED)
            .build();
);
}

6. Add the Required Permissions

Open your application's AndroidManifest.xml file and verify that it has these permissions:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>

If both of these permissions are not present, add them.

7. Rebuild the Application

Rebuild your application.  If you are using Gradle, add the -i flag (gradle -i).

In the console, you should see something like this:

 [injector] 				/=========================================\
 [injector] 				| AppDynamics BCI Instrumentation summary  |
 [injector] 				\=========================================/
 [injector]
 [injector]
 [injector] 		 - Total number of classes visited (#720 classes)
 [injector] 		 - Total number of classes instrumented (#1 classes)
 [injector] 		 - Total number of classes failed to instrument (#2 classes)
 [injector] 		 - Total number of features discovered (#3)
 [injector]

Verify your instrumentation - Gradle

If you didn't use the -i flag, check to make sure there is a line in your console output that contains "inject". If you don't see this information printed in your console, either your project is incorrectly configured or the injector failed to run completely.  There is a very detailed log of this process at <project>/build/appdynamics_eum_android_bci.log

Verify your instrumentation - Maven

If you don't see this information printed in your console, either your project is incorrectly configured or the injector failed to run completely.  There is a very detailed log of this process at <project>/target/appdynamics_eum_android_bci.log

8. Upload the ProGuard Mapping File

(info) If you did not obfuscate your application source code, you can skip this step.  If you have set up automatic uploading of this file using your build.gradle file, you can skip this step.

This step is optional but highly recommended if you obfuscated your code and plan to monitor crashes. AppDynamics needs the mapping file for the application to produce human-readable stack traces for crash snapshots. By default, the mapping file is named mapping.txt, unless you have renamed it in your build.

(warning) If you update your application, you need to upload the new version of the mapping file.

To associate the mapping file with the correct version of the application, you need to provide:

  • the package name of the Android package for the application
  • the version code for that application from the AndroidManifest.xml file

You can either upload the mapping file using the instrumentation screen in the Controller UI or use a special REST API. Perform the upload separately for each ProGuard mapping file that you are providing.

Upload the ProGuard Mapping File using the UI

 Click here to expand...
  1.  In the instrumentation window in the controller UI, click the Upload ProGuard mapping file for Android crashes button.
  2. In the ProGuard mapping file upload window, either 
    • select an existing package from the dropdown list
      or 
    • enter a new package name for the mobile application.

(info) If the application is already registered with the controller, you can select its package which is listed in the dropdown list.
If the application is not yet registered, enter the package name in the New Package field.

  1. Enter the version code (a number) for the package. This is the versionCode  property in the AndroidManifest.xml of the application for which this mapping file was generated.
  2. Click Select ProGuard mapping file.
    The uploader expects a file with .txt extension. The file is named mapping.txt.
  3. In the file browser locate and select the mapping file and click Open.
  4. Click Upload.

Upload the ProGuard Mapping File using the API

 Click here to expand...

The API uses HTTP basic authentication to send a PUT request to AppDynamics. The username is your AppDynamics EUM account name and the password is your EUM license key.

Set up your HTTP basic authentication credentials
  1. In the upper right section of the Controller UI, click the gear icon > License.
  2. Scroll down to the End User Monitoring panel.
  3. Note the Account Name at the top of the panel. This is your username for authentication.
  4. Note the License Key just below the Account Name. This is your password for authentication.

  5. URL-encode the account name and the license key.
  6. Generate an authentication string of the form: "<URL-encoded EUM account name>:<URL-encoded EUM license key>" and base64 encode it. You will use this string the following step.
  7. Add an authentication header to each request, setting its value to "Basic <authentication string>"

Send the mapping file

Send the ProGuard mapping file as as a text file in the body of the PUT request to the following URI:

https://api.eum-appdynamics.com/eumaggregator/crash-reports/proguardMappingFile/<androidPackageName>/<versionString>

These parameters are required:

  • androidPackagename: the name of the Android package for which this mapping file was generated
  • versionString: the string representation of the "versionCod"e property in the AndroidManifest.xml of the application for which this mapping file was generated

The request body contains the mapping file. The content type of the body is either text/plan or gzip if the body was ended with gzip.

Sample Request and Response Using the REST API

This is a sample request and response using the REST API.

Upload Request

The following example uses curl to send a mapping file. The account name is "Example account" and the license key/password is "Example-License-Key-4e8ec2ae6cfe". The plus signs replace spaces in the account name when the account name is URL-encoded. The package name for the Android application is "com.example.networklogger". The mapping file corresponds to the version with versionCode 1.

curl -v --upload-file mapping.txt --user Example+account:Example-License-Key-4e8ec2ae6cfe https://api.eum-appdynamics.com/eumaggregator/crash-reports/proguardMappingFile/com.example.networklogger/1
Upload Response

The successful output of the example request looks like this:

* About to connect() to api.eum-appdynamics.com port 443 (#0)
*   Trying ::1...
* connected
* Connected to api.eum-appdynamics.com  (::1) port 443 (#0)
* Server auth using Basic with user 'Example+account'
> PUT /eumaggregator/crash-reports/proguardMappingFile/com.example.networklogger/1 HTTP/1.1
> Authorization: Basic SW50ZXJuYWwrdGVzdCthY2NvdW50OlRlc3RBY2N0LTFlMzktNDVkMy05MzAzLTRlOGVjMmFlNmNmZQ==
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8y zlib/1.2.5
> Host: app.eum-appdynamics.com
> Accept: */*
> Content-Length: 4
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Jetty(8.1.4.v20120524)
<
* Connection #0 to host app.eum-appdynamics.com left intact
* Closing connection #0

9. Customize Your Instrumentation (Optional)

The Instrumentation class has additional methods to allow you to extend the kinds of application data you can collect and aggregate using Mobile RUM.  There are five basic kinds of extensions that you can create:

  • custom timers
  • custom metrics
  • information points
  • breadcrumbs
  • user data

In addition, if you are using an environment with an on-premise EUM Server you need to update your code to indicate the URL to which your agent should send its beacons.

For more information, see Use the APIs of the Android SDK to Customize Your Instrumentation.

Upgrade the Android Mobile Agent

As new features are added to the agent, you will need to rebuild to upgrade the Android SDK.

  • No labels