• Home
  • How to use Dynatrace
  • RUM
  • Setup and configuration
  • Mobile apps
  • Android
  • SDK
  • Instrumentation via OneAgent SDK

Instrumentation via OneAgent SDK

Start OneAgent

If you've disabled auto-start with the autoStart.enabled property or you're using standalone manual instrumentation instead of auto-instrumentation, start OneAgent manually in the Application.onCreate method. In this case, use the Dynatrace.startup(Application, Configuration) API method.

java
public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // provide the application context as parameter
        Dynatrace.startup(this, new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration());
    }
}
kotlin
class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        // provide the application context as parameter
        Dynatrace.startup(this, DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration())
    }
}

If you need to start OneAgent at a later stage, then use the Dynatrace.startup(Activity, Configuration) API method. You have to provide the active Activity as a parameter so that OneAgent can immediately monitor it.

java
Dynatrace.startup(yourActiveActivity, new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
  ... // additional configuration
  .buildConfiguration());
kotlin
Dynatrace.startup(yourActiveActivity, DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
  ... // additional configuration
  .buildConfiguration())
Start OneAgent in OneAgent SDK for Android versions 8.229 and earlier

If you've disabled auto-start with the autoStart.enabled property or you're using standalone manual instrumentation instead of auto-instrumentation, start OneAgent manually in the Application.onCreate method.

java
public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Dynatrace.startup(this, new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration());
    }
}
kotlin
class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        Dynatrace.startup(this, DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
            ... // additional configuration
            .buildConfiguration())
    }
}

If your app supports Direct Boot, ensure that Dynatrace.startup is never called from a Direct Boot aware component. You should also see Adjust communication with OneAgent SDK for Android to ensure that OneAgent is able to transmit the data to the cluster.

Configure OneAgent

Use the DynatraceConfigurationBuilder class to customize all advanced OneAgent settings with different API methods.

java
new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withUserOptIn(true)
    .withCrashReporting(true)
    .buildConfiguration();
kotlin
DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withUserOptIn(true)
    .withCrashReporting(true)
    .buildConfiguration()

If you use a combination of manual and auto-instrumentation, the auto-instrumentation injects a Dynatrace.startup call into the Application.onCreate method. In this case, you will lose your manual configuration because the Dynatrace.startup call from the auto-instrumentation is called before your Dynatrace.startup call.

The autoStart.enabled property allows you to deactivate the auto-start feature from the auto-instrumentation. You can then define a manual Dynatrace.startup call in the Application.onCreate method. In this case, you can override the values preconfigured from the auto-instrumentor.

User action monitoring

With user action monitoring you can define and report your own custom user actions. These user actions can be enriched with the following monitoring operations:

  • Report an event
  • Report a value
  • Report an error
  • attach a web request to the user action
  • Create a child action

Manually created user actions are different from the user actions created with the Dynatrace Android Gradle plugin. OneAgent does not automatically add additional events, such as web requests, to your custom user actions, and it does not automatically close your user actions after a specific time period. However, if OneAgent has to start a new session or it shuts down, it closes all custom user actions that have not yet been closed manually.

Create custom user actions

You can create your own custom user actions and enhance them with additional information. If manually created actions are not closed explicitly, OneAgent will close them and send them to the Dynatrace Cluster.

You need to call enterAction to start each action and leaveAction to close each action. Timing is measured automatically.

java
// start the user action
DTXAction action = Dynatrace.enterAction("exampleName");

// ...do some work here...

// end the action after the search has completed
action.leaveAction();
kotlin
val action = Dynatrace.enterAction("exampleName")

// ...do some work here...

// end the action after the search has completed
action.leaveAction()

Child actions

Child actions are similar to parent actions. When the parent action is closed, OneAgent automatically closes all nested/child actions of the parent action.

Child actions are generated using the method Dynatrace.enterAction(String, DTXAction).

java
// start parent user action
DTXAction parentAction = Dynatrace.enterAction("parent_user_action_name");

// ...do some work here...

// start child user action
DTXAction childAction = Dynatrace.enterAction("child_user_action_name", parentAction);

