Demeter

Description

Demeter is a performance measurement library that can simplify performance issue investigation in your app. It's also useful to give a specially prepared build with Demeter inside to your QA team to use during regression testing and upload performance reports at the end.

Features

• Tracer: Measures project methods with information about execution thread, execution time, and sorts by hazard level
• Inject: Wraps and measures @Inject constructor initializations and their dependencies. Useful for identifying problems with Dagger graphs
• Compose: Observes StateObject changes and recompositions
• Coroutine Tracer: Tracks coroutine job lifecycle (launch/async) with automatic bytecode instrumentation. Displays coroutine hierarchies as an interactive tree view
• Enriches methods with profileable sections that help investigate problems in Android Profiler or Profiler
• Exports measurements to CSV, Flamegraph, Firefox profiler and Flipper

Screenshots

Injected constructor analysis

Tracer for methods

Method export to Excel

Inspect Compose recompositions and StateObjects

Usage

Integrated Demeter provides an Activity that opens when you click the notification. The notification appears in any place of your application.

Architecture

Demeter consists of the following libraries:

Library	Description
demeter-core	Base interfaces without implementations. Can be used for release build type
demeter-profiler	Main profiler implementation for dev/debug build types. Do not attach to release builds!
demeter-profiler-base	Base profiler logic
demeter-profiler-ui	Profiler UI components
demeter-profiler-coroutine-tracer-plugin	Coroutine lifecycle tracing runtime
demeter-profiler-coroutine-tracer-ui-plugin	Coroutine tracer Compose tree-view UI
demeter-gradle-plugin	Main Demeter Gradle Plugin

Profiler Plugins

Functionality is provided via profiler plugins:

Plugin	Description
demeter-profiler-tracer-plugin	Method tracing
demeter-profiler-inject-plugin	@Inject constructor analysis
demeter-profiler-compose-plugin	Jetpack Compose analyzer
demeter-profiler-coroutine-tracer-plugin	Coroutine lifecycle tracing

Note: When using published Maven artifacts (not building from source), you need to explicitly add plugin dependencies in addition to the main profiler dependency.

Setup with UI

Use this setup to get the built-in metrics viewer accessible via notification.

Step 1. Add the Demeter plugin to your module's build.gradle.kts:

plugins {
    id("com.yandex.demeter")
}

Step 2. Add dependencies:

dependencies {
    debugImplementation("com.yandex.demeter:profiler:VERSION")

    // UI plugins (only add the ones you need):
    debugImplementation("com.yandex.demeter:profiler-tracer-ui-plugin:VERSION")
    debugImplementation("com.yandex.demeter:profiler-inject-ui-plugin:VERSION")
    debugImplementation("com.yandex.demeter:profiler-compose-ui-plugin:VERSION")
    debugImplementation("com.yandex.demeter:profiler-coroutine-tracer-ui-plugin:VERSION")
}

Step 3. Add profileable flag to your AndroidManifest.xml (inside <application> tag):

<profileable
    android:enabled="true"
    android:shell="true"
    tools:ignore="UnusedAttribute" />

Step 4. Initialize Demeter in your Application class:

override fun onCreate() {
    super.onCreate()

    Demeter.init(
        UiDemeterInitializer(
            context = this,
            uiPlugins = listOf(
                TracerUiDemeterPlugin(context = this),
                InjectUiDemeterPlugin(),
                ComposeUiDemeterPlugin(),
                CoroutineTracerUiDemeterPlugin(context = this),
            ),
        )
    )
}

Step 5. Configure the Demeter Gradle plugin:

demeter {
    tracer {
        includedClasses = listOf("com.yandex.myapp")
    }
    inject {
        includedClasses = listOf("com.yandex.myapp")
    }
    compose()
    coroutineTracer {
        includedClasses = listOf("com.yandex.myapp")
    }
}

Step 6. Build and run! A notification will appear to open the metrics viewer.

---

Setup without UI

