Tracing Recompositions At Runtime

Tracing Recompositions at Runtime — @TraceRecomposition, logcat, and the live heatmap

Layout Inspector counts recompositions and surfaces Argument Change Reasons, but it works only in debug, where Live Literals and the interpreted Compose runtime inflate counts. @TraceRecomposition from skydoves/compose-stability-analyzer instruments a composable at compile time and emits per-recomposition diffs (which state changed, what value transition) to logcat under the Recomposition tag. The instrumentation works in any build the developer enables it for — including release-with-debug-symbols — and feeds the IntelliJ / Android Studio plugin's live recomposition heatmap.

This skill is the release-mode complement to ../../recomposition/debugging-recompositions/SKILL.md. Layout Inspector is debug-only, fast to set up, and good for the first triage. @TraceRecomposition is the ground-truth confirmation: instrument the suspect composable, ship a release+R8 build of the dev APK, run the user journey, and read the per-recomposition log lines.

When to use this skill

• A composable recomposes more than expected and Layout Inspector counts are inconclusive (the count differs between debug and release, or the suspect is an inline composable not covered by Layout Inspector).
• A stability or strong-skipping fix needs to be confirmed against a release-equivalent build before merging.
• A developer wants per-state-and-per-parameter change diffs printed inline rather than clicking through the Layout Inspector tree.
• A team wants to baseline a composable's recomposition count for an SLO ("PriceTicker recomposes ≤ once per price update; never per parent tick").
• The user mentions @TraceRecomposition, "trace recomposition", "compose-stability-analyzer", "recomposition logcat", "recomposition heatmap", or "release-mode recomposition".

When NOT to use this skill

• The developer just wants recomposition counts in debug — Layout Inspector is faster to set up. See ../../recomposition/debugging-recompositions/SKILL.md.
• The build is a production release with no diagnosis intent — the instrumentation must be gated off. See the runtime-toggle pattern below.
• The team needs a CI gate that fails on future stability regressions — runtime tracing is for diagnosis; gating is ../../stability/enforcing-stability-in-ci/SKILL.md (stabilityCheck).
• The need is per-frame timing or end-to-end user-perceived perf, not recomposition counts — that is ../generating-baseline-profiles/SKILL.md with MacrobenchmarkRule + FrameTimingMetric.

Prerequisites

• The Gradle plugin com.github.skydoves.compose.stability.analyzer (latest, v0.7.3+) added to the module that owns the composables to instrument.
• An Application subclass declared in the manifest, so ComposeStabilityAnalyzer.setEnabled(...) can be called from onCreate().
• Compose Compiler reachable from the same module — org.jetbrains.kotlin.plugin.compose applied (Kotlin 2.0+).
• A BuildConfig field or feature flag the runtime toggle can read. BuildConfig.DEBUG works; a custom BuildConfig.ENABLE_RECOMPOSITION_TRACE is preferred for production-style profiling builds.
• For the IntelliJ / Android Studio heatmap: the compose-stability-analyzer plugin installed from the JetBrains marketplace (or built locally from the GitHub repo).
• Familiarity with ../../recomposition/debugging-recompositions/SKILL.md so the developer has already named the suspect composable in debug before reaching for runtime tracing.

Workflow

1. Apply the Gradle plugin

In the module's build.gradle.kts:

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose")
    alias(libs.plugins.compose.stability.analyzer)
}

In gradle/libs.versions.toml:

[versions]
composeStabilityAnalyzer = "0.7.3"

[plugins]
compose-stability-analyzer = { id = "com.github.skydoves.compose.stability.analyzer", version.ref = "composeStabilityAnalyzer" }

2. Configure the analyzer

Same build.gradle.kts, alongside the plugins block:

composeStabilityAnalyzer {
    enabled.set(true) // compile-time switch; runtime toggle below gates emission
}

enabled.set(true) controls whether the compiler weaves in the instrumentation. With enabled.set(false) no @TraceRecomposition annotations have any effect. Leaving it on across all build types is fine — the runtime toggle is the actual production gate.

3. Annotate the composables to trace

import com.skydoves.compose.stability.runtime.TraceRecomposition