// ...do some work here...

// end the child action
childAction.leaveAction();

// ...do some work here...

// end the parent action
parentAction.leaveAction();
kotlin
// start parent user action
val parentAction = Dynatrace.enterAction("parent_user_action_name")

// ...do some work here...

// start child user action
val childAction = Dynatrace.enterAction("child_user_action_name", parentAction)

// ...do some work here...

// end the child action
childAction.leaveAction()

// ...do some work here...

// end the parent action
parentAction.leaveAction()

Cancel custom user actions

OneAgent SDK for Android version 8.231+

If you need to cancel an already created but not yet completed action, use the DTXAction#cancel() API call.

Canceling an action discards all data associated with it: all reported values are discarded and all child actions are canceled.

Note that you cannot cancel a completed action.

Determine custom user action state

OneAgent SDK for Android version 8.231+

Sometimes it's helpful to know whether a custom user action is still open and can be used to report data.

To check the state of custom user action, use the DTXAction#isFinished() method.

A custom user action is finished when the action is:

  • Completed via DTXAction#leaveAction(), or
  • Canceled via DTXAction#cancel(), or
  • Terminated by OneAgent (for example, when OneAgent shuts down)

In any case, you shouldn't interact with a finished custom user action.

User action sample

The following code snippet shows a sample instrumentation of the fictional method search, which makes a web request to an instrumented server and parses the received result. The following instrumentation actions are part of the code snippet:

  1. Creates a user action
  2. Reports a custom metric
  3. Reports a handled exception
  4. Monitors a web request
  5. Creates a child action
java
public boolean search(String query) {
    // [1a] start outer/parent action
    DTXAction searchAction = Dynatrace.enterAction("search");

    // [2] report your own metric
    searchAction.reportValue("query", query);

    URL url;
    try {
        url = new URL("https://www.example.com/?query=" + query);
    } catch (MalformedURLException e) {
        // [3] report an error
        searchAction.reportError("invalid url", e);

        // [1b] end outer action
        searchAction.leaveAction();
        return false;
    }

    // [4.1] Generate a new unique tag associated with the user action "search"
    String uniqueRequestTag = searchAction.getRequestTag();
    // [4.2] Generate a WebRequestTiming object based on the unique tag
    WebRequestTiming timing = Dynatrace.getWebRequestTiming(uniqueRequestTag);

    Request request = new Request.Builder()
            .url(url)
            // [4.3] Place the Dynatrace HTTP header on your web request
            .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
            .build();

    // [4.4] Start web request timing before the HTTP request is sent
    timing.startWebRequestTiming();
    try (Response response = client.newCall(request).execute()) {
        if (!response.isSuccessful()) {
            // [4.5] Stop web request timing when a connection exception occurs
            timing.stopWebRequestTiming(url, response.code(), response.message());
            return false;
        }
        String body = response.body().string();

        // [4.5] Stop web request timing when the HTTP response is received and the response body was obtained
        timing.stopWebRequestTiming(url, response.code(), response.message());

        // [5a] start inner action
        DTXAction parseAction = Dynatrace.enterAction("parse result", searchAction);

        parseResult(body);

        // [5b] end inner action
        parseAction.leaveAction();

        return true;
    } catch (IOException e) {
        // [4.5] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString());

        return false;
    }
    finally {
        // [1b] end outer action
        searchAction.leaveAction();
    }
}
kotlin
fun search(query: String): Boolean {
    // [1a] start outer/parent action
    val searchAction = Dynatrace.enterAction("search")

    // [2] report your own metric
    searchAction.reportValue("query", query)

    var url: URL? = null
    try {
        url = URL("https://www.example.com/?query=$query")
    } catch (e: MalformedURLException) {
        // [3] report an error
        searchAction.reportError("invalid url", e)

        // [1b] end outer action
        searchAction.leaveAction()
        return false
    }

    // [4.1] Generate a new unique tag associated with the user action "search"
    val uniqueRequestTag = searchAction.requestTag
    // [4.2] Generate a WebRequestTiming object based on the unique tag
    val timing = Dynatrace.getWebRequestTiming(uniqueRequestTag)

    val request = Request.Builder()
        .url(url)
        // [4.3] Place the Dynatrace HTTP header on your web request
        .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
        .build()

    try {
        // [4.4] Start web request timing before the HTTP request is sent
        timing.startWebRequestTiming()
        client.newCall(request).execute().use { response ->
            if (!response.isSuccessful) {
                // [4.5] Stop web request timing when a connection exception occurs
                timing.stopWebRequestTiming(url, response.code, response.message)
                return false
            }
            val body = response.body!!.string()

            // [4.5] Stop web request timing when the HTTP response is received and the response body was obtained
            timing.stopWebRequestTiming(url, response.code, response.message)

            // [5a] start inner action
            val parseAction = Dynatrace.enterAction("parse result", searchAction)

            parseResult(body)

            // [5b] end inner action
            parseAction.leaveAction()
        }

        return true
    } catch (e: IOException) {
        // [4.5] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString())

        return false
    } finally {
        // [1b] end outer action
        searchAction.leaveAction()
    }
}