Use this setup when you want to collect metrics programmatically without the built-in UI. This is useful for custom reporting, analytics integration, or automated testing.

Step 1. Add the Demeter plugin to your module's build.gradle.kts:

plugins {
    id("com.yandex.demeter")
}

Step 2. Add dependencies:

dependencies {
    debugImplementation("com.yandex.demeter:profiler:VERSION")

    // Plain plugins (only add the ones you need):
    debugImplementation("com.yandex.demeter:profiler-tracer-plugin:VERSION")
    debugImplementation("com.yandex.demeter:profiler-inject-plugin:VERSION")
    debugImplementation("com.yandex.demeter:profiler-compose-plugin:VERSION")
    debugImplementation("com.yandex.demeter:profiler-coroutine-tracer-plugin:VERSION")
}

Step 3. Add profileable flag to your AndroidManifest.xml (inside <application> tag):

<profileable
    android:enabled="true"
    android:shell="true"
    tools:ignore="UnusedAttribute" />

Step 4. Initialize Demeter in your Application class:

override fun onCreate() {
    super.onCreate()

    Demeter.init(
        DemeterInitializer(
            plugins = listOf(
                TracerDemeterPlugin(context = this),
                InjectDemeterPlugin(),
                ComposeDemeterPlugin(),
                CoroutineTracerDemeterPlugin(),
            ),
        )
    )
}

Step 5. Configure the Demeter Gradle plugin:

demeter {
    tracer {
        includedClasses = listOf("com.yandex.myapp")
    }
    inject {
        includedClasses = listOf("com.yandex.myapp")
    }
    compose()
    coroutineTracer {
        includedClasses = listOf("com.yandex.myapp")
    }
}

Step 6. Build and run!

---

Compose feature and library modules

The main app plugin configures only the module where it is applied. Compose feature or library modules are fully manual: apply the Compose Gradle plugin, enable it for the required build type, and add the Compose profiler hook as a compile-only dependency.

import com.yandex.demeter.compose.plugin.DemeterComposeBuildTypeDslExtension

plugins {
    id("com.yandex.demeter.compose")
}

android {
    buildTypes {
        getByName("debug") {
            extensions.configure<DemeterComposeBuildTypeDslExtension>("demeterCompose") {
                enabled = true
            }
        }
    }
}

dependencies {
    debugCompileOnly("com.yandex.demeter:profiler-compose-plugin:VERSION")
}

The app module still owns runtime dependencies such as profiler-compose-ui-plugin or profiler-compose-plugin. Feature and library modules use compileOnly only so compiler-generated references can resolve during compilation without adding Demeter runtime classes to their APK/runtime classpath.

---

Custom Reporter

You can provide a custom reporter to send metrics to your analytics or logging system:

val customReporter = DemeterReporter { payload ->
    // payload contains metrics data as Map<String, Any>
    analytics.track("demeter_metrics", payload)
}

// With UI
Demeter.init(
    UiDemeterInitializer(
        context = this,
        uiPlugins = listOf(
            TracerUiDemeterPlugin(context = this, reporter = customReporter),
            InjectUiDemeterPlugin(reporter = customReporter),
        ),
    )
)

// Without UI
Demeter.init(
    DemeterInitializer(
        plugins = listOf(
            TracerDemeterPlugin(context = this, reporter = customReporter),
            InjectDemeterPlugin(reporter = customReporter),
        ),
    )
)

---

Gradle Plugin Configuration

Full configuration options:

demeter {
    tracer {
        enabled = true                                    // default: false
        debug = false                                     // default: false - enables ASM debug output
        includedClasses = listOf("com.yandex.myapp")      // required: packages to analyze
        excludedClasses = listOf("com.yandex.myapp.test") // optional: packages to exclude
    }

    inject {
        enabled = true                                    // default: false
        debug = false                                     // default: false - enables ASM debug output
        includedClasses = listOf("com.yandex.myapp")      // required: packages to analyze
        excludedClasses = listOf("com.yandex.myapp.di")   // optional: packages to exclude
    }

    compose {
        enabled = true  // default: false
        debug = false   // default: false - enables compiler plugin debug output
    }

    coroutineTracer {
        enabled = true                                    // default: false
        debug = false                                     // default: false - enables ASM debug output
        includedClasses = listOf("com.yandex.myapp")      // required: packages to analyze
        excludedClasses = listOf("com.yandex.myapp.test") // optional: packages to exclude
    }
}

