On this page:
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 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.
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.
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
The configuration example below sets
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.
Exclude Classes from Being Instrumented
You can exclude one or more class names from being instrumented, using the "adeum"
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:
Enable/Disable Instrumentation for Build Types
By default, instrumentation is enabled for both
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
false and set
true as shown below.
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 Value||Instrumentation State||Runtime Behavior|
|Enabled||The agent will verify that instrumentation has been enabled before initializing.|
|Disabled||The agent will verify that the instrumentation has not been enabled and then thown |
|Enabled||The agent will initialize without checking whether instrumentation has been enabled.|
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.
If the value of
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
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.
View Source Code Information in the Stack Trace
You have two different ways to view symbol information in the stack trace:
- From the Crash Details dialog, download the crash report and use a utility like
ndk-stackto view the crash report with source code level symbolications.
Upload the symbol files and then view the stack trace in the Crash Details dialog.
Download the Crash Report and Use ndk-stack
- From the Crash Dashboard, double-click one of the crashes listed in the Unique Crashes widget.
- From the Crash Details dialog, click Download to download the crash report.
- 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.
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
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.