Custom value reporting

Report event

The report event feature allows you to report the time point of a specific event. The reported event must be part of a user action.

java
action.reportEvent("event_name");
kotlin
action.reportEvent("event_name")

Report value

The report value feature allows you to report your own metrics. These metrics must be part of a user action. The OneAgent SDK allows you to report metrics with the following value types:

  • int
  • long
  • double
  • String

Metrics with type long are supported for OneAgent SDK versions 8.197+.

java
// report int
action.reportValue("int_metrics_name", 5);
// report long
action.reportValue("long_metrics_name", 5L);
// report double
action.reportValue("double_metrics_name", 5.6);
// report string
action.reportValue("string_metrics_name", "exampleValue");
kotlin
// report int
action.reportValue("int_metrics_name", 5)
// report long
action.reportValue("long_metrics_name", 5L)
// report double
action.reportValue("double_metrics_name", 5.6)
// report string
action.reportValue("string_metrics_name", "exampleValue")

Report errors

The reporting error feature is different from the reporting value feature in that it is specifically identified as an error type event. The OneAgent SDK allows you to report the following:

  • Error codes with the reportError(String, int) method
  • Handled exceptions with the reportError(String, Throwable) method
java
// report error code
action.reportError("error_code_name", -1);
// report exception
action.reportError("exception_name", exception);
kotlin
// report error code
action.reportError("error_code_name", -1)
// report exception
action.reportError("exception_name", exception)

You can also report errors as stand-alone error events via the class Dynatrace:

java
// report error code
Dynatrace.reportError("error_code_name", -1);
// report exception
Dynatrace.reportError("exception_name", exception);
kotlin
// report error code
Dynatrace.reportError("error_code_name", -1)
// report exception
Dynatrace.reportError("exception_name", exception)

Lifecycle monitoring

OneAgent SDK for Android version 8.223+

With lifecycle monitoring, OneAgent collects the following data:

  • Activity display: Measures the timespan from Activity.onCreate(Bundle) to Activity.onPostResume() and reports the time of each activity lifecycle state that is entered.
  • Activity redisplay: Measures the time it takes to redisplay a previously created activity and reports the time of each activity lifecycle state that is entered until the activity is visible again.

Activity lifecycle monitoring is on by default but can be disabled using the withActivityMonitoring method:

java
new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withActivityMonitoring(false)
    .buildConfiguration();
kotlin
DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withActivityMonitoring(false)
    .buildConfiguration()

Web request monitoring

To track web requests, add the x-dynatrace HTTP header with a unique value to the web request. The tag correlates the server-side monitoring data to the corresponding mobile web request. Additionally, the timing values from the mobile side must be measured.

Perform the following steps to successfully monitor a web request:

  1. Generate a new unique tag.

  2. Generate a WebRequestTiming object based on the tag.

  3. Place the Dynatrace HTTP header on your web request.

  4. Start web request timing before the HTTP request is sent.

  5. Stop web request timing.

    1. The HTTP response is received and the response body is obtained.

    2. A connection exception occurs.

