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

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:

Requirement	Minimum
Gradle	7.0.2
Android Gradle Plugin (AGP)	7.0
JVM	Java 11

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(...)

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:

```
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.
```
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:

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

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:

bash

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

Windows (cmd):

text

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

Windows (PowerShell):

text

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:

bash

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

Windows (cmd):

text

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

Windows (PowerShell):

text

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:

text

<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.):

Stop immediately — do not attempt further changes.
Report the failure — state clearly which step failed and why.
Rollback all edits — restore every file modified in this phase to its original content. If a file was created from scratch, delete it.
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:

text

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:

text

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:

text

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:

text

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:

text

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:

text

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:

text

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:

text

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:

bash

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

Windows (cmd):

text

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

Windows (PowerShell):

text

.\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.

dt-obs-android

NPX Install

Tags

SKILL.md Content

Android Dynatrace Instrumentation

Phase 1: Preflight

Phase 2: Detect existing setup

Phase 3: Collect inputs

Phase 4: Locate files

Finding the app module

Files to read before editing

Finding the entry-point file

Phase 5: Instrument

Root build file

Kotlin DSL (
`build.gradle.kts`
)

Groovy DSL (
`build.gradle`
)

Entry-point file (Application class or launcher activity)

Kotlin

Java

Phase 6: Build and verify

dt-obs-android

NPX Install

Tags

SKILL.md Content

Android Dynatrace Instrumentation

Phase 1: Preflight

Phase 2: Detect existing setup

Phase 3: Collect inputs

Phase 4: Locate files

Finding the app module

Files to read before editing

Finding the entry-point file

Phase 5: Instrument

Root build file

Kotlin DSL (build.gradle.kts)

Groovy DSL (build.gradle)

Entry-point file (Application class or launcher activity)

Kotlin

Java

Phase 6: Build and verify

Kotlin DSL (
`build.gradle.kts`
)

Groovy DSL (
`build.gradle`
)