Every Android team has lived this story. A screen feels sluggish, someone attaches a profiler on a well-charged flagship, the numbers look fine, and the ticket is closed as “cannot reproduce”. Two weeks later the p95 for the same screen is still ugly in your analytics, and nobody can say why.
The gap is not a lack of tools. It is that each tool answers a different question, and most teams use only the first one. This post walks through a four-stage loop that connects them, using a fictional notes app called Marigold as the running example, and spends real time on the places where each stage breaks.
Why a single profiler is never enough
A local profile is deep but narrow: one device, one build, one data set, one person deciding what to click. A CI benchmark is repeatable but synthetic. A field capture is honest but expensive and sparse. The mistake is treating any one of them as ground truth.
The more useful framing is a staircase. As you move from your desk to real users you give up per-run detail and gain coverage of devices, OS versions, thermal states, and data shapes you would never think to test.
The rest of the post follows that staircase, starting with the layer that makes the upper steps possible: cheap, structured, in-process trace points.
Stage 0: set up androidx.tracing 2.0 properly
Tracing 2.0 is a Kotlin-first, in-process API. Its notable design choice is that the backend is pluggable: your code talks to a Tracer, and a TraceDriver plus a TraceSink decide what actually gets recorded and where it is written. The default Android sink writes Perfetto-format files.
Split your dependencies by role. Libraries that only emit slices need the thin API; the app module owns the backend.
// :core:telemetry (library module)
dependencies {
implementation("androidx.tracing:tracing:<latest-stable>")
}
// :app
dependencies {
implementation("androidx.tracing:tracing-wire:<latest-stable>")
}
On Android, including tracing-wire is enough for automatic initialization via androidx.startup. If you need control over where files go, implement the factory interface on your Application:
class MarigoldApp : Application(), AbstractTraceDriver.Factory {
override fun create(): AbstractTraceDriver {
val sink = TraceSink(
context = this,
fileProvider = { File(noBackupFilesDir, "marigold-traces") },
)
return TraceDriver(context = this, sink = sink)
}
}
Two rules matter here, and both come from how the global tracer is wired:
-
Only the application owns the backend. On Android, prefer the automatic initializer or the
AbstractTraceDriver.Factoryshown above; you should not need to register a tracer by hand. On the JVM there is no bootstrap, so you callTracer.setGlobalTracer, which is annotated as a delicate API: once per process, from the entry point, never from a library. Either way, a library that installs its own tracer will fight the app. -
Name categories like packages. Filtering happens by category, so
com.marigold.syncandcom.marigold.uigive you two independent switches. Decide the taxonomy before slices spread through the codebase; renaming later invalidates every dashboard query.
Slices with metadata, not slices with string soup
A slice’s name is its identity. Keep it stable and low-cardinality, and push the variable part into metadata.
internal const val CAT_SYNC = "com.marigold.sync"
// withTransaction is a suspend function, so the slice must be a coroutine slice.
suspend fun mergeIntoDb(batch: List<NoteDto>): MergeStats =
Tracer.global.traceCoroutine(
category = CAT_SYNC,
name = "db.merge",
metadataBlock = {
addMetadataEntry("batchSize", batch.size.toLong())
},
) {
database.withTransaction { applyBatch(batch) }
}
(If your transaction API is blocking, such as runInTransaction, the plain trace { } form works.) If you instead wrote name = "db.merge.${batch.size}", every distinct size becomes its own slice name. In a field setting, that makes aggregation useless and inflates trace files. This is the first and most common failure mode.
Coroutines: where traces usually lie
Threads are the wrong unit of work in a coroutine app. One logical operation can start on Main, run on a worker, suspend, resume on a different worker, and hop to a legacy Executor. A thread-centric trace shows disconnected rectangles.
traceCoroutine attaches a propagation token to the coroutine context so slices belonging to the same operation can be linked, and the tracer records suspends and resumes so you can see when a coroutine was actually waiting.
class SyncOrchestrator(
private val api: NotesApi,
private val decryptor: LegacyDecryptor,
private val decryptExecutor: ExecutorService,
) {
suspend fun refresh(): MergeStats =
Tracer.global.traceCoroutine(CAT_SYNC, "sync.refresh") {
val delta = api.fetchDelta()
val plain = decrypt(delta)
mergeIntoDb(plain)
}
private suspend fun decrypt(batch: DeltaBatch): List<NoteDto> {
// Capture BEFORE leaving the coroutine; the Executor thread has no context.
val token = Tracer.global.tokenFromCoroutineContext()
return suspendCancellableCoroutine { cont ->
val future = decryptExecutor.submit {
val outcome = runCatching {
Tracer.global.trace(
category = CAT_SYNC,
name = "sync.decrypt",
token = token,
) { decryptor.decryptAll(batch) }
}
cont.resumeWith(outcome)
}
// Stop the worker if the caller goes away.
cont.invokeOnCancellation { future.cancel(true) }
}
}
}
Failure modes worth knowing
-
Orphaned slices after an Executor hop. Without the manually captured token,
sync.decryptappears as an unrelated blip. Capture the token on the coroutine side, before the hop. For tangled asynchronous pipelines, such as longFlowoperator chains, the library also exposes a way to take full control of manual propagation. - One suspend function, several slices. Because the tracer closes and reopens work around suspensions, a single function can show up as multiple slices. That is faithful to what the thread did, but it surprises people reading the trace for the first time. Teach it in your team’s onboarding doc.
- Flow arrows are an approximation. The current visualization is thread-centric and uses Perfetto flows; fan-out and fan-in are not drawn perfectly. Do not treat a missing arrow as proof that two pieces of work are unrelated.
-
Cancellation. Without
invokeOnCancellation, cancelling the coroutine leaves the Executor task running to completion and your trace shows work nobody is waiting for. The sample cancels theFuture; interruption only helps ifdecryptAllactually responds to it, so decide whether abandoning is acceptable.
Compose: slices inside UI effects
Composition itself is best inspected with composition tracing in the tooling. Your own code inside effects is another matter, and traceCoroutine fits naturally:
@Composable
fun NoteScreen(noteId: Long, viewModel: NoteViewModel) {
LaunchedEffect(noteId) {
Tracer.global.traceCoroutine("com.marigold.ui", "NoteScreen.load") {
viewModel.load(noteId)
}
}
// ...
}
The failure mode is subtle: whenever the key changes, the effect is cancelled and restarted, so you see a truncated slice followed by a fresh one. A Long key like noteId only restarts when the id really changes, which is correct behavior. The real trap is an unstable key, such as an object recreated on every recomposition or one without a meaningful equals. If a trace shows many short NoteScreen.load slices, look at what you pass as the key before blaming the repository.
Smart instrumentation: let the profiler pick the targets
Hand-placing slices does not scale, and instrumenting everything defeats the purpose. A better workflow: record a local method trace with the ART profiler, find the methods that matter, and generate trace points only for those.
The selection step is plain Kotlin and worth keeping in version control so reviewers can see what was chosen and why:
data class MethodStat(val signature: String, val selfTimeMs: Double, val calls: Long)
fun pickInstrumentationTargets(
stats: List<MethodStat>,
maxSlices: Int = 40,
minAvgMs: Double = 0.5,
): List<MethodStat> =
stats.asSequence()
.filter { it.calls > 0 && it.selfTimeMs / it.calls >= minAvgMs }
.sortedByDescending { it.selfTimeMs }
.take(maxSlices)
.toList()
The minAvgMs filter encodes the single most important rule of automated instrumentation: a slice has a cost, and a tiny method called a million times will cost more than it reveals. Methods with a high self-time but a very low per-call average are usually loops better measured one level up.
A generation step (a compiler plugin, bytecode transform, or source generator, whichever your build already supports) then wraps the chosen methods in the same trace { } call you would have written by hand. The bytecode details are beyond this post, and I would rather not guess at how the session implements them. What I would insist on is a CI check that fails the build if the number of injected slices exceeds the budget.
Build tooling: R8 and API tracking
The session dedicates a few minutes to build-tool optimizations involving R8 and metalava. The description does not say what is covered, so I will not pretend to summarize it. What I can say from first principles about R8:
- Slice names are string literals and survive shrinking. Class and method names captured as metadata or call-stack entries do not; upload your mapping files alongside any field traces so they can be deobfuscated.
- Inlining changes call stacks. A helper that was a distinct frame in debug may vanish in release, so compare like with like.
- Decide deliberately whether tracing is compiled out of release. If you want field data, it must not be.
Macrobenchmarks: turn the slices into a regression gate
Once slices exist, a benchmark can measure them on physical devices in CI. Time a section instead of an entire app launch and your signal gets much sharper:
@OptIn(ExperimentalMetricApi::class)
@RunWith(AndroidJUnit4::class)
class SyncRefreshBenchmark {
@get:Rule
val rule = MacrobenchmarkRule()
@Test
fun refreshAfterColdStart() = rule.measureRepeated(
packageName = "com.marigold.notes",
metrics = listOf(
TraceSectionMetric("sync.refresh", TraceSectionMetric.Mode.Sum),
FrameTimingMetric(),
),
iterations = 10,
startupMode = StartupMode.COLD,
compilationMode = CompilationMode.Partial(),
) {
pressHome()
startActivityAndWait()
// By.res(String) matches the full "package:id/name"; use the two-argument form.
device.findObject(By.res("com.marigold.notes", "refresh")).click()
device.wait(Until.hasObject(By.res("com.marigold.notes", "synced")), 10_000)
}
}
Failure modes here are mostly about trust in the number:
-
Section never found. If the slice name in the metric does not match what the app emits (a rename, a category disabled in the benchmark build), the outcome depends on mode and library version. The
Averagemode, for instance, is documented to report 0 when the section is absent. A silent zero looks like a spectacular improvement, so assert on the result in CI instead of assuming a failure will be raised. - Mismatched compilation mode. Benchmarking a fully interpreted build tells you nothing about what users with installed baseline profiles experience.
- Thermal drift. Ten iterations on a warm device are not ten independent samples. Rest the device between runs or compare medians across several jobs.
- In-process slices versus system slices. Recent Tracing 2.0 release notes mention that the benchmark capture rules can record in-process traces and merge them for the target package. Verify on your own setup that the slices you care about actually appear in the benchmark’s trace before building a gate on them.
Field tracing: ProfilingManager plus in-process slices
CI cannot tell you how the app behaves on a three-year-old mid-range phone with a nearly full disk. For that you need field data, and ProfilingManager (Android 15 and newer) can record system traces, heap dumps, heap profiles, and call-stack profiles from the device, with a rate limiter protecting users from heavy profiling.
A suspend wrapper keeps call sites tidy:
The Kotlin helpers come from androidx.core (the official sample pairs it with the tracing-ktx artifact); import androidx.core.os.requestProfiling, SystemTraceRequestBuilder, and BufferFillPolicy. The wrapper also hands the platform a CancellationSignal, so cancelling the coroutine stops the session instead of leaving it to run out its duration:
@RequiresApi(35)
suspend fun captureSystemTrace(
context: Context,
tag: String,
durationMs: Int = 20_000,
): ProfilingResult = suspendCancellableCoroutine { cont ->
val stopSignal = CancellationSignal()
cont.invokeOnCancellation { stopSignal.cancel() }
val request = SystemTraceRequestBuilder().apply {
setCancellationSignal(stopSignal)
setTag(tag)
setDurationMs(durationMs) // hard cap and safety net if cancel never fires
setBufferFillPolicy(BufferFillPolicy.RING_BUFFER)
setBufferSizeKb(16_384)
}.build()
requestProfiling(
context.applicationContext,
request,
Dispatchers.IO.asExecutor(),
) { result -> cont.resume(result) }
}
Handle the result honestly:
val result = captureSystemTrace(appContext, tag = "sync-slow")
if (result.errorCode == ProfilingResult.ERROR_NONE) {
// The path is nullable in the platform type; handle it explicitly.
result.resultFilePath?.let(uploadScheduler::enqueue)
} else {
metrics.count("profiling_failed", result.errorCode)
}
Field failure modes
- Silent rate limiting. Requests can be rejected when you ask too often. If you never read the error code, your dataset will quietly under-represent exactly the sessions you were most interested in.
- Late start. There is no signal that recording has begun, so a short delay before the interesting work is approximate. Prefer a duration cap and a ring buffer over a precise manual stop.
- Sensitive data in metadata. Trace files leave the device. Metadata keys should come from an allow-list, and values should be sizes, counts, and opaque ids, never user content.
- Upload cost. Large traces on cellular data are a user-facing regression you created. Gate uploads on network type and battery state through your background work scheduler.
- Triggering by hunch. Capture when something measurably goes wrong, such as a slice exceeding its budget, instead of at random. A threshold you already know from CI is a good starting point.
What can go wrong across the whole loop
A rollout order that survives contact with a real team
- Week one: initialize tracing, define categories, and add five hand-written slices on your slowest user journey.
- Week two: add one macrobenchmark with a section metric, and run it nightly, not per pull request.
- Week three: adopt the hotspot-selection step and set the slice budget.
- Week four: enable one field trigger, with a conservative rate, and review the first dozen traces by hand before automating anything.
Resist the urge to skip to step four. Field traces are only legible when you already have the slices from steps one to three.
🔚 Closing thought
The point of tracing is not prettier flame charts. It is shortening the distance between “a user was slow” and “this line of code, on this class of device, under these conditions”. Each stage in the loop removes one reason for a ticket to end in “cannot reproduce”.
🔐 Go Beyond Using Android — Master How It’s Actually Secured
If you’re building, testing, or breaking Android apps, understanding the security model beneath the SDK separates developers who follow best practices from those who truly understand why those practices exist. I highly recommend “Mastering Android Security: From Fundamentals to Advanced Practice.” It’s a comprehensive, architecture-first journey through app sandboxing, cryptography, network defense, reverse engineering, and exploitation — spanning everything from AndroidManifest.xml internals to TrustZone and the Verified Boot chain, with hands-on labs at every step.
- E-book: Available on Google Play
- Kindle Edition: Available on Amazon
- Topmate: Available on Topmate
- Also available in Paperback & Hardcover




Top comments (0)