dt-setup-android

Android Dynatrace Instrumentation

Scope: Basic setup only — from zero to first event. For anything beyond initial instrumentation (custom actions, crash grouping, data privacy policies, etc.) refer to the Dynatrace documentation directly.

Phase 1: Preflight

Before doing anything else, check that the current directory is an Android project root by looking for settings.gradle.kts or settings.gradle. If neither exists, stop and tell the user this is not an Android project root, and ask them to navigate to the correct directory.

Then verify the following minimum requirements. If any are not met, stop and inform the user of what needs to be upgraded before proceeding:

Run ./gradlew --version (or gradlew.bat --version on Windows). The output covers both Gradle and the actual JVM Gradle is using (the Daemon JVM line), which may differ from the system Java when the project is opened in Android Studio or IntelliJ. Do not use java -version — it may report a different JDK than what the build actually runs on. The AGP version is declared in the root build file.

Phase 2: Detect existing setup

If a dynatrace { } block or a configure<com.dynatrace.tools.android.dsl.DynatraceExtension> { } block (also written as configure<DynatraceExtension> { } when the class is imported) is found anywhere in the build files, read it and extract if present:

• applicationId (the value passed to applicationId(...) or applicationId '...')
• beaconUrl (the value passed to beaconUrl(...) or beaconUrl '...')

Save these as pre-filled values to carry into Phase 3. If either value is absent or uses a placeholder (e.g. YOUR_APPLICATION_ID), treat it as not found. Proceed to Phase 3.

Phase 3: Collect inputs

First, ask only for:

1. applicationId — Dynatrace application ID. Tell the user this can be found in their Dynatrace tenant, inside the mobile application they have already created. If a value was extracted in Phase 2, show it as the current value and ask the user to confirm or replace it.
2. beaconUrl — Dynatrace beacon URL. Tell the user this can also be found in their Dynatrace tenant, inside the same mobile application configuration. Same: show the extracted value if available and ask to confirm or replace.

Once the user confirms or provides both, then ask — unless the user already stated their session replay preference in their initial request, in which case skip this question and use what they said:

1. Session replay — should session replay be enabled? (yes/no)

Phase 4: Locate files

Finding the app module

The application module is not always named app. Read settings.gradle.kts or settings.gradle to find all included modules, then check each module's build file for the com.android.application plugin. Use the directory of the first module that applies it as APP_MODULE for all paths below.

macOS / Linux:

grep -r -l --include="*.gradle" --include="*.gradle.kts" --exclude-dir=buildSrc "com.android.application" .

Windows (cmd):

findstr /s /m "com.android.application" *.gradle *.gradle.kts

Windows (PowerShell):

Get-ChildItem -Recurse -Include "*.gradle","*.gradle.kts" | Select-String "com.android.application" | Select-Object -ExpandProperty Path

Discard any result where the matching line contains apply false — those are version-catalog declarations in the root build file, not actual plugin applications. Also discard any result under buildSrc/.

If no module applying com.android.application is found after filtering, stop and report the failure — no files have been modified at this point.

Files to read before editing

• Root build.gradle.kts / build.gradle (sibling of the settings file)
• App APP_MODULE/build.gradle.kts / APP_MODULE/build.gradle
• Entry-point source file — see below

Finding the entry-point file

Preferred: Application class. Search the source tree for a class that extends Application using the appropriate command for the OS:

macOS / Linux:

grep -r -l --include="*.java" "extends Application" APP_MODULE/src
grep -r -l --include="*.kt" ": Application()" APP_MODULE/src

Windows (cmd):

findstr /s /m "extends Application" APP_MODULE\src\*.java
findstr /s /m ": Application()" APP_MODULE\src\*.kt

Windows (PowerShell):

Get-ChildItem -Recurse -Path APP_MODULE/src -Include "*.java" | Select-String "extends Application" | Select-Object -ExpandProperty Path
Get-ChildItem -Recurse -Path APP_MODULE/src -Include "*.kt" | Select-String ": Application()" | Select-Object -ExpandProperty Path

If found, use that file. Add the privacy opt-in call inside its onCreate(), after super.onCreate().

Fallback: Launcher activity. If no Application class exists, find the launcher activity in AndroidManifest.xml — it is the <activity> that contains:

<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />

Read the android:name attribute of that activity, locate its source file, and add the privacy opt-in call inside onCreate(), after setContentView(...).

Once the file is found, detect the language from its extension: .kt = Kotlin, .java = Java.

Do not assume the file is named MainActivity.

Phase 5: Instrument

For each step below, check whether the element is already present before writing. If it is present and correct, skip it. If it is present but incorrect or incomplete, update only the affected values. If it is absent, add it in full.

Before editing any file, record its original content. If any step fails for any reason (build error, missing file, unresolvable conflict, unexpected file structure, etc.):

1. Stop immediately — do not attempt further changes.
2. Report the failure — state clearly which step failed and why.
3. Rollback all edits — restore every file modified in this phase to its original content. If a file was created from scratch, delete it.
4. Confirm rollback — tell the user which files were restored and that the project is back to its original state.

Do not leave the project in a partially instrumented state.

Root build file

First check whether the root build file is build.gradle.kts (Kotlin DSL) or build.gradle (Groovy DSL) and apply the matching syntax.

com.dynatrace.instrumentation must be applied in the root build file, not the app module.

Kotlin DSL (build.gradle.kts)

