On this page:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
16 rates

Build the Android Application showed you how to use the bare minimum configuration to build your application. This page shows you how to add additional configuration to customize your build.

Automatically Upload Mapping Files

You can configure the build to add your EUM account information so that you can automatically upload your ProGuard or DexGuard mapping files for crash reports with each build. This is the recommended way of managing these types of mapping files, although manual modes are available for uploading mapping files. If you do not use ProGuard or DexGuard to obfuscate your files you can ignore this section.

DexGuard Limitation

DexGuard mapping files must be in the default location. This means that their dexguard configurations should not specify --printMapping, which changes where to print the mapping file.

Uploading to the SaaS EUM Server

If you are using the SaaS EUM Server, you just need to provide your account name and license key to automate uploading as shown below.

adeum {  
        
    // Add this information to allow the upload of ProGuard or DexGuard mapping files. 
    // If you are using the EUM Cloud (SaaS), this automatically uploads your files with each build 
    account {
      name "The EUM Account Name from the License screen"
      licenseKey "The EUM License Key from the License screen"
    }
}

Uploading to the On-Prem EUM Server

If you are using an on-prem deployment, in addition to supplying your account name and license, you must also assign the URL to your on-prem EUM Server to the url property as shown below.

adeum{  
    // The account information is also needed for on-prem deployments.
    account {
      name "The EUM Account Name from the License screen"
      licenseKey "The EUM License Key from the License screen"
    }
    ...
    // Add this information to point to the on-prem EUM Server.
    url "https://<your-on-prem-eum-server>:7001"
}

Modifying the Default Upload Behavior

You can also modify the default upload behavior for both on-prem and SaaS deployments. For on-prem deployments, you will need to provide the URL to your on-prem EUM Server with the url property.

The configuration example below sets failBuildOnUploadFailure to true, so that the build will fail if the upload to the URL specified by url is unreachable. The object proguardMappingFileUpload is used for both Proguard and DexGuard mapping files. If you don't want your build to fail because the ProGuard or DexGuard mapping file couldn't be uploaded, do not modify the default setting.

adeum{  
    ...
    // Add this information to point to the on-prem EUM Server.
    url "https://<your-on-prem-eum-server>:7001"
 
   // Add this information if you want to modify upload behavior.
    proguardMappingFileUpload {
      failBuildOnUploadFailure true // If true, will fail build. Defaults to false.
      enabled true //enables automatic uploads.  Defaults to true
    }
}

 

Exclude Classes from Being Instrumented

You can exclude one or more class names from being instrumented, using the "adeum" excludeClasses snippet.

Class names can contain wildcards:

  • '?' for a single character
  • '*' for any number of characters, but not the package separator
  • '**' for any number of (any) characters
  • '$' prefix for an inner class name 

To exclude named classes from instrumentation, add the class names to the excludeClasses array, using matching patterns where needed:

...
adeum {
    // Excludes all the classes in the android.support.multidex and okio packages.
    excludeClasses = ['android.support.multidex.*', 'okio.**']
}
...

Enable/Disable Instrumentation for Build Types

By default, instrumentation is enabled for both release and debug builds. In certain cases, however, you might want to disable instrumentation for a certain build. 

For example, if you are tracking down an issue in your code, you might want to disable instrumentation in the debug build and enable instrumentation in the release build. To do this, in the adeum object, set enabledForDebugBuilds to false and set enabledForReleaseBuilds to true as shown below.

...
adeum {
    //other stuff, if it exists
    // Optional. 
    // By default, instrumentation is enabled for both debug and release builds.
    // This controls instrumentation for "debuggable" build types.
      enabledForDebugBuilds   = false
    // This controls for non-debuggable build types. 
      enabledForReleaseBuilds = true
}
...

Verify the Instrumentation State at Runtime

If one or more of your builds has disabled instrumentation, you need to disable the instrumentation check at runtime. You can set boolean fields in the build configuration to disable the runtime verification of instrumentation. The runtime verification of instrumentation is on by default. You can turn it off using the method withAutoInstrument.

In the build configuration, you can set a boolean value for the CHECK_ENABLED field for build types. The table below shows the config value, the instrumentation state, and then describes the runtime behavior of your applications.

Config ValueInstrumentation StateRuntime Behavior
trueEnabledThe agent will verify that instrumentation has been enabled before initializing.
DisabledThe agent will verify that the instrumentation has not been enabled and then thown IllegalState exception.
falseEnabledThe agent will initialize without checking whether instrumentation has been enabled.
Disabled

For example, in the build configuration below, the field CHECK_ENABLED is set to true for the release build and false for the debug build. The agent for the debug build will not verify if instrumentation has been enabled before executing instrumentation code, whereas, the application code for the release build will check before executing the instrumentation code.