You can also configure per build type separately:

android {
    buildTypes {
        getByName("debug") {
            demeter {
                tracer {
                    includedClasses = listOf("com.yandex.myapp")
                }
                inject {
                    includedClasses = listOf("com.yandex.myapp")
                }
                compose()
            }
        }
    }
}

Configuration Reference

Tracer Plugin Parameters

Parameter	Type	Default	Description
enabled	Boolean	false	Enable/disable tracer feature
debug	Boolean	false	Enable ASM debug output (TraceClassVisitor with ASMifier)
includedClasses	List<String>	[]	Class name prefixes to trace (required - if empty, nothing is traced)
excludedClasses	List<String>	[]	Class name prefixes to exclude from tracing

Note: The following packages are always excluded from tracing:

• java.*, javax.*, kotlin.*, kotlinx.*
• com.yandex.demeter.* (except com.yandex.demeter.showcase.*)
• Kotlin intrinsics classes (ending with WhenMappings)

Inject Plugin Parameters

Parameter	Type	Default	Description
enabled	Boolean	false	Enable/disable inject analysis
debug	Boolean	false	Enable ASM debug output
includedClasses	List<String>	[]	Class name prefixes to analyze (required)
excludedClasses	List<String>	[]	Class name prefixes to exclude

Compose Plugin Parameters

Parameter	Type	Default	Description
enabled	Boolean	false	Enable/disable Compose inspection
debug	Boolean	false	Enable compiler plugin debug output

Coroutine Tracer Plugin Parameters

Parameter	Type	Default	Description
enabled	Boolean	false	Enable/disable coroutine tracing
debug	Boolean	false	Enable ASM debug output
includedClasses	List<String>	[]	Class name prefixes to trace (required)
excludedClasses	List<String>	[]	Class name prefixes to exclude

Limitations: instruments only kotlinx.coroutines.BuildersKt.{launch, async} (and their *$default variants). runBlocking, withContext, produce, actor, flow { ... }.launchIn, and custom CoroutineScope extensions are not currently traced.

Runtime Plugin Classes

Plugin Class	Parameters	Description
TracerDemeterPlugin	context: Context, reporter: DemeterReporter?	Plain tracer plugin
InjectDemeterPlugin	reporter: DemeterReporter?	Plain inject plugin
ComposeDemeterPlugin	none	Plain compose plugin
TracerUiDemeterPlugin	context: Context, reporter: DemeterReporter?	Tracer with UI
InjectUiDemeterPlugin	reporter: DemeterReporter?	Inject with UI
ComposeUiDemeterPlugin	none	Compose with UI
CoroutineTracerDemeterPlugin	context: Context, reporter: DemeterReporter?	Plain coroutine tracer
CoroutineTracerUiDemeterPlugin	context: Context, reporter: DemeterReporter?	Coroutine tracer with tree-view UI

Gradle Plugins

Demeter feature plugins can be applied via the main plugin:

plugins {
    id("com.yandex.demeter")
}

Or applied directly:

plugins {
    id("com.yandex.demeter.tracer")
    id("com.yandex.demeter.inject")
    id("com.yandex.demeter.compose")
}

Note: The main plugin configures the current app module only. Feature and library modules that need Compose instrumentation must apply com.yandex.demeter.compose directly and configure demeterCompose.

Available Gradle Plugins