Do not manually and auto-instrument the same web requests. This behavior can lead to incorrect monitoring data.

Web requests can either be:

  • attached to a user action by generating a unique tag with the DTXAction.getRequestTag() method
  • or monitored as a standalone web request by generating a unique tag with the Dynatrace.getRequestTag() method

For monitoring standalone web requests, OneAgent automatically tries to find an appropriate user action. If it finds one, the web request is attached to the user action. The web request is only reported as a standalone web request when no appropriate user action is found.

Attach a web request to the user action

The following sample shows how a synchronous OkHttp web request could be monitored:

java
URL url = new URL("https://www.example.com");

// First, create a user action
DTXAction webAction = Dynatrace.enterAction("search request");
// [1] Generate a new unique tag associated with the user action
String uniqueRequestTag = webAction.getRequestTag();
// [2] Generate a WebRequestTiming object based on the unique tag
WebRequestTiming timing = Dynatrace.getWebRequestTiming(uniqueRequestTag);

// Define your OkHttp request, this varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(url)
        // Define your headers for the OkHttp request
        .addHeader(yourKey1, yourValue1)
        .addHeader(yourKey2, yourValue2)
        // [3] Place the Dynatrace HTTP header on your web request
        .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
        .build();

// [4] Start web request timing before the HTTP request is sent
timing.startWebRequestTiming();
try (Response response = client.newCall(request).execute()) {
    if (response.isSuccessful()) {
        // handle response
        String body = response.body().string();
    }

    // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.stopWebRequestTiming(url, response.code(), response.message());
} catch (IOException e) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString());

    // user-defined exception handling
}
finally {
    // Lastly, leave the action
    webAction.leaveAction();
}
kotlin
val url = URL("https://www.example.com")

// First, create a user action
val webAction = Dynatrace.enterAction("search request")
// [1] Generate a new unique tag associated with the user action
val uniqueRequestTag = webAction.requestTag
// [2] Generate a WebRequestTiming object based on the unique tag
val timing = Dynatrace.getWebRequestTiming(uniqueRequestTag)

// Define your OkHttp request, this varies greatly depending on your implementation
val request = Request.Builder()
    .url(url)
    // Define your headers for the OkHttp request
    .addHeader(yourKey1, yourValue1)
    .addHeader(yourKey2, yourValue2)
    // [3] Place the Dynatrace HTTP header on your web request
    .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
    .build()

try {
    // [4] Start web request timing before the HTTP request is sent
    timing.startWebRequestTiming()
    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            // handle response
            val body = response.body!!.string()
        }

        // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
        timing.stopWebRequestTiming(url, response.code, response.message)
    }
} catch (e: IOException) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString())

    // user-defined exception handling
} finally {
    // Lastly, leave the action
    webAction.leaveAction()
}

Standalone web request

The following sample shows how a synchronous OkHttp web request can be monitored:

java
URL url = new URL("https://www.example.com");

// [1] Generate a new unique tag
String uniqueRequestTag = Dynatrace.getRequestTag();
// [2] Generate a WebRequestTiming object based on the unique tag
WebRequestTiming timing = Dynatrace.getWebRequestTiming(uniqueRequestTag);

// Define your OkHttp request, this varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(url)
        // Define your headers for the OkHttp request
        .addHeader(yourKey1, yourValue1)
        .addHeader(yourKey2, yourValue2)
        // [3] Place the Dynatrace HTTP header on your web request
        .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
        .build();

// [4] Start web request timing before the HTTP request is sent
timing.startWebRequestTiming();
try (Response response = client.newCall(request).execute()) {
    if (response.isSuccessful()) {
        // handle response
        String body = response.body().string();
    }

    // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.stopWebRequestTiming(url, response.code(), response.message());
} catch (IOException e) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString());

    // user-defined exception handling
}
kotlin
val url = URL("https://www.example.com")