Classpath dependency — check whether com.dynatrace.tools.android:gradle-plugin already appears in a buildscript { dependencies { } } block. If yes and the version spec is 8.+, skip. If yes with a different version, update the version to 8.+. If absent, add the classpath into an existing buildscript { dependencies { } } block if one exists; otherwise add the full buildscript block before the plugins {} block:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("com.dynatrace.tools.android:gradle-plugin:8.+")
    }
}

Plugin apply — check whether apply(plugin = "com.dynatrace.instrumentation") is already present. If yes, skip. If absent, add it after the plugins {} block.

DynatraceExtension block — check whether a configure<com.dynatrace.tools.android.dsl.DynatraceExtension> block already exists.

• If it exists, check each field and update only those that differ from the target values: applicationId, beaconUrl, userOptIn(true), agentBehavior.startupLoadBalancing(true), agentBehavior.startupWithGrailEnabled(true), and sessionReplay.enabled(true) (if session replay was requested). Add any missing fields.
• If absent, add the full block after the plugin apply line. In both cases, substitute applicationId and beaconUrl with the values confirmed in Phase 3 — do not leave the placeholders below in place:

configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            autoStart {
                applicationId("YOUR_APPLICATION_ID")
                beaconUrl("https://your-tenant.live.dynatrace.com/mbeacon")
            }
            userOptIn(true)
            agentBehavior.startupLoadBalancing(true)
            agentBehavior.startupWithGrailEnabled(true)
            // only if session replay was requested:
            sessionReplay.enabled(true)
        }
    }
}

Groovy DSL (build.gradle)

Classpath dependency — check whether com.dynatrace.tools.android:gradle-plugin already appears in a buildscript { dependencies { } } block. If yes and the version spec is 8.+, skip. If yes with a different version, update the version to 8.+. If absent, add the classpath inside the existing buildscript { dependencies { } } block, or create the full buildscript block before any apply lines if none exists:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.dynatrace.tools.android:gradle-plugin:8.+'
    }
}

Plugin apply — check whether apply plugin: 'com.dynatrace.instrumentation' is already present. If yes, skip. If absent, add it after the existing apply lines or at the end of the file.

dynatrace block — check whether a dynatrace { } block already exists.

• If it exists, check each field and update only those that differ from the target values: applicationId, beaconUrl, userOptIn true, agentBehavior.startupLoadBalancing true, agentBehavior.startupWithGrailEnabled true, and sessionReplay.enabled true (if session replay was requested). Add any missing fields.
• If absent, add the full block after the plugin apply line. In both cases, substitute applicationId and beaconUrl with the values confirmed in Phase 3 — do not leave the placeholders below in place:

dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId 'YOUR_APPLICATION_ID'
                beaconUrl 'https://your-tenant.live.dynatrace.com/mbeacon'
            }
            userOptIn true
            agentBehavior.startupLoadBalancing true
            agentBehavior.startupWithGrailEnabled true
            // only if session replay was requested:
            sessionReplay.enabled true
        }
    }
}

Entry-point file (Application class or launcher activity)

Add only the imports not already present. For the privacy opt-in call, check whether Dynatrace.applyUserPrivacyOptions(...) already exists inside onCreate. If yes, verify each option (DataCollectionLevel.USER_BEHAVIOR, withCrashReportingOptedIn(true), withScreenRecordOptedIn(true) if session replay is enabled) and update any that differ. If absent, insert it at the position matching the entry-point type:

• Application subclass — after super.onCreate()
• Launcher activity — after setContentView(...)

Kotlin

Imports — add only those not already present:

import com.dynatrace.android.agent.Dynatrace
import com.dynatrace.android.agent.conf.DataCollectionLevel
import com.dynatrace.android.agent.conf.UserPrivacyOptions

Privacy opt-in call — insert after super.onCreate() (Application subclass) or after setContentView(...) (launcher activity). Include .withScreenRecordOptedIn(true) only if session replay was enabled in Phase 3:

Dynatrace.applyUserPrivacyOptions(
    UserPrivacyOptions.builder()
        .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
        .withCrashReportingOptedIn(true)
        // .withScreenRecordOptedIn(true) — add only if session replay is enabled
        .build()
)

Java

Imports — add only those not already present:

import com.dynatrace.android.agent.Dynatrace;
import com.dynatrace.android.agent.conf.DataCollectionLevel;
import com.dynatrace.android.agent.conf.UserPrivacyOptions;

Privacy opt-in call — insert after super.onCreate() (Application subclass) or after setContentView(...) (launcher activity). Include .withScreenRecordOptedIn(true) only if session replay was enabled in Phase 3:

Dynatrace.applyUserPrivacyOptions(UserPrivacyOptions.builder()
    .withDataCollectionLevel(DataCollectionLevel.USER_BEHAVIOR)
    .withCrashReportingOptedIn(true)
    // .withScreenRecordOptedIn(true) — add only if session replay is enabled
    .build()
);

Phase 6: Build and verify

First, discover available assemble tasks to handle projects with custom build types or product flavors:

macOS / Linux:

./gradlew tasks --group=build | grep -i "^assemble"

Windows (cmd):

gradlew.bat tasks --group=build | findstr /i "assemble"

Windows (PowerShell):

.\gradlew.bat tasks --group=build | Select-String -Pattern "^assemble" -CaseSensitive:$false

If only one assemble task is listed, use it. If multiple tasks are listed, present them to the user and ask which one to run.

Then run it:

• macOS / Linux: ./gradlew CHOSEN_TASK
• Windows (cmd): gradlew.bat CHOSEN_TASK
• Windows (PowerShell): .\gradlew.bat CHOSEN_TASK

A successful build confirms the Dynatrace plugin is wired up correctly.