Plugin ID	Artifact	Description
com.yandex.demeter	demeter-gradle-plugin	Main plugin (applies all sub-plugins)
com.yandex.demeter.tracer	tracer-gradle-plugin	Method tracing instrumentation
com.yandex.demeter.inject	inject-gradle-plugin	@Inject constructor instrumentation
com.yandex.demeter.compose	compose-gradle-plugin	Jetpack Compose compiler plugin
com.yandex.demeter.coroutine.tracer	coroutine-tracer-gradle-plugin	Coroutine builder instrumentation

Coroutine Tracer

The Coroutine Tracer plugin automatically instruments launch and async calls at build time via ASM bytecode transformation. At runtime it tracks the full lifecycle of every coroutine Job:

• Parent-child hierarchy — automatically detected via Job parent references
• Duration — wall-clock time from launch to completion
• Thread info — launch thread, completion thread, and dispatcher name
• Cancellation & exceptions — tracked and displayed as badges
• Interactive tree view — expand/collapse nodes, sort by time/duration/name, filter by thread

How it works

1. Build time: The Gradle plugin scans classes matching includedClasses and finds launch/async calls. It inserts a DUP + LDC "ClassName#method:line" + INVOKESTATIC CoroutineTracerAsm.onCoroutineLaunched sequence after each builder call.

2. Runtime: CoroutineTracerAsm.onCoroutineLaunched(job, launchSite) registers a completion listener on the Job. When the Job completes, a metric is emitted containing duration, thread names, cancellation status, exception info, and parent trace ID.

3. UI: Metrics are collected into a tree structure and displayed as an interactive Compose tree view with color-coded warning levels (green → yellow → red based on duration).

Coroutine Tracer setup

Step 1. Enable the plugin in your build.gradle.kts:

plugins {
    id("com.yandex.demeter")
}

demeter {
    coroutineTracer {
        includedClasses = listOf("com.your.package")
    }
}

Step 2. Add the runtime dependency:

dependencies {
    // With UI (tree-view visualization):
    debugImplementation("com.yandex.demeter:profiler-coroutine-tracer-ui-plugin:VERSION")

    // Or without UI (programmatic access only):
    debugImplementation("com.yandex.demeter:profiler-coroutine-tracer-plugin:VERSION")
}

Step 3. Initialize in your Application:

Demeter.init(
    UiDemeterInitializer(
        context = this,
        uiPlugins = listOf(
            CoroutineTracerUiDemeterPlugin(),
            // ... other plugins
        ),
    )
)

The COROUTINE TRACER tab will appear in the Demeter UI showing all tracked coroutine trees.

Flipper Integration

Demeter supports integration with Facebook's Flipper debugging tool:

dependencies {
    debugImplementation("com.yandex.demeter:flipper:VERSION")
}

Initialize with Flipper plugin:

// In your Flipper setup
val client = AndroidFlipperClient.getInstance(this)
client.addPlugin(DemeterFlipperTracerPlugin())
client.start()

Troubleshooting

Problem: Built-in class kotlin.Any is not found

Crash stacktrace:

java.lang.AssertionError: Built-in class kotlin.Any is not found

Solution: Ensure you don't exclude .kotlin_builtins files from the build:

android {
    packagingOptions {
        resources {
            // Remove or modify these excludes if present:
            // excludes += ['**/kotlin/**', '**.kotlin_builtins']
        }
    }
}

Problem: No methods are being traced

Possible causes:

1. includedClasses is empty - you must specify at least one package prefix
2. The package name doesn't match your actual class packages
3. The plugin is not enabled (enabled = false)

Solution:

demeter {
    tracer {
        enabled = true
        includedClasses = listOf("com.your.package")  // Must match your actual package
    }
}

Problem: Demeter UI notification doesn't appear

Possible causes:

1. Using DemeterInitializer instead of UiDemeterInitializer
2. Notification permissions not granted (Android 13+)

Solution: Use UiDemeterInitializer with UI plugins:

Demeter.init(
    UiDemeterInitializer(
        context = this,
        uiPlugins = listOf(TracerUiDemeterPlugin(this))
    )
)

License

Apache License 2.0