Android Agent FAQ
This is documentation for the legacy version 7.x. For the most recent version see Android Agent v8.x.
Version 8.x is only supported with AppMon 2018 October!
Mobile Agent
You can send a GET request to the web server agent and check if the web server agent delivers the correct result. The url can be compound from the agent path and application id value:
<your_agent_path>/dynaTraceMonitor?type=m&app=<your_app_id>
Example:
http://myhost.mydomain.com/dynaTraceMonitor?type=m&app=myAndroidApp
The response must start with type=m
and should not contain the key-value pair cp=0
(UEM is disabled). A typical result should look like the following example:
type=m&cp=1&si=120&cl=1&cr=1&er=1&bn=dynaTraceMonitor&id=1&bl=30&st=600
First check if the web server agent is working properly. Then you should enable debug logging with the DTXLogLevel
property. Compare the following log snippets with the debug log from your application.
Check if the agent has been started. You can identify the startup sequence from the Mobile Agent with the following log snippet:
Dynatrace OneAgent (Android) startup parms: <startup_parameters>
Check if the agent has established a successful connection to the web server agent. The initial GET request can be found with the log snippet:
Send <number>bytes <your_agent_path>/dynaTraceMonitor?type=m&<other_parameters>
You can verify if the connection was successfully established, when the Mobile Agent logs the following two lines:
Response code: 200 msg: OK
Result: type=m&cp=1&<other_config_parameters> Success: true
Check if the agent has sent data to the web server agent. The POST request can be found with the log snippet:
aPOST url[<your_agent_path>/dynaTraceMonitor?type=m&<other_parameters>] data[<data>]
You can verify if the connection was successfully established, when the Mobile Agent logs the following two lines:
Response code: 200 msg: OK
Result: type=m&cp=1&<other_config_parameters> Success: true
No. For efficiency, the AppMon server does not accept monitoring data older than 10 minutes.
The Mobile Agent truncates most (user-related) values, if they exceed the border limit value of 250.
The Mobile Agent uses the default log framework from Android. You can use the logcat monitor from Android Studio or the command-line tool logcat to view these log lines.
Manual instrumentation
By default, the Mobile Agent assigns the WebRequestTiming
object to the last action. To use other action, tag the web request before you create the WebRequestTiming
object. The following example (see point 2a
and 2b
) shows how you can assign the WebRequestTiming
object to the webAction
variable instead of the otherAction
variable.
HttpURLConnection conn = null;
WebRequestTiming timing = null;
// [1] First, create an action
DTXAction webAction = Dynatrace.enterAction("time service");
DTXAction otherAction = Dynatrace.enterAction("dummy action");
try {
URL url = new URL("http://myhost.mydomain.com/TimeService?tz=CET");
conn = (HttpURLConnection) url.openConnection();
// [2a] Select your own action
webAction.tagRequest(connection);
// [2b] Use the existing tag and return the WebRequestTiming object
timing = Dynatrace.getWebRequestTiming(conn);
// [3] Call startWebRequestTiming() to begin the timing, and then handle the input
// stream from the connection
timing.startWebRequestTiming();
InputStream stream = new BufferedInputStream(conn.getInputStream());
readStream(stream);
// [4] Once done reading, timing can stop
timing.stopWebRequestTiming();
} catch (Exception e) {
// Attach the exception to the action
webAction.reportError("Exception", e);
// user-defined exception handling
} finally {
// [5] Lastly finalize the timing and the action in the finally block.
// This allow us to receive timings and close the action even if there is an
// exception thrown
if (timing != null) {
timing.stopWebRequestTiming();
}
webAction.leaveAction();
if (conn != null) {
conn.disconnect();
}
}
The Dynatrace.jar
library contains an dependency to the Apache HTTP client library. You must add the compile-time dependency for this library to your build.gradle
file.
android {
useLibrary 'org.apache.http.legacy'
}
Auto-Instrumentation
Yes, all frameworks based on OkHttp 3
, are supported.
No. Using DexGuard with the default configuration generates a protected APK file that the auto-instrumentor can't modify. The auto instrumentation process fails because the Unicode characters introduced by DexGuard are not supported. A possible workaround for this issue is to use -classobfuscationdictionary empty.txt
, where empty.txt
is an empty file. This option instructs DexGuard to assign obfuscated class names such as a
, b
, or c
, avoiding the Unicode class name issue.
You may have to deactivate additional protection and optimization features from DexGuard to generate an APK file that is compatible with the auto-instrumentor. If you do not want to modify you DexGuard configuration, then use manual instrumentation. Manual instrumentation is fully compatible with DexGuard or other protection tools.
No, the auto-instrumentor cancels the auto-instrumentation process, if the APK file is already auto-instrumented. You must use an uninstrumented APK file. You can run the auto-instrumentation process on a manually instrumented APK file.
No, this is not supported. Generally, manual and auto instrumentation must use the same Mobile Agent version.
Only activities defined and enabled in AndroidManifest.xml
are instrumented.
Only web requests from a supported HTTP framework are captured. Check if your HTTP framework is in this list. If not, you must instrument your web requests manually.
The Mobile Agent only attaches web requests to a user action triggered within a specific time frame. The time frame starts when the action opens, and ends 500 ms
after the action closes. You can change this value with the DTXAutoActionTimeoutMilliseconds
property.
MenuItems:
- getTitle()
Other views:
view.getContentDescription()
if not null.getText()
for a TextView (or subclass of).- For
LinearLayout
the name is determined by looking at the children. - The class name is used as backup.
There can be multiple reasons why the Mobile Agent can't create a user action:
- The UI component is defined in a WebView.
- The listener method is defined in a resource XML file.
- The UI component uses an unsupported listener. The User action monitoring section in Auto-instrumentation for Android lists all supported listeners.
Enable the DTXSendEmptyAutoAction
property if your user interaction does not trigger a web request or lifecycle change. The Mobile Agent discards empty user actions by default.
You may be running your application in development or testing mode (not signed and deployed to Google Play) with a Google Maps release API key.
Yes. The instrument.sh
and instrument.cmd
files have a default maximum heap (-Xmx
) setting. If you experience an out-of-memory exception, you can increase the memory by updating that setting.
When the crash (like java.lang.NoClassDefFoundError
or java.lang.ExceptionInInitializerError
) happens only on devices with Android 4.4 or lower, then you have to adjust the multidex preparation step of the auto-instrumentor. See the multi-dex applications section for more details.
When the crash happens at the app startup phase on devices with Android 4.4 or lower, the mentioned class is not part of the primary .dex
file. Update the DTXMultiDexKeep
and/or DTXMultiDexKeepFile
property to resolve the issue. See Using multiple .dex files for Android instrumentation for details.
These exceptions are trigger by the Apktool tool and aapt
and indicate that the auto-instrumentor wasn't able to read/modify the binary files of your APK file.
These tools are shipped within the Mobile Agent zip file and are regularly updated through public updates. Therefore, you should always use the latest Mobile Agent version.
If your app depends on a framework file from a manufacturer that is not part of the standard Android OS, then you manually have to install this framework file with the Apktool
. You can find the install command in the official Apktool documentation. In this case the auto-instrumentor is not able to successfully update the 1.apk
. Normally the auto-instrumentor takes care of renewing the framework APK by deleting the framework directory and recreating the 1.apk
file using the Apktool
tool. However the Apktool
will not clean its framework directory if more than just the 1.apk
are installed. In this case you must update the 1.apk
manually.
The provided APK file contains an old Mobile Agent. When you use a combination of manual and auto-instrumentation, you can't mix agent versions.
You are using a resource from Android that is not part of the public.xml
file. Instead of referring to a non-public resource, you should copy the resource into your application and refer it directly, as recommended here.
The auto-instrumentor uses the tool Apktool
and this tool blocks non-public resources for safety reasons.
The auto-instrumentor uses tools like aapt
and Apktool
to extract information from the AndroidManifest.xml
file and to modify it. In this case the tools are not able to generate a compiled version of the modified AndroidManifest.xml
file. The exact error message is only shown, when the property DTXLogLevel
is enabled.
These tools are shipped within the Mobile Agent zip file and are regularly updated through public updates. Therefore, you should always use the latest Mobile Agent version.
The provided APK file is already auto-instrumented and can't be auto-instrumented again. You must use an uninstrumented APK file.
The auto-instrumentor uses the tool Apktool (and aapt
) to unpack and decode the provided APK file. The exact error message is only shown, when the property DTXLogLevel
is enabled.
These tools are shipped within the Mobile Agent zip file and are regularly updated through public updates. Therefore, you should always use the latest Mobile Agent version.
If your app depends on a framework file from a manufacturer that is not part of the standard Android OS, then you manually have to install this framework file with the Apktool
. You can find the install command in the official Apktool documentation. In this case the auto-instrumentor is not able to successfully update the 1.apk
. Normally the auto-instrumentor takes care of renewing the framework APK by deleting the framework directory and recreating the 1.apk
file using the Apktool
tool. However the Apktool
will not clean its framework directory if more than just the 1.apk
are installed. In this case you must update the 1.apk
manually.
You have to adjust the default value of the DTXPrimaryDexLimit
property. See the Multi-dex applications section in Auto-instrumentation for Android for details.
Dynatrace Gradle plugin
There can be multiple reasons for this error message:
- Not specifying the
applicationId
and/or thestartupPath
property. - Not adding a configuration block (
dynatrace
) to your module'sbuild.gradle
file. - Not defining a configuration for your product flavor and also not adding a default configuration.
Check if you have added the buildscript
block with the classpath 'com.dynatrace.tools:android:<version_number>.+'
dependency to your module's build.gradle
file.
Gradle was not able to find the specified version. Check if you have specified the correct version number. You can check the available version on JCenter and Maven Central. You also must add jcenter()
or mavenCentral()
to your buildscript
configuration.
Gradle was not able to find a version that matches your version settings. You can check the available version on JCenter and
Maven Central. You also have to add jcenter()
or mavenCentral()
to your buildscript
configuration.
Check if you have applied the Dynatrace Gradle plugin before the dynatrace
block and the dynatrace.agent()
dependency
apply plugin: 'com.dynatrace.tools.android'
dynatrace {
...
The Dynatrace Gradle plugin started the auto-instrumentation, but it failed. Check the error message from the auto-instrumentor and check the auto-instrumentation FAQ section for further help.
The Dynatrace Gradle plugin auto-instrumented your APK file, but was not able to successfully extract your signing information and sign the instrumented APK file with your certificate. Check if your Dynatrace plugin version fits the used Android plugin version. See the section Supported versions on the Gradle Plugin for Android page.
Because auto-instrumentation was successful, you can use the generated instrumented APK in the <project>/<module>/build/outputs/apk/<app_name>/dist
folder. You must sign the <app_name>.apk
file manually with your Google playstore certificate.
You have added the Android agent library multiple times. Check if you have added the Dynatrace.jar
to your libs directory and remove it. See the section Combine with manual instrumentation on the Gradle Plugin for Android page for information on how to integrate manual instrumentation into your build process.
The log file is stored in the <project>/<module>/build/tmp/autoInstrument<build_variant>/logs
directory.
For version 2.2 and later of the Android Gradle plugin, the Dynatrace Gradle plugin generates an uninstrumented APK file with a file suffix of _uninstrumented
. In some cases it can be useful to have an uninstrumented version of the application, for example if you notice that the agent interferes with another library. If you use manual instrumentation, then the manual instrumentation is still part of the _uninstrumented
APK file.
Check if you have uploaded the correct file: <project>/<module>/build/outputs/apk/<app_name>.apk
. Do not use the APKs in the
<project>/<module>/build/outputs/apk/<app_name>/dist
directory, because they are unsigned or signed with a debug certificate.