// [1] Generate a new unique tag
val uniqueRequestTag = Dynatrace.getRequestTag()
// [2] Generate a WebRequestTiming object based on the unique tag
val timing = Dynatrace.getWebRequestTiming(uniqueRequestTag)

// Define your OkHttp request, this varies greatly depending on your implementation
val request = Request.Builder()
    .url(url)
    // Define your headers for the OkHttp request
    .addHeader(yourKey1, yourValue1)
    .addHeader(yourKey2, yourValue2)
    // [3] Place the Dynatrace HTTP header on your web request
    .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
    .build()

try {
    // [4] Start web request timing before the HTTP request is sent
    timing.startWebRequestTiming()
    client.newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            // handle response
            val body = response.body!!.string()
        }

        // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
        timing.stopWebRequestTiming(url, response.code, response.message)
    }
} catch (e: IOException) {
    // [5.2] Stop web request timing when a connection exception occurs
    timing.stopWebRequestTiming(url, -1, e.toString())

    // user-defined exception handling
}

HttpURLConnection

For monitoring HttpURLConnection web requests, OneAgent SDK contains an additional API method: Dynatrace.getWebRequestTiming(HttpURLConnection). It automatically generates a unique tag and places it on the HttpURLConnection connection. You can also use the WebRequestTiming.stopWebRequestTiming() method, because OneAgent can automatically determine the status code and message from the specified HttpURLConnection.

java
URL url = new URL("https://www.example.com");
HttpURLConnection conn = null;
WebRequestTiming timing = null;

// First, create an action
DTXAction webAction = Dynatrace.enterAction("search request");
try {
    conn = (HttpURLConnection) url.openConnection();

    // [1], [2], [3] Once the connection object is obtained, tag it automatically and receive a WebRequestTiming instance
    timing = Dynatrace.getWebRequestTiming(conn);

    // [4] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.startWebRequestTiming();
    InputStream stream = new BufferedInputStream(conn.getInputStream());
    readStream(stream);

    // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.stopWebRequestTiming();
} catch (Exception e) {
    if(timing != null) {
        // [5.2] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString());
    }

    // user-defined exception handling
} finally {
    if (conn != null) {
        conn.disconnect();
    }
    // Lastly, leave the action
    webAction.leaveAction();
}
kotlin
val url = URL("https://www.example.com")
var conn: HttpURLConnection? = null
var timing: WebRequestTiming? = null

// First, create an action
val webAction = Dynatrace.enterAction("search request")
try {
    conn = url.openConnection() as HttpURLConnection

    // [1], [2], [3] Once the connection object is obtained, tag it automatically and receive a WebRequestTiming instance
    timing = Dynatrace.getWebRequestTiming(conn)

    // [4] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.startWebRequestTiming()
    val stream = BufferedInputStream(conn.getInputStream())
    readStream(stream)

    // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
    timing.stopWebRequestTiming()
} catch (e: Exception) {
    timing?.stopWebRequestTiming(url, -1, e.toString())

    // user-defined exception handling
} finally {
    conn?.disconnect()
    // Lastly, leave the action
    webAction.leaveAction()
}

Other samples

Attach an asynchronous OkHttp web request to a user action
java
final URL url = new URL("https://www.example.com");

// First, create an action
final DTXAction webAction = Dynatrace.enterAction("search request");
// [1] Generate a new unique tag associated with the user action
String uniqueRequestTag = webAction.getRequestTag();
// [2] Generate a WebRequestTiming object based on the unique tag
final WebRequestTiming timing = Dynatrace.getWebRequestTiming(uniqueRequestTag);

// Define your OkHttp request, this varies greatly depending on your implementation
Request request = new Request.Builder()
        .url(url)
        // Define your headers for the OkHttp request
        .addHeader(yourKey1, yourValue1)
        .addHeader(yourKey2, yourValue2)
        // [3] Place the Dynatrace HTTP header on your web request
        .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
        .build();