...
android {
    // usual stuff
    buildTypes {
    // usual stuff
        release {//these lines added for AppDynamics
            //release based configuration
            // The release build by default is not "debuggable". 
            // The build config "CHECK_ENABLED" will be accessible in the runtime environment.
            // This enables the Android Agent to verify that the instrumentation has been enabled before running the initialization code.
            // If instrumentation has not been enabled, an "IllegalState" exception is thrown.  
            buildConfigField "boolean", "CHECK_ENABLED", "true"
        }
        debug {
            // Setting 'CHECKED_ENABLED' to "false" means the Android Agent will run the initaliazation code without confirming that
            // instrumentation has been enabled. No exception will be thrown.
            buildConfigField "boolean", "CHECK_ENABLED", "false"
        }
    }
}
...

If the value of CHECK_ENABLED is true, the Android Agent will confirm that instrumentation has been enabled before executing the initialization code. If the value is false, the Android Agent executes the initialization code regardless of whether instrumentation has been enabled.

The following instrumentation initialization code shows you how to check the value of the build config CHECK_ENABLED with the method withCompileTimeInstrumentationCheck.

import com.appdynamics.eumagent.runtime.Instrumentation;
...
Instrumentation.start(
        AgentConfiguration config = AgentConfiguration.builder()
            .withAppKey(<EUM_APP_KEY>)
            .withContext(this)
            .withCompileTimeInstrumentationCheck(BuildConfig.CHECK_ENABLED)
            .build();
);
...

Enable/Disable Native Crash Reporting

You can report native crashes caused by native libraries. This feature is available for all architectures supporting the Android Native Development Kit (NDK)

How It Works

When instrumentation is initialized, the native crash handler loads the AppDynamics library libadeum. At entry points of your code, a signal handler is injected into the running process. After a signal is handled, libadeum restores the previous signal handler. (This enables you to use different methods to handle signals.)

The handler collects and writes the information about the native crash into a temporary file. When the application is restarted, the temporary file is read, processed, and the crash information is displayed in the Controller UI. 

Configuration for Native Crash Reporting

By default, however, this feature is turned off, so you need to add the section nativeCrashHandling and set enabled to true. In addition, you point the library paths in the variantLibraryPaths array for each build variant to write the symbol files locally and transmit the symbol files to the EUM Server. You can also specify a build ID for a project build. After you build the project, the build ID can be found in build/appDynamics/ndkSym<VariantName>/<AppBuildID>. If not specified, the build ID of the most recently built project will be used.

adeum {  
    // Other configuration if needed.

    // Enable native crash handling; the default is false.
    nativeCrashHandling {
        enabled = true
        symbolUpload {
            buildId = "<your_custom_build_id>"
            variantLibraryPaths = ["release": "ndkLib/obj/local", "debug": "ndkLib/obj/debug", ...]
        }
    } 
}

View Source Code Information in the Stack Trace

You have two different ways to view symbol information in the stack trace:

  1. From the Crash Details dialog, download the crash report and use a utility like ndk-stack to view the crash report with source code level symbolications.
  2. Upload the symbol files and then view the stack trace in the Crash Details dialog. 

Download the Crash Report and Use ndk-stack 

  1. From the Crash Dashboard, double-click one of the crashes listed in the Unique Crashes widget.
  2. From the Crash Details dialog, click Download to download the crash report.
  3. Run ndk-stack (or a similar utility) on the downloaded crash report as the input file to generate a crash report with source code level symbolications.

Upload the Symbol File and View the Stack Trace

You are recommended to automatically generate and upload symbol files, but you can also manually generate and upload the symbol files, too. After you upload the symbol files, when the app with the same build ID as the UUID of the uploaded ndkSYM file crashes, you will see the file name and the line number next to the C/C++ function name for each frame of the stack trace shown in the Crash Details dialog.

Automatically Generate and Upload Symbol Files

You can run the following gradle command to generate and upload the symbol files to the EUM Server. Replace <VariantName> with the build variant names you defined in the configuration. For example, in the configuration above, the <VariantName> could be release or debug.

$ gradle appDynamicsUploadNDKSymbolFile<VariantName>
Manually Generate and Upload Symbol Files

To generate symbol files, run the following gradle command, where <VariantName> is the build variant names. The generated symbol file will be written to build/appDynamics/ndkSym<VariantName>/<AppBuildID>/<AppBuildID>.ndkSYM.zip.

$ gradle appDynamicsGenerateNDKSymbolFile<VariantName>

To manually upload the generated symbol file, use the following cURL command, replacing the <ndkSymZipFile> with your generated symbol file, <Account Name> with your EUM Account name, and <License Key> with your EUM License Key. 

$ curl -v -H Content-Type:application/octet-stream --upload-file <ndkSymZipFile> --user <Account Name>:<License Key> https://api.eum-appdynamics.com/v2/account/<Account Name>/android-ndksym
  • No labels