@TraceRecomposition(traceStates = true)
@Composable
fun PriceTicker(price: Price) {
    Text(price.formatted)
}

traceStates = true extends the diff to mutableStateOf reads inside the composable body, not just parameters. Start with true for first investigation; flip to false once the cause is known to keep logs compact.

4. Add the runtime toggle in Application.onCreate()

import com.skydoves.compose.stability.runtime.ComposeStabilityAnalyzer

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        ComposeStabilityAnalyzer.setEnabled(BuildConfig.DEBUG)
    }
}

Without this call, every annotated composable still emits to logcat — including in release. Gate the toggle behind BuildConfig.DEBUG or a custom BuildConfig.ENABLE_RECOMPOSITION_TRACE so the production APK is silent.

5. Reproduce the symptom and read logcat

adb logcat -s Recomposition:D

Sample output for an animated PriceTicker whose price changes from 99.0 to 99.5 (illustrative — exact log shape depends on the analyzer version):

D/Recomposition: [Recomposition #1] PriceTicker
D/Recomposition:   ├─ [param] price: Price changed (Price(99.0) → Price(99.5))
D/Recomposition: [Recomposition #2] PriceTicker
D/Recomposition:   ├─ [param] price: Price unchanged (skipped via strong-skipping equals)

The number after # is a per-instance counter — cumulative across the lifetime of the composable's restart scope. A composable that prints [Recomposition #50] while only being on screen for two seconds is the smoking gun.

6. Open the live heatmap in Android Studio (optional)

Install the Compose Stability Analyzer plugin from JetBrains Marketplace. With the plugin installed and the app running, the editor gutter next to each @TraceRecomposition-annotated composable shows a color-coded badge. Indicative thresholds (illustrative — see the plugin's settings panel for the current bands):

• Green — fewer than 10 recompositions in the current session.
• Yellow — 10 to 50 recompositions.
• Red — more than 50 recompositions.

Click the badge to jump to a side panel listing each [Recomposition #N] entry with its diff. The panel mirrors logcat but groups by composable instance so the developer can spot which LazyColumn row is misbehaving without scrolling logcat.

7. Chain back to the upstream fix

Runtime tracing names the composable and the changing parameter. The fix lives elsewhere:

• Param recomposes because the type is unstable → ../../stability/diagnosing-compose-stability/SKILL.md and ../../stability/stabilizing-compose-types/SKILL.md.
• Param recomposes because of a captured lambda or Flow → ../../recomposition/using-strong-skipping-correctly/SKILL.md and ../../side-effects/collecting-flows-safely/SKILL.md.
• State read happened in the wrong phase (Composition vs Layout vs Draw) → ../../recomposition/deferring-state-reads/SKILL.md.
• Layout Inspector showed an Argument Change Reason status that needed to be acted on → ../../recomposition/debugging-recompositions/SKILL.md.

Once the fix lands, re-run the trace; the post-fix logcat should show one initial [Recomposition #1] and no subsequent entries during the same scenario.

8. Gate against future regressions in CI

@TraceRecomposition is for diagnosis. Preventing the next regression is a CI concern: enable stabilityCheck in CI per ../../stability/enforcing-stability-in-ci/SKILL.md, which fails the build when a previously-skippable composable becomes non-skippable.

Patterns

Pattern: annotate the suspect, run a release-with-debug build, read the diff

// RIGHT
@TraceRecomposition(traceStates = true)
@Composable
fun PriceTicker(price: Price) {
    Text(price.formatted)
}

Sample logcat output (illustrative — exact log shape depends on the analyzer version; the price changes once per second; the surrounding row recomposes once per parent tick):

D/Recomposition: [Recomposition #3] PriceTicker
D/Recomposition:   ├─ [param] price: Price changed (Price(99.0) → Price(99.5))
D/Recomposition: [Recomposition #4] PriceTicker
D/Recomposition:   ├─ [param] price: Price unchanged
D/Recomposition:   ├─ [reason] parent restart scope re-invoked; strong-skipping equals matched

The second entry is the desirable shape: parent ticked, the equals() guard fired, body skipped.