// [4] Call startWebRequestTiming to begin the timing, and then handle the response body from the OkHttp call
timing.startWebRequestTiming();
client.newCall(request).enqueue(new Callback() {
    @Override
    public void onFailure(Call call, IOException e) {
        // [5.2] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString());

        // user-defined exception handling

        // [8] Lastly, leave the action
        webAction.leaveAction();
    }

    @Override
    public void onResponse(Call call, Response response) throws IOException {
        try (ResponseBody responseBody = response.body()) {
            if (response.isSuccessful()) {
                // handle response
                String body = response.body().string();
            }

            // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
            timing.stopWebRequestTiming(url, response.code(), response.message());

            // Lastly, leave the action
            webAction.leaveAction();
        }
    }
});
kotlin
val url = URL("https://www.example.com")

// First, create an action
val webAction = Dynatrace.enterAction("search request")
// [1] Generate a new unique tag associated with the user action
val uniqueRequestTag = webAction.requestTag
// [2] Generate a WebRequestTiming object based on the unique tag
val timing = Dynatrace.getWebRequestTiming(uniqueRequestTag)

// Define your OkHttp request, this varies greatly depending on your implementation
val request = Request.Builder()
    .url(url)
    // Define your headers for the OkHttp request
    .addHeader(yourKey1, yourValue1)
    .addHeader(yourKey2, yourValue2)
    // [3] Place the Dynatrace HTTP header on your web request
    .addHeader(Dynatrace.getRequestTagHeader(), uniqueRequestTag)
    .build()

// [4] Call startWebRequestTiming to begin the timing, and then handle the response body from the OkHttp call
timing.startWebRequestTiming()
client.newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        // [5.2] Stop web request timing when a connection exception occurs
        timing.stopWebRequestTiming(url, -1, e.toString())

        // user-defined exception handling

        // [8] Lastly, leave the action
        webAction.leaveAction()
    }

    @Throws(IOException::class)
    override fun onResponse(call: Call, response: Response) {
        response.use {
            if (response.isSuccessful) {
                // handle response
                val body = response.body!!.string()
            }

            // [5.1] Stop web request timing when the HTTP response is received and the response body was obtained
            timing.stopWebRequestTiming(url, response.code, response.message)

            // Lastly, leave the action
            webAction.leaveAction()
        }
    }
})

Crash reporting

OneAgent captures all unhandled exceptions and errors and sends the crash report immediately to the server. The Android crash report includes the occurrence time and the full stack trace of the exception.

Disable crash reporting

You can also deactivate crash reporting with the withCrashReporting method:

java
new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withCrashReporting(false)
    .buildConfiguration();
kotlin
DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withCrashReporting(false)
    .buildConfiguration()

Tag specific users

You can tag each user of your mobile apps with a unique user name. This enables you to search and filter specific user sessions and analyze individual user behavior over time. The following steps explain how to manually tag an individual user via the Dynatrace API.

java
Dynatrace.identifyUser("john.doe@example.com");
kotlin
Dynatrace.identifyUser("john.doe@example.com")

The user tag value is not stored and must be renewed every session.

Data privacy

To dynamically adjust privacy settings and build your apps in compliance with data protection laws and regulations, enable the userOptIn flag via the DSL from the Dynatrace Android Gradle plugin or use the ConfigurationBuilder.withUserOptIn method.

The privacy API methods allow you to dynamically activate and deactivate crash reporting and to change the data-collection level based on the individual preferences of your users. Each user can select from the following data-privacy levels:

  • Off: Monitoring data isn't captured.
  • Performance: Only anonymous performance data is captured. Monitoring data that can be used to identify individual users, such as user tags and custom values, isn't captured.
  • User behavior: Performance data and user data is captured. In this mode, OneAgent recognizes and reports users who revisit in the future.

By default, crash reporting is deactivated and data-collection level is set to off. Based on your end user's individual preference, they can change their privacy settings when the app starts for the first time. Dynatrace doesn't provide a consent banner or any similar UI component. You must integrate the network dialog into your app. We recommend that you display the dialog before your app is displayed and then apply the user's privacy preference. You must also allow your users to change their privacy settings in the future.

With the Dynatrace.applyUserPrivacyOptions method, you can adjust privacy settings based on the user's decision. OneAgent persists the privacy settings and automatically applies them when the app is restarted. Additionally, a new session is created whenever the privacy settings are changed via the Dynatrace.applyUserPrivacyOptions method.

You can retrieve the privacy settings with the Dynatrace.getUserPrivacyOptions method. However, you won't be able to retrieve the correct values if you use this method before OneAgent starts.

java
Dynatrace.applyUserPrivacyOptions(UserPrivacyOptions.builder()
    .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
    .withCrashReportingOptedIn(true)
    .build()
);
kotlin
Dynatrace.applyUserPrivacyOptions(UserPrivacyOptions.builder()
    .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
    .withCrashReportingOptedIn(true)
    .build()
)
Data privacy in OneAgent SDK for Android versions 8.189 and earlier

With the Dynatrace.setCrashReportingOptedIn(boolean) method, you can activate or deactivate crash reporting. The data collection level can be changed with the Dynatrace.setDataCollectionLevel(DataCollectionLevel) method.

You can retrieve the privacy settings with the Dynatrace.getDataCollectionLevel() and Dynatrace.isCrashReportingOptedIn() methods. But you can't use the privacy API methods before OneAgent starts. Otherwise, OneAgent will throw an exception.

Hybrid apps that use RUM JavaScript inside a WebView

For hybrid applications that use the RUM JavaScript, cookies must be set for each instrumented domain or server that the application communicates with. When the hybrid app monitoring feature is enabled, OneAgent generates these cookies for every specified domain and stores them in CookieManager.

You can activate the hybrid app monitoring feature with the withHybridMonitoring method. All used domains, hosts, and IP addresses must be specified via the withMonitoredDomains or the withMonitoredHttpsDomains method. Domains and sub-domains must start with a dot (.).

java
new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredDomains("<domain1>", "<domain2>")
    .buildConfiguration();
kotlin
DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredDomains("<domain1>", "<domain2>")
    .buildConfiguration()

Dynatrace allows you to add the Secure cookie attribute for all cookies that are set by Dynatrace. This ensures that the browser sends these cookies only over secure connections.

java
new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredHttpsDomains("https://<domain1>", "https://<domain2>")
    .buildConfiguration();
kotlin
DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withHybridMonitoring(true)
    .withMonitoredHttpsDomains("https://<domain1>", "https://<domain2>")
    .buildConfiguration()

Instrument WebView

OneAgent SDK for Android version 8.191+

To enable communication between RUM JavaScript and OneAgent for Android, all WebView objects must be instrumented before the URL is loaded with WebView.loadUrl(String). The Dynatrace.instrumentWebView method must be instrumented for every WebView that contains the RUM JavaScript. Without this method call, the monitoring data may not be associated with the same session.

java
WebView myWebView = (WebView) findViewById(R.id.webview);
Dynatrace.instrumentWebView(myWebView);
myWebView.loadUrl("http://www.example.com");
kotlin
val myWebView: WebView = findViewById(R.id.webview)
Dynatrace.instrumentWebView(myWebView)
myWebView.loadUrl("http://www.example.com")

Due to security reasons, this method call is ignored on devices with API versions 15 and 16.

Preserve cookies

OneAgent SDK for Android version 8.191+

Call this method when you delete all cookies via CookieManager#removeAllCookies(ValueCallback) or CookieManager#removeSessionCookies(ValueCallback). Without the Dynatrace-related cookies, data from the RUM JavaScript and OneAgent for Android can't be combined into a single session.

java
CookieManager.getInstance().removeAllCookies(null);
Dynatrace.restoreCookies();
kotlin
CookieManager.getInstance().removeAllCookies(null)
Dynatrace.restoreCookies()

Adjust OneAgent behavior

Startup load balancing

OneAgent allows you to enable client-side load balancing that helps avoid unbalanced load on the server when multiple OneAgents simultaneously establish a connection to the ActiveGate.

java
new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withStartupLoadBalancing(true)
    .buildConfiguration();
kotlin
DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconURL>")
    .withStartupLoadBalancing(true)
    .buildConfiguration()