In Android 17, apps targeting SDK 37 or higher will receive a new implementation of MessageQueue where the implementation is lock-free. The new implementation improves performance and reduces missed frames, but may break clients that reflect on MessageQueue private fields and methods. To learn more about the behavior change and how you can mitigate impact, check out the MessageQueue behavior change documentation. This technical blog post provides an overview of the MessageQueue rearchitecture and how you can analyze lock contention issues using Perfetto.

The Looper drives the UI thread of every Android application. It pulls work from a MessageQueue, dispatches it to a Handler, and repeats. For two decades, MessageQueue used a single monitor lock (i.e. a synchronized code block) to protect its state.

Android 17 introduces a significant update to this component: a lock-free implementation named DeliQueue.

This post explains how locks affect UI performance, how to analyze these issues with Perfetto, and the specific algorithms and optimizations used to improve the Android main thread.

The problem: Lock Contention and Priority Inversion

The legacy MessageQueue functioned as a priority queue protected by a single lock. If a background thread posts a message while the main thread performs queue maintenance, the background thread blocks the main thread.

When two or more threads are competing for exclusive use of the same lock, this is called Lock contention. This contention can cause Priority Inversion, leading to UI jank and other performance problems.

Priority inversion can happen when a high-priority thread (like the UI thread) is made to wait for a low-priority thread. Consider this sequence:

1. A low priority background thread acquires the MessageQueue lock to post the result of work that it did.

2. A medium priority thread becomes runnable and the Kernel’s scheduler allocates it CPU time, preempting the low priority thread.

3. The high priority UI thread finishes its current task and attempts to read from the queue, but is blocked because the low priority thread holds the lock.

The low-priority thread blocks the UI thread, and the medium-priority work delays it further.

Analyzing contention with Perfetto

You can diagnose these issues using Perfetto. In a standard trace, a thread blocked on a monitor lock enters the sleeping state, and Perfetto shows a slice indicating the lock owner.

When you query trace data, look for slices named “monitor contention with …” followed by the name of the thread that owns the lock and the code site where the lock was acquired.

Case study: Launcher jank

To illustrate, let’s analyze a trace where a user experienced jank while navigating home on a Pixel phone immediately after taking a photo in the camera app. Below we see a screenshot of Perfetto showing the events leading up to the missed frame:

• Symptom: The Launcher main thread missed its frame deadline. It blocked for 18ms, which exceeds the 16ms deadline required for 60Hz rendering.

• Diagnosis: Perfetto showed the main thread blocked on the MessageQueue lock. A “BackgroundExecutor” thread owned the lock.

• Root Cause: The BackgroundExecutor runs at Process.THREAD_PRIORITY_BACKGROUND (very low priority). It performed a non-urgent task (checking app usage limits). Simultaneously, medium priority threads were using CPU time to process data from the camera. The OS scheduler preempted the BackgroundExecutor thread to run the camera threads.

This sequence caused the Launcher’s UI thread (high priority) to become indirectly blocked by the camera worker thread (medium priority), which was keeping the Launcher’s background thread (low priority) from releasing the lock.

Querying traces with PerfettoSQL

You can use PerfettoSQL to query trace data for specific patterns. This is useful if you have a large bank of traces from user devices or tests, and you’re searching for specific traces that demonstrate a problem.

For example, this query finds MessageQueue contention coincident with dropped frames (jank):

INCLUDE PERFETTO MODULE android.monitor_contention;
INCLUDE PERFETTO MODULE android.frames.jank_type;

SELECT
  process_name,
  -- Convert duration from nanoseconds to milliseconds
  SUM(dur) / 1000000 AS sum_dur_ms,
  COUNT(*) AS count_contention
FROM android_monitor_contention
WHERE is_blocked_thread_main
AND short_blocked_method LIKE "%MessageQueue%" 

-- Only look at app processes that had jank
AND upid IN (
  SELECT DISTINCT(upid)
  FROM actual_frame_timeline_slice
  WHERE android_is_app_jank_type(jank_type) = TRUE
)
GROUP BY process_name
ORDER BY SUM(dur) DESC;

In this more complex examples, join trace data that spans multiple tables to identify MessageQueue contention during app startup:

INCLUDE PERFETTO MODULE android.monitor_contention; 
INCLUDE PERFETTO MODULE android.startup.startups; 

-- Join package and process information for startups
DROP VIEW IF EXISTS startups; 
CREATE VIEW startups AS 
SELECT startup_id, ts, dur, upid 
FROM android_startups 
JOIN android_startup_processes USING(startup_id); 

-- Intersect monitor contention with startups in the same process.
DROP TABLE IF EXISTS monitor_contention_during_startup; 
CREATE VIRTUAL TABLE monitor_contention_during_startup 
USING SPAN_JOIN(android_monitor_contention PARTITIONED upid, startups PARTITIONED upid); 

SELECT 
  process_name, 
  SUM(dur) / 1000000 AS sum_dur_ms, 
  COUNT(*) AS count_contention 
FROM monitor_contention_during_startup 
WHERE is_blocked_thread_main 
AND short_blocked_method LIKE "%MessageQueue%" 
GROUP BY process_name 
ORDER BY SUM(dur) DESC;

You can use your favorite LLM to write PerfettoSQL queries to find other patterns.

At Google, we use BigTrace to run PerfettoSQL queries across millions of traces. In doing so, we confirmed that what we saw anecdotally was, in fact, a systemic issue. The data revealed that MessageQueue lock contention impacts users across the entire ecosystem, substantiating the need for a fundamental architectural change.

Solution: lock-free concurrency

We addressed the MessageQueue contention problem by implementing a lock-free data structure, using atomic memory operations rather than exclusive locks to synchronize access to shared state. A data structure or algorithm is lock-free if at least one thread can always make progress regardless of the scheduling behavior of the other threads. This property is generally hard to achieve, and is usually not worth pursuing for most code.

The atomic primitives

Lock-free software often relies on atomic Read-Modify-Write primitives that the hardware provides.

On older generation ARM64 CPUs, atomics used a Load-Link/Store-Conditional (LL/SC) loop. The CPU loads a value and marks the address. If another thread writes to that address, the store fails, and the loop retries. Because the threads can keep trying and succeed without waiting for another thread, this operation is lock-free.

ARM64 LL/SC loop example
retry:
    ldxr    x0, [x1]        // Load exclusive from address x1 to x0
    add     x0, x0, #1      // Increment value by 1
    stxr    w2, x0, [x1]    // Store exclusive.
                            // w2 gets 0 on success, 1 on failure
    cbnz    w2, retry       // If w2 is non-zero (failed), branch to retr

(view in Compiler Explorer)

Newer ARM architectures (ARMv8.1) support Large System Extensions (LSE) which include instructions in the form of Compare-And-Swap (CAS) or Load-And-Add (demonstrated below). In Android 17 we added support to the Android Runtime (ART) compiler to detect when LSE is supported and emit optimized instructions:

/ ARMv8.1 LSE atomic example
ldadd   x0, x1, [x2]    // Atomic load-add.
                        // Faster, no loop required.

In our benchmarks, high-contention code that uses CAS achieves a ~3x speedup over the LL/SC variant.

The Java programming language offers atomic primitives via java.util.concurrent.atomic that rely on these and other specialized CPU instructions.

The Data Structure: DeliQueue

To remove lock contention from MessageQueue, our engineers designed a novel data structure called DeliQueue. DeliQueue separates Message insertion from Message processing:

1. The list of Messages (Treiber stack): A lock-free stack. Any thread can push new Messages here without contention.

2. The priority queue (Min-heap): A heap of Messages to handle, exclusively owned by the Looper thread (hence no synchronization or locks are needed to access).

Enqueue: pushing to a Treiber stack

The list of Messages is kept in a Treiber stack [1], a lock-free stack that uses a CAS loop to update the head pointer.

public class TreiberStack <E> {
    AtomicReference<Node<E>> top =
            new AtomicReference<Node<E>>();
    public void push(E item) {
        Node<E> newHead = new Node<E>(item);
        Node<E> oldHead;
        do {
            oldHead = top.get();
            newHead.next = oldHead;
        } while (!top.compareAndSet(oldHead, newHead));
    }

    public E pop() {
        Node<E> oldHead;
        Node<E> newHead;
        do {
            oldHead = top.get();
            if (oldHead == null) return null;
            newHead = oldHead.next;
        } while (!top.compareAndSet(oldHead, newHead));
        return oldHead.item;
    }
}

Source code based on Java Concurrency in Practice [2], available online and released to the public domain

Any producer can push new Messages to the stack at any time. This is like pulling a ticket at a deli counter – your number is determined by when you showed up, but the order you get your food in doesn’t have to match. Because it’s a linked stack, every Message is a sub-stack – you can see what the Message queue was like at any point in time by tracking the head and iterating forwards – you won’t see any new Messages pushed on top, even if they’re being added during your traversal.

Dequeue: bulk transfer to a min-heap

To find the next Message to handle, the Looper processes new Messages from the Treiber stack by walking the stack starting from the top and iterating until it finds the last Message that it previously processed. As the Looper traverses down the stack, it inserts Messages into the deadline-ordered min-heap. Since the Looper exclusively owns the heap, it orders and processes Messages without locks or atomics.

In walking down the stack, the Looper also creates links from stacked Messages back to their predecessors, thus forming a doubly-linked list. Creating the linked list is safe because links pointing down the stack are added via the Treiber stack algorithm with CAS, and links up the stack are only ever read and modified by the Looper thread. These back links are then used to remove Messages from arbitrary points in the stack in O(1) time.

This design provides O(1) insertion for producers (threads posting work to the queue) and amortized O(log N) processing for the consumer (the Looper).

Using a min-heap to order Messages also addresses a fundamental flaw in the legacy MessageQueue, where Messages were kept in a singly-linked list (rooted at the top). In the legacy implementation, removal from the head was O(1), but insertion had a worst case of O(N) – scaling poorly for overloaded queues! Conversely, insertion to and removal from the min-heap scale logarithmically, delivering competitive average performance but really excelling in tail latencies.

In the legacy queue implementation, producers and the consumer used a lock to coordinate exclusive access to the underlying singly-linked list. In DeliQueue, the Treiber stack handles concurrent access, and the single consumer handles ordering its work queue.

Removal: consistency via tombstones

DeliQueue is a hybrid data structure, joining a lock-free Treiber stack with a single-threaded min-heap. Keeping these two structures in sync without a global lock presents a unique challenge: a message might be physically present in the stack but logically removed from the queue.

To solve this, DeliQueue uses a technique called “tombstoning.” Each Message tracks its position in the stack via the backwards and forwards pointers, its index in the heap’s array, and a boolean flag indicating whether it has been removed. When a Message is ready to run, the Looper thread will CAS its removed flag, then remove it from the heap and stack.

When another thread needs to remove a Message, it doesn’t immediately extract it from the data structure. Instead, it performs the following steps:

1. Logical removal: the thread uses a CAS to atomically set the Message’s removal flag from false to true. The Message remains in the data structure as evidence of its pending removal, a so-called “tombstone”. Once a Message is flagged for removal, DeliQueue treats it as if it no longer exists in the queue whenever it’s found.

2. Deferred cleanup: The actual removal from the data structure is the responsibility of the Looper thread, and is deferred until later. Rather than modifying the stack or heap, the remover thread adds the Message to another lock-free freelist stack.

3. Structural removal: Only the Looper can interact with the heap or remove elements from the stack. When it wakes up, it clears the freelist and processes the Messages it contained. Each Message is then unlinked from the stack and removed from the heap. 

This approach keeps all management of the heap single-threaded. It minimizes the number of concurrent operations and memory barriers required, making the critical path faster and simpler.

Traversal: benign Java memory model data races

We perform an atomic read of the head, and see A. A’s next pointer points to B. At the same time as we process B, the looper might remove B and C, by updating A to point to C and then D.

Even though B and C are logically removed, B retains its next pointer to C, and C to D. The reading thread continues traversing through the detached removed nodes and eventually rejoins the live stack at D.

By designing DeliQueue to handle races between traversal and removal, we allow for safe, lock-free iteration.

Quitting: Native refcount

Looper is backed by a native allocation that must be manually freed once the Looper has quit. If some other thread is adding Messages while the Looper is quitting, it could use the native allocation after it’s freed, a memory safety violation. We prevent this using a tagged refcount, where one bit of the atomic is used to indicate whether the Looper is quitting.

Before using the native allocation, a thread reads the refcount atomic. If the quitting bit is set, it returns that the Looper is quitting and the native allocation must not be used. If not, it attempts a CAS to increment the number of active threads using the native allocation. After doing what it needs to, it decrements the count. If the quitting bit was set after its increment but before the decrement, and the count is now zero, then it wakes up the Looper thread.

When the Looper thread is ready to quit, it uses CAS to set the quitting bit in the atomic. If the refcount was 0, it can proceed to free its native allocation. Otherwise, it parks itself, knowing that it will be woken up when the last user of the native allocation decrements the refcount. This approach does mean that the Looper thread waits for the progress of other threads, but only when it’s quitting. That only happens once and is not performance sensitive, and it keeps the other code for using the native allocation fully lock-free.

There’s a lot of other tricks and complexity in the implementation. You can learn more about DeliQueue by reviewing the source code.

Optimization: branchless programming

While developing and testing DeliQueue, the team ran many benchmarks and carefully profiled the new code. One issue identified using the simpleperf tool was pipeline flushes caused by the Message comparator code.

A standard comparator uses conditional jumps, with the condition for deciding which Message comes first simplified below:

static int compareMessages(@NonNull Message m1, @NonNull Message m2) {
    if (m1 == m2) {
        return 0;
    }

    // Primary queue order is by when.
    // Messages with an earlier when should come first in the queue.
    final long whenDiff = m1.when - m2.when;
    if (whenDiff > 0) return 1;
    if (whenDiff < 0) return -1;

    // Secondary queue order is by insert sequence.
    // If two messages were inserted with the same `when`, the one inserted
    // first should come first in the queue.
    final long insertSeqDiff = m1.insertSeq - m2.insertSeq;
    if (insertSeqDiff > 0) return 1;
    if (insertSeqDiff < 0) return -1;

    return 0;
}

This code compiles to conditional jumps (b.le and cbnz instructions). When the CPU encounters a conditional branch, it can’t know whether the branch is taken until the condition is computed, so it doesn’t know which instruction to read next, and has to guess, using a technique called branch prediction. In a case like binary search, the branch direction will be unpredictably different at each step, so it’s likely that half the predictions will be wrong. Branch prediction is often ineffective in searching and sorting algorithms (such as the one used in a min-heap), because the cost of guessing wrong is larger than the improvement from guessing correctly. When the branch predictor guesses wrong, it must throw away the work it did after assuming the predicted value, and start again from the path that was actually taken – this is called a pipeline flush.

To find this issue, we profiled our benchmarks using the branch-misses performance counter, which records stack traces where the branch predictor guesses wrong. We then visualized the results with Google pprof, as shown below:

Recall that the original MessageQueue code used a singly-linked list for the ordered queue. Insertion would traverse the list in sorted order as a linear search, stopping at the first element that’s past the point of insertion and linking the new Message ahead of it. Removal from the head simply required unlinking the head. Whereas DeliQueue uses a min-heap, where mutations require reordering some elements (sifting up or down) with logarithmic complexity in a balanced data structure, where any comparison has an even chance of directing the traversal to a left child or to a right child. The new algorithm is asymptotically faster, but exposes a new bottleneck as the search code stalls on branch misses half the time.

Realizing that branch misses were slowing down our heap code, we optimized the code using branch-free programming:

// Branchless Logic
static int compareMessages(@NonNull Message m1, @NonNull Message m2) {
    final long when1 = m1.when;
    final long when2 = m2.when;
    final long insertSeq1 = m1.insertSeq;
    final long insertSeq2 = m2.insertSeq;

    // signum returns the sign (-1, 0, 1) of the argument,
    // and is implemented as pure arithmetic:
    // ((num >> 63) | (-num >>> 63))
    final int whenSign = Long.signum(when1 - when2);
    final int insertSeqSign = Long.signum(insertSeq1 - insertSeq2);

    // whenSign takes precedence over insertSeqSign,
    // so the formula below is such that insertSeqSign only matters
    // as a tie-breaker if whenSign is 0.
    return whenSign * 2 + insertSeqSign;
}

To understand the optimization, disassemble the two examples in Compiler Explorer and use LLVM-MCA, a CPU simulator that can generate an estimated timeline of CPU cycles.

The original code:
Index     01234567890123
[0,0]     DeER .    .  .   sub  x0, x2, x3
[0,1]     D=eER.    .  .   cmp  x0, #0
[0,2]     D==eER    .  .   cset w0, ne
[0,3]     .D==eER   .  .   cneg w0, w0, lt
[0,4]     .D===eER  .  .   cmp  w0, #0
[0,5]     .D====eER .  .   b.le #12
[0,6]     . DeE---R .  .   mov  w1, #1
[0,7]     . DeE---R .  .   b    #48
[0,8]     . D==eE-R .  .   tbz  w0, #31, #12
[0,9]     .  DeE--R .  .   mov  w1, #-1
[0,10]    .  DeE--R .  .   b    #36
[0,11]    .  D=eE-R .  .   sub  x0, x4, x5
[0,12]    .   D=eER .  .   cmp  x0, #0
[0,13]    .   D==eER.  .   cset w0, ne
[0,14]    .   D===eER  .   cneg w0, w0, lt
[0,15]    .    D===eER .   cmp  w0, #0
[0,16]    .    D====eER.   csetm        w1, lt
[0,17]    .    D===eE-R.   cmp  w0, #0
[0,18]    .    .D===eER.   csinc        w1, w1, wzr, le
[0,19]    .    .D====eER   mov  x0, x1
[0,20]    .    .DeE----R   ret

Note the one conditional branch, b.le,  which avoids comparing the insertSeq fields if the result is already known from comparing the when fields.

The branchless code:
Index     012345678
[0,0]     DeER .  .   sub       x0, x2, x3
[0,1]     DeER .  .   sub       x1, x4, x5
[0,2]     D=eER.  .   cmp       x0, #0
[0,3]     .D=eER  .   cset      w0, ne
[0,4]     .D==eER .   cneg      w0, w0, lt
[0,5]     .DeE--R .   cmp       x1, #0
[0,6]     . DeE-R .   cset      w1, ne
[0,7]     . D=eER .   cneg      w1, w1, lt
[0,8]     . D==eeER   add       w0, w1, w0, lsl #1
[0,9]     .  DeE--R   ret

Here, the branchless implementation takes fewer cycles and instructions than even the shortest path through the branchy code – it’s better in all cases. The faster implementation plus the elimination of mispredicted branches resulted in a 5x improvement in some of our benchmarks!

However, this technique is not always applicable. Branchless approaches generally require doing work that will be thrown away, and if the branch is predictable most of the time, that wasted work can slow your code down. In addition, removing a branch often introduces a data dependency. Modern CPUs execute multiple operations per cycle, but they can’t execute an instruction until its inputs from a previous instruction are ready. In contrast, a CPU can speculate about data in branches, and work ahead if a branch is predicted correctly.

Testing and Validation

Validating the correctness of lock-free algorithms is notoriously difficult!

In addition to standard unit tests for continuous validation during development, we also wrote rigorous stress tests to verify queue invariants and to attempt to induce data races if they existed. In our test labs we could run millions of test instances on emulated devices and on real hardware.

With Java ThreadSanitizer (JTSan) instrumentation, we could use the same tests to also detect some data races in our code. JTSan did not find any problematic data races in DeliQueue, but – surprisingly -actually detected two concurrency bugs in the Robolectric framework, which we promptly fixed.

To improve our debugging capabilities, we built new analysis tools. Below is an example showing an issue in Android platform code where one thread is overloading another thread with Messages, causing a large backlog, visible in Perfetto thanks to the MessageQueue instrumentation feature that we added.

To enable MessageQueue tracing in the system_server process, include the following in your Perfetto configuration:

data_sources {
  config {
    name: "track_event"
    target_buffer: 0  # Change this per your buffers configuration
    track_event_config {
      enabled_categories: "mq"
    }
  }
}

Impact

DeliQueue improves system and app performance by eliminating locks from MessageQueue.

• Synthetic benchmarks: multi-threaded insertions into busy queues is up to 5,000x faster than the legacy MessageQueue, thanks to improved concurrency (the Treiber stack) and faster insertions (the min-heap).

• In Perfetto traces acquired from internal beta testers, we see a reduction of 15% in app main thread time spent in lock contention.

• On the same test devices, the reduced lock contention leads to significant improvements to the user experience, such as:

• -4% missed frames in apps.

• -7.7% missed frames in System UI and Launcher interactions.

• -9.1% in time from app startup to the first frame drawn, at the 95%ile.

Next steps

DeliQueue is rolling out to apps in Android 17. App developers should review preparing your app for the new lock-free MessageQueue on the Android Developers blog to learn how to test their apps.

References

[1] Treiber, R.K., 1986. Systems programming: Coping with parallelism. International Business Machines Incorporated, Thomas J. Watson Research Center.

[2] Goetz, B., Peierls, T., Bloch, J., Bowbeer, J., Holmes, D., & Lea, D. (2006). Java Concurrency in Practice. Addison-Wesley Professional.

Posted by Ben Weiss – Senior Developer Relations Engineer, Performance Paladin

Posted by Ben Weiss, Senior Developer Relations Engineer and Sara Hamilton, Product Manager

We spent the past week diving deep into sharing best practices and guidance that helps to make Android apps faster, smaller, and more stable. From the foundational powers of the R8 optimizer and Profile Guided Optimizations, to performance improvements with Jetpack Compose, to a new guide on levelling up your app’s performance, we’ve covered the low effort, high impact tools you need to build a performant app.

This post serves as your index and roadmap to revisit these resources whenever you need to optimize. Here are the five key takeaways from our journey together.

Use the R8 optimizer to speed up your app

The single most impactful, low-effort change you can make is fully enabling the R8 optimizer. It doesn’t just reduce app size; it performs deep, whole-program optimizations to fundamentally rewrite your code for efficiency. Revisit your Keep Rules and get R8 back into your engineering tasks.

Our newly updated and expanded documentation on the R8 optimizer is here to help.

Reddit observed a 40% faster cold startup and 30% fewer ANR errors after enabling R8 full mode.

You can read the full case study on our blog.

Engineers at Disney+ invest in app performance and are optimizing the app’s user experience. Sometimes even seemingly small changes can make a huge impact. While inspecting their R8 configuration, the team found that the -dontoptimize flag was being used. After enabling optimizations by removing this flag, the Disney+ team saw significant improvements in their app’s performance.

So next time someone asks you what you could do to improve app performance, just link them to this post.

Read more in our Day 1 blog: Use R8 to shrink, optimize, and fast-track your app

Guiding you to better performance

Baseline Profiles effectively remove the need for Just in Time compilation, improving startup speed, scrolling, animation and overall rendering performance. Startup Profiles make app startup more even more lightweight by bringing an intelligent order to your app’s classes.dex files.

And to learn more about just how important Baseline Profiles are for app performance, read Meta’s engineering blog where they shared how Baseline Profiles improved various critical performance metrics by up to 40% across their apps.

We continue to make Jetpack Compose more performant for you in Jetpack Compose 1.10. Features like pausable composition and the customizable cache window are crucial for maintaining zero scroll jank when dealing with complex list items.Take a look at the latest episode of #TheAndroidShow where we explain this in more detail.

Read more in our Wednesday’s blog: Deeper Performance Considerations

Measuring performance can be easy as 1, 2, 3

You can’t manage what you don’t measure. Our Performance Leveling Guide breaks down your measurement journey into five steps, starting with easily available data and building up to advanced local tooling.

Starting at level 1, we’ll teach you how to use readily available data from Android Vitals, which provides you with field data on ANRs, crashes, and excessive battery usage.

We’ll also teach you how to level up. For example, we’ll demonstrate how to reach level 3 with local performance testing using Jetpack Macrobenchmark and the new UiAutomator 2.4 API to accurately measure and verify any change in your app’s performance.

Read more in our Thursday’s blog

Debugging performance just got an upgrade

Advanced optimization shouldn’t mean unreadable crash reports. New features are designed to help you confidently debug R8 and background work:

Automatic Logcat Retrace

Starting in Android Studio Narwhal, stack traces can automatically be de-obfuscated in the Logcat window. This way you can immediately see and debug any crashes in a production-ready build.

Narrow Keep Rules

On Tuesday we demystified the Keep Rules needed to fix runtime crashes, emphasizing writing specific, member-level rules over overly-broad wildcards. And because it’s an important topic, we made you a video as well.

And with the new lint check for wide Keep Rules, the Android Studio Otter 3 Feature Drop has you covered here as well.

We also released new guidance on testing and troubleshooting your R8 configuration to help you get the configuration right with confidence.

Read more in our Tuesday’s blog: Configure and troubleshoot R8 Keep Rules

Background Work

We shared guidance on debugging common scenarios you may encounter when scheduling tasks with WorkManager.

Background Task Inspector gives you a visual representation and graph view of WorkManager tasks, helping debug why scheduled work is delayed or failed. And our refreshed Background Work documentation landing page highlights task-specific APIs that are optimized for particular use cases, helping you achieve more reliable execution.

Read more in our Wednesday’s blog: Background work performance considerations

Performance optimization is an ongoing journey

If you successfully took our challenge to enable R8 full mode this week, your next step is to integrate performance into your product roadmap using the App Performance Score. This standardized framework helps you find the highest leverage action items for continuous improvement.

We capped off the week with the #AskAndroid Live Q&A session, where engineers answered your toughest questions on R8, Profile Guided Optimizations, and more. If you missed it, look for the replay!

Thank you for joining us! Now, get building and keep that momentum going.

Posted by Ben Weiss – Senior Developer Relations Engineer,
Breana Tate – Developer Relations Engineer,
Jossi Wolf – Software Engineer on Compose

Compose
yourselves and let us guide you through more background on performance.

Welcome
to day 3 of Performance Spotlight Week. Today we’re continuing to share details and guidance on
important
areas of app performance. We’re covering Profile Guided Optimization, Jetpack Compose
performance
improvements and considerations on working behind the scenes. Let’s dive right in.

Profile
Guided Optimization

Baseline
Profiles
and Startup
Profiles
are foundational to improve an Android app’s startup and runtime performance. They are part of a
group of
performance optimizations called Profile Guided Optimization.

When
an app is packaged, the d8 dexer takes classes and methods and populates your app’s classes.dex
files. When a user opens the app, these dex files are loaded, one after the other until the app
can start.
By providing a Startup
Profile
you let d8 know which classes and methods to pack in the first classes.dex
files. This structure allows the app to load fewer files, which in turn improves startup
speed.

Baseline
Profiles effectively move the Just in Time (JIT) compilation steps away from user devices and
onto developer
machines. The generated Ahead Of Time (AOT) compiled code has proven to reduce startup time and
rendering
issues alike.

Trello
and Baseline Profiles

We
asked engineers on the Trello app how Baseline Profiles affected their app’s performance. After
applying
Baseline Profiles to their main user journey, Trello saw a significant 25 % reduction in app
startup
time.

Trello
was able to improve their app’s startup time by 25 % by using baseline
profiles.

Baseline
Profiles at Meta

Also,
engineers at Meta recently published an article on how they are accelerating
their Android apps with Baseline Profiles.

Across
Meta’s apps the teams have seen various critical metrics improve by up to 40 % after
applying Baseline
Profiles.

Technical
improvements like these help you improve user satisfaction and business success as well. Sharing
this with
your product owners, CTOs and decision makers can also help speed up your app’s
performance.

Get
started with Baseline Profiles

To
generate either a Baseline or Startup Profile, you write a macrobenchmark
test that exercises the app. During the test profile data is collected which will be used during
app
compilation. The tests are written using the new UiAutomator
API,
which we’ll cover tomorrow.

Writing
a benchmark like this is straightforward and you can see the full sample on GitHub.

Considerations

Start
by writing a macrobenchmark tests Baseline Profile and a Startup Profile for the path most
traveled by your
users. This means the main entry point that your users take into your app which usually is
after
they logged in.
Then continue to write more test cases to capture a more complete picture only for Baseline
Profiles. You do
not need to cover everything with a Baseline Profile. Stick to the most used paths and measure
performance
in the field. More on that in tomorrow’s post.

Get
started with Profile Guided Optimization

To
learn how Baseline Profiles work under the hood, watch this video from the Android Developers
Summit:

And
check out the Android Build Time episode on Profile Guided Optimization for another in-depth
look: 

We
also have extensive guidance on Baseline
Profiles
and Startup
Profiles
available for further reading.

Jetpack
Compose performance improvements

The
UI framework for Android has seen the performance investment of the engineering team pay off.
From version
1.9 of Jetpack Compose, scroll jank has dropped to 0.2 % during an internal long scrolling
benchmark
test. 

These
improvements were made possible because of several features packed into the most recent
releases.

Customizable
cache window

By
default, lazy layouts only compose one item ahead of time in the direction of scrolling, and
after something
scrolls off screen it is discarded. You can now customize the amount of items to retain through
a fraction
of the viewport or dp size. This helps your app perform more work upfront, and after enabling
pausable
composition in between frames, using the available time more efficiently.

To
start using customizable cache windows, instantiate a LazyLayoutCacheWindow
and pass it to your lazy list or lazy grid. Measure your app’s performance using different cache
window
sizes, for example 50% of the viewport. The optimal value will depend on your content’s
structure and item
size.

Pausable
composition

This
feature allows compositions to be paused, and their work split up over several frames. The APIs
landed in
1.9 and it is now used by default in 1.10 in lazy layout prefetch. You should see the most
benefit with
complex items with longer composition times. 

More
Compose performance optimizations

In
the versions 1.9 and 1.10 of Compose the team also made several optimizations that are a bit
less
obvious.

Several
APIs that use coroutines under the hood have been improved. For example, when using Draggable
and Clickable,
developers should see faster reaction times and improved allocation counts.

Optimizations
in layout rectangle tracking have improved performance of Modifiers like onVisibilityChanged()
and onLayoutRectChanged().
This speeds up the layout phase, even when not explicitly using these APIs.

Another
performance improvement is using cached values when observing positions via onPlaced().

Prefetch
text in the background

Starting
with version 1.9, Compose adds the ability to prefetch text on a background thread. This enables
you to
pre-warm caches to enable faster text layout and is relevant for app rendering performance.
During layout,
text has to be passed into the Android framework where a word cache is populated. By default
this runs on
the Ui thread. Offloading prefetching and populating the word cache onto a background thread can
speed up
layout, especially for longer texts. To prefetch on a background thread you can pass a custom
executor to
any composable that’s using BasicText
under the hood by passing a LocalBackgroundTextMeasurementExecutor
to a CompositionLocalProvider
like so.

Depending
on the text, this can provide a performance boost to your text rendering. To make sure that it
improves your
app’s rendering performance, benchmark and compare the results.

Background
work performance considerations

Background
Work is an essential part of many apps. You may be using libraries like WorkManager or
JobScheduler to
perform tasks like:

• Periodically
  uploading analytical events

• Syncing
  data between a backend service and a database

• Processing
  media (i.e. resizing or compressing images)

A
key challenge while executing these tasks is balancing performance and power efficiency.
WorkManager allows
you to achieve this balance. It’s designed to be power-efficient, and allow work to be deferred
to an
optimal execution window influenced by a number of factors, including constraints you specify or
constraints
imposed by the system. 

WorkManager
is not a one-size-fits-all solution, though. Android also has a number of power-optimized APIs
that are
designed specifically with certain common Core User Journeys (CUJs) in
mind.  

Reference
the Background
Work landing page
for a list of just a few of these,  including updating a widget and getting location in the
background.

Local
Debugging tools for Background Work: Common Scenarios

To
debug Background Work and understand why a task may have been delayed or failed, you need
visibility into
how the system has scheduled your tasks. 

To
help with this, WorkManager has several related
tools to help you debug locally
and optimize performance (some of these work for JobScheduler as well)! Here are some common
scenarios you
might encounter when using WorkManager, and an explanation of tools you can use to debug
them.

Debugging
why scheduled work is not executing

Scheduled
work being delayed or not executing at all can be due to a number of factors, including
specified
constraints not being met or constraints having been imposed
by the system. 

The
first step in investigating why scheduled work is not running is to confirm
the work was successfully scheduled. 
After confirming the scheduling status, determine whether there are any unmet constraints or
preconditions
preventing the work from executing.

There
are several tools for debugging this scenario.

Background
Task Inspector

The
Background Task Inspector is a powerful tool integrated directly into Android Studio. It
provides a visual
representation of all WorkManager tasks and their associated states (Running, Enqueued, Failed,
Succeeded). 

To
debug why scheduled work is not executing with the Background Task Inspector, consult the listed
Work
status(es). An ‘Enqueued’ status indicates your Work was scheduled, but is still waiting to
run.

Benefits:
Aside from providing an easy way to view all tasks, this tool is especially useful if you have
chained work.
The Background Task inspector offers a graph view that can visualize if a previous task failing
may have
impacted the execution of the following task.

Background
Task Inspector list view

Background
Task Inspector graph view

adb
shell dumpsys jobscheduler

This
command
returns a list of all active JobScheduler jobs (which includes WorkManager Workers) along with
specified
constraints, and system-imposed constraints. It also returns job
history. 

Use
this if you want a different way to view your scheduled work and associated constraints. For
WorkManager
versions earlier than WorkManager 2.10.0, adb
shell dumpsys jobscheduler
will return a list of Workers with this name:

If
your app has multiple workers, updating to WorkManager 2.10.0 will allow you to see Worker names
and easily
distinguish between workers:

Benefits:
This
command is useful for understanding if there were any system-imposed
constraints, which
you cannot determine with the Background Task Inspector. For example, this will return your
app’s
standby bucket,
which can affect the window in which scheduled work completes.

Enable
Debug logging

You
can enable custom
logging
to see verbose WorkManager logs, which will have WM—
attached. 

Benefits:
This allows you to gain visibility into when work is scheduled, constraints are fulfilled, and
lifecycle
events, and you can consult these logs while developing your app.

WorkInfo.StopReason

If
you notice unpredictable performance with a specific worker, you can programmatically observe
the reason
your worker was stopped on the previous run attempt with WorkInfo.getStopReason. 

It’s
a good practice to configure your app to observe WorkInfo using getWorkInfoByIdFlow to identify
if your work
is being affected by background restrictions, constraints, frequent timeouts, or even stopped by
the
user.

Benefits:
You can use WorkInfo.StopReason to collect field data about your workers’
performance.

Debugging
WorkManager-attributed high wake lock duration flagged by Android vitals

Android
vitals features an excessive partial wake locks metric, which highlights wake locks contributing
to battery
drain. You may be surprised to know that WorkManager
acquires wake locks to execute tasks,
and if the wake locks exceed the threshold set by Google Play, can have impacts to your app’s
visibility.
How can you debug why there is so much wake lock duration attributed to your work? You can use
the following
tools.

Android
vitals dashboard

First
confirm in the Android
vitals excessive wake lock dashboard
that the high wake lock duration is
from WorkManager and not an alarm or other wake lock. You can use the Identify
wake locks created by other APIs
documentation to understand which wake locks are held due to WorkManager. 

Perfetto

Perfetto
is a tool for analyzing system traces. When using it for debugging WorkManager specifically, you
can view
the “Device State” section to see when your work started, how long it ran, and how it
contributes to power
consumption. 

Under
“Device State: Jobs” track,  you can see any workers that have been executed and their
associated wake
locks.

Device
State section in Perfetto, showing CleanupWorker and BlurWorker execution.

Resources

Consult
the Debug
WorkManager page
for an overview of the available debugging methods for other scenarios you might
encounter.

And
to try some of these methods hands on and learn more about debugging WorkManager, check out
the
Advanced WorkManager and Testing
codelab.

Next
steps

Today
we moved beyond code shrinking and explored how the Android Runtime and Jetpack Compose actually
render your
app. Whether it’s pre-compiling critical paths with Baseline Profiles or smoothing out scroll
states with
the new Compose 1.9 and 1.10 features, these tools focus on the feel
of your app. And we dove deep into best practices on debugging background work.

Ask
Android

On
Friday we’re hosting a live AMA on performance. Ask your questions now using #AskAndroid and get
them
answered by the experts. 

The
challenge

We
challenged you on Monday to enable R8. Today, we are asking you to generate
one Baseline Profile
for your app.

With
Android
Studio Otter,
the Baseline Profile Generator module wizard makes this easier than ever. Pick your most
critical user
journey—even if it’s just your app startup and login—and generate a profile.

Once
you have it, run a Macrobenchmark to compare CompilationMode.None
vs. CompilationMode.Partial.

Share
your startup time improvements on social media using #optimizationEnabled.

Tune
in tomorrow

You
have shrunk your app with R8 and optimized your runtime with Profile Guided Optimization. But
how do you
prove
these wins to your stakeholders? And how do you catch regressions before they hit
production?

Join
us tomorrow for Day
4: The Performance Leveling Guide,
where we will map out exactly how to measure your success, from field data in Play Vitals to
deep local
tracing with Perfetto.

Posted by Alice Yuan – Senior Developer Relations Engineer

Welcome to day 4 of Performance Spotlight Week. Now that you’ve learned about some of the awesome tools and best practices we’ve introduced recently such as the R8 Optimizer, and Profile Guided Optimization with Baseline Profiles and Startup Profiles, you might be wondering where to start your performance improvement journey. 

We’ve come up with a step-by-step performance leveling guide to meet your mobile development team where you are—whether you’re an app with a single developer looking to get started with performance, or you have an entire team dedicated to improving Android performance. 

The performance leveling guide features 5 levels. We’ll start with level 1, which introduces minimal adoption effort performance tooling, and we’ll go up to level 5, ideal for apps that have the resourcing to maintain a bespoke performance framework.

 
Feel free to jump to the level that resonates most with you:

• Level 1: Use Play Console provided field monitoring

• Level 2: Follow the App Performance Score action items

• Level 3: Leverage local performance test frameworks

• Level 4: Use trace analysis tools like Perfetto 

• Level 5: Build your own performance tracking framework

Level 1:  Use Play Console provided field monitoring

We recommend first leveraging Android vitals within the Play Console for viewing automatically collected field monitoring data, giving you insights about your application with minimal effort.

Android vitals is Google’s initiative to automatically collect and surface this field data for you.

Here’s an explanation of how we deliver this data:

1. Collect Data: When a user opts-in, their Android device automatically logs key performance and stability events from all apps, including yours.

2. Aggregate Data: Google Play collects and anonymizes this data from your app’s users.

3. Surface Insights: The data is presented to you in the Android vitals dashboard within your Google Play Console.

The Android vitals dashboard tracks many metrics, but a few are designated as Core Vitals. These are the most important because they can affect your app’s visibility and ranking on the Google Play Store.

The Core Vitals

The core vitals include user-perceived crash rate, ANR rate, excessive battery usage and the newly introduced metric on excessive partial wake locks.

User-Perceived ANR Rate

You can use the Android Vitals ANR dashboard, to see stack traces of issues that occur in the field and get insights and recommendations on how to fix the issue. 

You can drill down into a specific ANR that occurred, to see the stack trace as well as insights on what might be causing the issue.

Also, check out our ANR guidance to help you diagnose and fix the common scenarios where ANRs might occur. 

User-Perceived Crash Rate 

Use the Android vitals crflevelash dashboard to further debug crashes and view a sample of stack traces that occur within your app. 

Our documentation also has guidance around troubleshooting specific crashes. For example, the Troubleshoot foreground services guide discusses ways to identify and fix common scenarios where crashes occur.

Excessive Battery Usage 

To decrease watch face sessions with excessive battery usage on Wear OS, check out the Wear guide on how to improve and conserve battery. 

[new] Excessive Partial Wake Locks

We recently announced that apps that exceed the excessive partial wake locks threshold may see additional treatment starting on March 1st 2026. 

For mobile devices, the Android vitals metric applies to non-exempted wake locks acquired while the screen is off and the app is in the background or running a foreground service. Android vitals considers partial wake lock usage excessive if wake locks are held for at least two hours within a 24-hour period and it affects more than 5% of your app’s sessions, averaged over 28 days.

To debug and fix excessive wake lock issues, check out our technical blog post.

Consult our Android vitals documentation and continue your journey to better leverage Android vitals.

Level 2: Follow the App Performance Score action items

Next, move onto using the App Performance Score to find the high leverage action items to uplevel your app performance.

The Android App Performance Score is a standardized framework to measure your app’s technical performance. It gives you a score between 0 and 100, where a lower number indicates more room for improvement.

To get easy wins, you should first start with the Static Performance Score first. These are often configuration changes or tooling updates that provide significant performance boosts.

Step 1: Perform the Static Assessment

The static assessment evaluates your project’s configuration and tooling adoption. These are often the quickest ways to improve performance.

Navigate to the Static Score section of the scoreboard page and do the following:

1. Assess Android Gradle Plugin (AGP) Version.

2. Adopt R8 Minification incrementally or ideally, use R8 in full mode to minify and optimize the app code.

3. Adopt Baseline Profiles which improves code execution speed from the first launch providing performance enhancements for every new app install and every app update.

4. Adopt Startup Profiles to improve Dex Layout. Startup Profiles are used by the build system to further optimize the classes and methods they contain by improving the layout of code in your APK’s DEX files. 

5. Upgrade to the newest version of Jetpack Compose

Step 2: Perform the Dynamic Assessment

Once you have applied the static easy wins, use the dynamic assessment to validate the improvements on a real device. You can first do this manually with a physical device and a stop watch.

Navigate to the Dynamic Score section of the scoreboard page and do the following:

1. Set up your test environment with a physical device. Consider using a lower-end device to exaggerate performance issues, making them easier to spot.

2. Measure startup time from the launcher. Cold start your app from the launcher icon and measure the time until it is interactive.

3. Measure app startup time from a notification, with the goal to reduce notification startup time to be below a couple seconds.

4. Measure rendering performance by scrolling through your core screens and animations.

Once you’ve completed these steps, you will receive a score between 1 – 100 for the static and dynamic scores, giving you an understanding of your app’s performance and where to focus on.

Level 3: Leverage local performance test frameworks

Once you’ve started to assess dynamic performance, you may find it too tedious to measure performance manually. Consider automating your performance testing using performance test frameworks such as Macrobenchmarks and UiAutomator.

Macrobenchmark UiAutomator

Think of Macrobenchmark and UiAutomator as two tools that work together: Macrobenchmark is the measurement tool. It’s like a stopwatch and a frame-rate counter that runs outside your app. It is responsible for starting your app, recording metrics (like startup time or dropped frames), and stopping the app. UiAutomator is the robot user. The library lets you write code to interact with the device’s screen. It can find an icon, tap a button,  scroll on a list and more.

How to write a test

When you write a test, you wrap your UiAutomator code inside a Macrobenchmark block.

1. Define the Test: Use the @MacrobenchmarkRule

2. Start Measuring: Call benchmarkRule.measureRepeated.

3. Drive the UI: Inside that block, use UiAutomator code to launch your app, find UI elements, and interact with them.

Here’s an example code snippet of what it looks like to test a compose list for scrolling jank.

4. Review the results: Each test run provides you with precisely measured information to give you the best data on your app’s performance.

Common use cases

Macrobenchmark provides several core metrics out of the box. StartupTimingMetric allows you to accurately measure app startup. The FrameTimingMetric enables you to understand an app’s rendering performance during the test.

We have a detailed and complete guide to using Macrobenchmarks and UiAutomator alongside code samples available for you to continue learning.

Level 4: Use trace analysis tools like Perfetto 

Trace analysis tools like Perfetto are used when you need to see beyond your own application code. Unlike standard debuggers or profilers that only see your process, Perfetto captures the entire device state—kernel scheduling, CPU frequency, other processes, and system services—giving you complete context for performance issues.

Check our Performance Debugging youtube playlist for video instructions on performance debugging using system traces, Android Studio Profiler and Perfetto.

How to use Perfetto to debug performance

The general workflow for debugging performance using trace analysis tools is to record, load and analyze the trace. 

Step 1: Record a trace

You can record a system trace using several methods: 

• Recording a trace manually on the device directly from the developer options. 

• Using the Android Studio CPU Profiler

• Using the Perfetto UI

Step 2: Load the trace

Once you have the trace file, you need to load it into the analysis tool.

1. Open Chrome and navigate to ui.perfetto.dev.

2. Drag and drop your .perfetto-trace (or .pftrace) file directly into the browser window.

3. The UI will process the file and display the timeline.

Step 3: Analyze the trace

You can use Perfetto UI or Android Studio Profiler to investigate performance issues. Check out this episode of the MAD Skills series on Performance, where our performance engineer Carmen Jackson discusses the Perfetto traceviewer.

Scenarios for inspecting system traces using Perfetto

Perfetto is an expert tool and can provide information about everything that happened on the Android device while a trace was captured. This is particularly helpful when you cannot identify the root cause of a slowdown using standard logs or basic profilers.

Debugging Jank (Dropped Frames)

If your app stutters while scrolling, Perfetto can show you exactly why a specific frame missed its deadline.

If it’s due to the app, you might see your main thread running for a long duration doing heavy parsing; this indicates scenarios where you should move the work into asynchronous processing.

If it’s due to the system, you might see your main thread ready to run, but the CPU kernel scheduler gave priority to a different system service, leaving your app waiting (CPU contention). This indicates scenarios where you may need to optimize usage of platform APIs.

Analyzing Slow App Startup

Startup is complex, involving system init, process forking, and resource loading. Perfetto visualizes this timeline precisely.

You can see if you are waiting on Binder calls (inter-process communication). If your onCreate waits a long time for a response from the system PackageManager, Perfetto will show that blocked state clearly. 

You can also see if your app is doing more work than necessary during the app startup. For example, if you are creating and laying out more views than the app needs to show, you can see these operations in the trace.

Investigating Battery Drain & CPU Usage

Because Perfetto sees the whole system, it’s perfect for finding invisible power drains.

You can identify which processes are holding wake locks, preventing the device from sleeping under the “Device State” tracks. Learn more in our wake locks blog post. Also, use Perfetto to see if your background jobs are running too frequently or waking up the CPU unnecessarily.

Level 5: Build your own performance tracking framework

The final level is for apps that have teams with resourcing to maintain a performance tracking framework. 

Building a custom performance tracking framework on Android involves leveraging several system APIs to capture data throughout the application lifecycle, from startup to exit, and during specific high-load scenarios.

By using ApplicationStartInfo, ProfilingManager, and ApplicationExitInfo, you can create a robust telemetry system that reports on how your app started, detailed info on what it did while running, and why it died.

ApplicationStartInfo: Tracking how the app started

Available from Android 15 (API 35), ApplicationStartInfo provides detailed metrics about app startup in the field. The data includes whether it was a cold, warm, or hot start, and the duration of different startup phases. 

This helps you develop a baseline startup metric using production data to further optimize that might be hard to reproduce locally. You can use these metrics to run A/B tests optimizing the startup flow.

The goal is to accurately record launch metrics without manually instrumenting every initialization phase.

You can query this data lazily some time after application launch.

ProfilingManager: Capturing why it was slow

ProfilingManager (API 35) allows your app to programmatically trigger system traces on user devices. This is powerful for catching transient performance issues in the wild that you can’t reproduce locally.

The goal is to automatically record a trace when a specific highly critical user journey is detected as running slowly or experiencing performance issues.

You can register a listener that triggers when specific conditions are met or trigger it manually when you detect a performance issue such as jank, excessive memory, or battery drain.

Check our documentation on how to capture a profile,

retrieve and analyze profiling data and use debug commands.

ApplicationExitInfo: Tracking why the app died

ApplicationExitInfo (API 30) tells you why your previous process died. This is crucial for finding native crashes, ANRs, or system kills due to excessive memory usage (OOM). You’ll also be able to get a detailed tombstone trace by using the API getTraceInputStream.

The goal of the API is to understand stability issues that don’t trigger standard Java crash reporters (like Low Memory Kills).

You should trigger this API on the next app launch.

Next Steps

Improving Android performance is a step-by-step journey. We’re so excited to see how you level up your performance using these tools!

Tune in tomorrow for Ask Android

You have shrunk your app with R8 and optimized your runtime with Profile Guided Optimization. And measure your app’s performance.

Join us tomorrow for the live Ask Android session. Ask your questions now using #AskAndroid and get them answered by the experts.

Posted by Ajesh R Pai – Developer Relations Engineer & Ben Weiss – Senior Developer Relations Engineer

In modern Android development, shipping a small, fast, and secure application is a fundamental user expectation. The Android build system’s primary tool for achieving this is the R8 optimizer, the compiler that handles dead code and resource removal for shrinking, code renaming or minification, and app optimization.

Enabling R8 is a critical step in preparing an app for release, but it requires developers to provide guidance in the form of “Keep Rules.”

After reading this article, check out the Performance Spotlight Week video on enabling, debugging and troubleshooting the R8 optimizer on YouTube.

Why Keep Rules are needed

The need to write Keep Rules stems from a core conflict: R8 is a static analysis tool, but Android apps often rely on dynamic execution patterns like reflection or calls in and out of native code using the JNI (Java Native Interface).

R8 builds a graph of used code by analyzing direct calls. When code is accessed in a dynamic way, R8’s static analysis cannot predict that and it will identify that code as unused and remove it, leading to runtime crashes.

A keep rule is an explicit instruction to the R8 compiler, stating: “This specific class, method, or field is an entry point that will be accessed dynamically at runtime. You must keep it, even if you cannot find a direct reference to it.”

See the official guide for more details on Keep Rules.

Where to write Keep Rules

Custom Keep Rules for an application are written in text file. By convention, this file is named proguard-rules.pro and is located in the root of the app or library module. This file is then specified in your module’s build.gradle.kts file’s release build type.

Use the correct default file

The getDefaultProguardFile method imports a default set of rules provided by the Android SDK. When using the wrong file your app might not be optimized. Make sure to use proguard-android-optimize.txt. This file provides the default Keep Rules for standard Android components and enables R8’s code optimizations. The outdated proguard-android.txt only provides the Keep Rules but does not enable R8’s optimizations.

Since this is a serious performance problem, we are starting to warn developers about using the wrong file, starting in Android Studio Narwhal 3 Feature Drop. And starting with the Android Gradle Plugin Version 9.0 we’re no longer supporting the outdated proguard-android.txt file. So make sure you upgrade to the optimized version.

How to write Keep Rules

A keep rule consists of three main parts:

1. An option like -keep or -keepclassmembers

2. Optional modifiers like allowshrinking

3. A class specification that defines the code to match

For the complete syntax and examples, refer to the guidance to add Keep Rules.

Keep Rule anti-patterns

It’s important to know about best practices, but also about anti-patterns. These anti-patterns often arise from misunderstandings or troubleshooting shortcuts and can be catastrophic for a production build’s performance.

Global options

These flags are global toggles that should never be used in a release build. They are only for temporary debugging to isolate a problem.

Using -dontotptimize effectively disables R8’s performance optimizations leading to a slower app.

When using -dontobfuscate you disable all renaming and using -dontshrink turns off dead code removal. Both of these global rules increase app size.

Avoid using these global flags in a production environment wherever possible for a more performant app user experience.

Overly broad keep rules

The easiest way to nullify R8’s benefits is to write overly-broad Keep Rules. Keep rules like the one below instruct the R8 optimizer to not shrink, not obfuscate, and not optimize any class in this package or any of its sub-packages. This completely removes R8’s benefits for that entire package. Try to write narrow and specific Keep Rules instead.

The inversion operator (!)

The inversion operator (!) seems like a powerful way to exclude a package from a rule. But it’s not that simple. Take this example:

You might think that this rule means “do not keep classes in com.example.package.” But it actually means “keep every class, method and property in the entire application that is not in com.example.package.” If that came as a surprise to you, best check for any negations in your R8 configuration.

Redundant rules for Android components

Another common mistake is to manually add Keep Rules for your app’s Activities, Services, or BroadcastReceivers. This is unnecessary. The default proguard-android-optimize.txt file already includes the relevant rules for these standard Android components to work out of the box.

Also many libraries bring their own Keep Rules. So you should not have to write your own rules for these. In case there is a problem with Keep Rules from a library you’re using, it is best to reach out to the library author to see what the problem is.

Keep Rule best practices

Now that you know what not to do, let’s talk about best practices.

Write narrow Keep Rules

Good Keep Rules should be as narrow and specific as possible. They should preserve only what is necessary, allowing R8 to optimize everything else.

Use common ancestors

Instead of writing separate Keep Rules for multiple different data models, write one rule that targets a common base class or interface. The below rule tells R8 to keep any members of classes that implement this interface and is highly scalable.

Use Annotations to target multiple classes

Create a custom annotation (e.g., @Serialize) and use it to “tag” classes that need their fields preserved. This is another clean, declarative, and highly scalable pattern. You can create Keep Rules for already existing annotations from frameworks you’re using as well.

Choose the right Keep Option

The Keep Option is the most critical part of the rule. Choosing the wrong one can needlessly disable optimization.

You can find more about the keep option in our documentation for Keep Options.

Allow optimization with Modifiers

Modifiers like allowshrinking and allowobfuscation relax a broad -keep rule, giving optimization power back to R8. For example, if a legacy library forces you to use -keep on an entire class, you might be able to reclaim some optimization by allowing shrinking and obfuscation:

Add global options for additional optimization

Beyond Keep Rules, you can add global flags to your R8 configuration file to encourage even more optimization.

-repackageclasses is a powerful option that instructs R8 to move all obfuscated classes into a single package. This saves significant space in the DEX file by removing redundant package name strings.

-allowaccessmodification allows R8 to widen access (e.g., private to public) to enable more aggressive inlining. This is now enabled by default when using proguard-android-optimize.txt.

Warning: Library authors must never add these global optimization flags to their consumer rules, as they would be forcibly applied to the entire app.

And to make it even more clear, in version 9.0 of the Android Gradle Plugin we’re going to start ignoring global optimization flags from libraries altogether. 

Best practices for libraries

Every Android app relies on libraries one way or another. So let’s talk about best practices for libraries.

For library developers

If your library uses reflection or JNI, you have the responsibility to provide the necessary Keep Rules to its consumers. These rules are placed in a consumer-rules.pro file, which is then automatically bundled inside the library’s AAR file.

For library consumers

Filter out problematic Keep Rules

If you must use a library that includes problematic Keep Rules, you can filter them out in your build.gradle.kts file starting with AGP 9.0 This tells R8 to ignore the rules coming from a specific dependency.

The best Keep Rule is no Keep Rule

The ultimate R8 configuration strategy is to remove the need to write Keep Rules altogether. For many apps can be achieved by choosing modern libraries that favor code generation over reflection. With code generation, the optimizer can more easily determine what code is actually used at runtime and what code can be removed. Also not using any dynamic reflection means no “hidden” entry points, and therefore, no Keep Rules are needed. When choosing a new library, always prefer a solution that uses code generation over reflection.

For more information about how to choose libraries, check choose library wisely.

Debugging and troubleshooting your R8 configuration

When R8 removes code it should have kept, or your APK is larger than expected, use these tools to diagnose the problem.

Find duplicate and global Keep Rules

Because R8 merges rules from dozens of sources, it can be hard to know what the “final” ruleset is. Adding this flag to your proguard-rules.pro file generates a complete report:

You can search this file to find redundant rules or trace a problematic rule (like -dontoptimize) back to the specific library that included it.

Ask R8: Why are you keeping this?

If a class you expected to be removed is still in your app, R8 can tell you why. Just add this rule:

During the build, R8 will print the exact chain of references that caused it to keep that class, allowing you to trace the reference and adjust your rules.

For a full guide, check out the troubleshoot R8 section.

Next steps

R8 is a powerful tool for enhancing Android app performance. Its effectiveness, depends on a correct understanding of its operation as a static analysis engine.

By writing specific, member-level rules, leveraging ancestors and annotations, and carefully choosing the right keep options, you can preserve exactly what is necessary. The most advanced practice is to eliminate the need for rules entirely by choosing modern, codegen-based libraries over their reflection-based predecessors.

As you’re following along Performance Spotlight Week, make sure to check out today’s Spotlight Week video on YouTube and continue with our R8 challenge. Use #optimizationEnabled for any questions on enabling or troubleshooting R8. We’re here to help.

It’s time to see the benefits for yourself.

We challenge you to enable R8 full mode for your app today.

1. Follow our developer guides to get started: Enable app optimization.

2. Check if you still use proguard-android.txt and replace it with proguard-android-optimize.txt.

3. Then, measure the impact. Don’t just feel the difference, verify it. Measure your performance gains by adapting the code from our Macrobenchmark sample app on GitHub to measure your startup times before and after.

We’re confident you’ll see a meaningful improvement in your app’s performance.

While you’re at it, use the social tag #AskAndroid to bring your questions. Throughout the week our experts are monitoring and answering your questions.

Stay tuned for tomorrow, where we’ll talk about Profile Guided Optimization with Baseline and Startup Profiles, share how Compose rendering performance improved over the past releases and share performance considerations for background work.

Posted by Ben Weiss – Senior Developer Relations Engineer

In today’s world of mobile applications, a seamless user experience is not just a feature—it’s a necessity. Slow load times, unresponsive interfaces, and instability can be significant barriers to user engagement and retention. During their work with the Android Developer Relations team, the engineering team at Reddit used the App Performance Score to evaluate their app. After assessing their performance, they identified significant improvement potential and decided to take the steps to enable the full power of R8, the Android app optimizer. This focused initiative led to remarkable improvements in startup times, reductions in slow or frozen frames and ANRs, and an overall increase in Play Store ratings. This case study breaks down how Reddit achieved these impressive results.

How the R8 Optimizer helped Reddit

• Tree shaking is the most important step to reduce an app’s size. Here, unused code from app dependencies and the app itself is removed.

• Method inlining replaces method calls with the actual code, making the app more performant.

• Class merging, and other strategies are applied to make the code more compact. At this point it’s not about human readability of source code any more, but making compiled code work fast. So abstractions, such as interfaces or class hierarchies don’t matter here and will be removed.

• Identifier minification changes the names of classes, fields, and methods to shorter, meaningless names. So instead of MyDataModel you might end up with a class called a. 

• Resource shrinking removes unused resources such as xml files and drawables to further reduce app size.

Caption: Main stages of R8 Optimization

From hard data to user satisfaction: Identifying success in production

Reddit saw improved performance results immediately after a new version of the app was rolled out to users. By using Android Vitals and Crashlytics, Reddit was able to capture performance metrics on real devices with actual users, allowing them to compare the new release against previous versions.

Caption: How R8 improved Reddit’s app performance

The team observed a 40% faster cold startup, a 30% reduction in “Application Not Responding” (ANR) errors, a 25% improvement in frame rendering, and a 14% reduction in app size.

These enhancements are crucial for user satisfaction. A faster startup means less waiting and quicker access to content. Fewer ANRs lead to a more stable and reliable app, reducing user frustration. Smoother frame rendering removes UI jank, making scrolling and animations feel fluid and responsive. This positive technical impact was also clearly visible in user sentiment.

User satisfaction indicators of the optimization’s success were directly visible on the Google Play Store. Following the rollout of the R8-optimized version, the team saw a dramatic and positive shift in user sentiment and engagement.

Drew Heavner: “Enabling R8’s full potential tool less than 2 weeks”

Most impressively, this was accomplished with a focused effort. Drew Heavner, the Staff Software Engineer at Reddit who worked on this initiative, noted that implementing the changes to enable R8’s full potential took less than two weeks.

Confirming the gains: A deep dive with macrobenchmarks

After observing the significant real-world improvements, Reddit’s engineering team and the Android Developer Relations team at Google conducted detailed benchmarks to scientifically confirm the gains and experiment with further optimizations. For this analysis, Reddit engineering provided two versions of their app: one without optimizations and another that applied R8 and two more foundational performance optimization tools: Baseline Profiles, and Startup Profiles.

Baseline Profiles effectively move the Just in Time (JIT) compilation steps away from user devices and onto developer machines. The generated Ahead Of Time (AOT) compiled code has proven to reduce startup time and rendering issues alike.

When an app is packaged, the d8 dexer takes classes and methods and constructs your app’s classes.dex files. When a user opens the app, these dex files are loaded, one after the other until the app can start. By providing a Startup Profile you let d8 know which classes and methods to pack in the first classes.dex files. This structure allows the app to load fewer files, which in turn improves startup speed.

Jetpack Macrobenchmark was the core tool for this phase, allowing for precise measurement of user interactions in a controlled environment. To simulate a typical user journey, they used the UIAutomator API to create a test that opened the app, scrolled down three times, and then scrolled back up.

In the end all that was needed to write the benchmark was this:

The benchmark data confirmed the field observations and provided deeper insights. The fully optimized app started 55% faster and users could begin to browse 18% sooner. The optimized app also showed a two-thirds reduction in Just in Time (JIT) compilation occurrences and a one-third decrease in JIT compilation time. Frame rendering improved, resulting in 19% more frames being rendered over the benchmarked user journey. Finally, the app’s size was reduced by over a third.

Caption: Reddit’s overall performance improvements

You can measure the JIT compilation time with a custom Macrobenchmark trace section metric like this:

Enabling the technology behind the transformation: R8

To enable R8 in full mode, you configure your app/build.gradle.kts file by setting minifyEnabled and shrinkResources to true in the release build type.

This step has to be followed by holistic end to end testing, as performance optimizations can lead to unwanted behavior, which you better catch before your users do.

As shown earlier in this article, R8 performs extensive optimizations in order to maximize your performance benefits. R8 makes substantial modifications to the code including renaming, moving, and removing classes, fields and methods. If you observe that these modifications cause errors, you need to specify which parts of the code R8 shouldn’t modify by declaring those in keep rules.

Follow Reddit’s example in your app

Reddit’s success with R8 serves as a powerful case study for any development team looking to make a significant, low-effort impact on their app’s performance. The direct correlation between the technical improvements and the subsequent rise in user satisfaction underscores the value of performance optimization.

By following the blueprint laid out in this case study—using tools like the App Performance Score to identify opportunities, enabling R8’s full optimization potential, monitoring real-world data, and using benchmarks to confirm and deepen understanding—other developers can achieve similar gains.

To get started with R8 in your own app, refer to the freshly updated official documentation and guidance on enabling, configuring and troubleshooting the R8 optimizer.

Posted by Ben Weiss – Senior Developer Relations Engineer

Welcome to day one of Android Performance Spotlight Week!

We’re kicking things off with the single most impactful, low-effort change you can make to improve your app’s performance: enabling the R8 optimizer in full mode.

You probably already know R8 as a tool to shrink your app’s size. It does a fantastic job of removing unused code and resources, reducing your app’s size. But its real power, the one it’s really g-R8 at, is as an optimizer.

When you enable full mode and allow optimizations, R8 performs deep, whole-program optimizations, rewriting your code to be fundamentally more efficient. This isn’t just a minor tweak.

After reading this article, check out the Performance Spotlight Week introduction to the R8 optimizer on YouTube.

How R8 makes your app more performant

Let’s shine a spotlight on the largest steps that the R8 optimizer takes to improve app performance.

Tree shaking is the most important step to reduce app size. During this phase the R8 optimizer removes unused code from libraries that your app depends on as well as dead code from your own codebase.

Method inlining replaces a method call with the actual code, which improves runtime performance.

Class merging, and other strategies are applied to make the code more compact. All your beautiful abstractions, such as interfaces and class hierarchies don’t matter at this point and are likely to be removed.

Code minification is used to change the names of classes, fields, and methods to shorter, meaningless ones. So instead of MyDataModel you might end up with a class called

a. This is what causes the most confusion when reading stack traces from an R8 optimized app. (Note that we have improved this in AGP 9.0!)

Resource shrinking further reduces an app’s size by removing unused resources such as xml files and drawables.

By applying these steps the R8 optimizer improves app startup times, enables smoother UI rendering, with fewer slow and frozen frames and improves overall on-device resource usage.

Case Study: Reddit’s performance improvements with R8

As one example of the performance improvements that R8 can bring, let’s take a look at an example from Reddit. After enabling R8 in full mode, the Reddit for Android app saw significant performance improvements in various areas.

Caption: How R8 improved Reddit’s app performance

The team observed a 40% faster cold startup, a 30% reduction in “Application Not Responding” (ANR) errors, a 25% improvement in frame rendering, and a 14% reduction in app size

.

These enhancements are crucial for user satisfaction. A faster startup means less waiting and quicker access to content. Fewer ANRs lead to a more stable and reliable app, reducing user frustration. Smoother frame rendering removes UI jank, making scrolling and animations feel fluid and responsive. This positive technical impact was also clearly visible in user sentiment.

You can read more about their improvements on our blog.

Non-technical side effects of using R8

During our work with partners we have seen that these technical improvements have a direct impact on user satisfaction and can be reflected in user retention, engagement and session length. User stickiness, which can be measured with daily, weekly or monthly active users, has also been positively affected by technical performance improvements. And we’ve seen app ratings on the Play Store rise in correlation with R8 adoption. Sharing this with your product owners, CTOs and decision makers can help speed up your app’s performance.

So let’s call it what it is: Deliberate performance optimization is a virtue.

Guiding you to a more performant app

We heard that our developer guidance for R8 needed to be improved. So we went to work. The developer guidance for the R8 optimizer now is much more actionable and provides comprehensive guidance to enable and debug R8.

The documentation guides you on the high-level strategy for adoption, emphasizing the importance of choosing optimization-friendly libraries and, crucially, adopting R8’s features incrementally to ensure stability. This phased approach allows you to safely unlock the benefits of R8 while providing you with guidance on difficult-to-debug issues.

We have significantly expanded our guidance on Keep Rules, which are the primary mechanism for controlling the R8 optimizer. We now provide a section on what Keep Rules are, how to apply them and guide you with best practices for writing and maintaining them. We also provide practical and actionable use cases and examples, helping you understand how to correctly prevent R8 from removing code that is needed at runtime, such as code accessed via reflection or use of the JNI native interface.

The documentation now also covers essential follow-up steps and advanced scenarios. We added a section on testing and troubleshooting, so you can verify the performance gains and debug any potential issues that arise. The advanced configurations

section explains how to target specific build variants, customize which resources are kept or removed, and offers special optimization instructions for library authors, ensuring you can provide an optimized and R8-friendly package for other developers to use.

Enable the R8 optimizer’s full potential

The R8 optimizer defaults to using “full mode” since version 8.0 of the Android Gradle Plugin. If your project has been developed over many years, it might still include a legacy flag to disable it. Check your gradle.properties file for this line and remove it.

Now check whether you have enabled R8 in your app’s build.gradle.kts file for the release variant. It’s enabled by setting isMinifyEnabled and isShrinkResources to true. You can also pass default and custom configuration files at this step.

Case Study: Disney+ performance improvements

Engineers at Disney+ invest in app performance and are optimizing the app’s user experience. Sometimes even seemingly small changes can make a huge impact. While inspecting their R8 configuration, the team found that the -dontoptimize flag was being used. It was brought in by a default configuration file, which is still used in many apps today.

After replacing proguard-android.txt

with proguard-android-optimize.txt, the Disney+ team saw significant improvements in their app’s performance.

After a new version of the app containing this change was rolled out to users, Disney+ saw 30% faster app startup and 25% fewer user-perceived ANRs. 

Today many apps still use the proguard-android.txt file which contains the -dontoptimize flag. And that’s where our tooling improvements come in.

Tooling support

Starting with Android Studio Narwhal 3 Feature Drop, you will see a lint warning when using proguard-android.txt 

And from AGP 9.0 onwards we are entirely dropping support for the file. This means you will have to migrate to proguard-android-optimize.txt.

We’ve also invested in new Android Studio features

to make debugging R8-optimized code easier than ever. Starting in AGP 9.0 you can now automatically de-obfuscate stack traces within Android Studio’s logcat for R8-processed builds, helping you pinpoint the exact line of code causing an issue, even in a fully optimized app. This will be covered in more depth in tomorrow’s blog post on this Android Performance Spotlight Week.

Next Steps

Check out the Performance Spotlight Week introduction to the R8 optimizer on YouTube.

Take the Performance Challenge!

It’s time to see the benefits for yourself.

We challenge you to enable R8 full mode for your app today.

1. Follow our developer guides to get started: Enable app optimization.

2. Check if you still use proguard-android.txt and replace it with proguard-android-optimize.txt.

3. Then, measure the impact. Don’t just feel the difference, verify it. Measure your performance gains by adapting the code from our

   Macrobenchmark sample app on GitHub to measure your startup times before and after.

We’re confident you’ll see a meaningful improvement in your app’s performance. Use #optimizationEnabled for any questions on enabling or troubleshooting R8. We’re here to help.

Bring your questions for the Ask Android session on Friday

Use the social tag #AskAndroid to bring any performance questions. Throughout the week we are monitoring your questions and will answer several in the Ask Android session on performance on Friday, November 21. Stay tuned for tomorrow, where we’ll dive even deeper into debugging and troubleshooting. But for now, get started with R8 and get your app on the fast track.

Written by Alice Yuan, Senior Developer Relations Engineer

Most of the content of this post is also available in video format, go give it a watch!

Battery life is a crucial aspect of user experience and wake locks play a major role. Are you using them excessively? In this blog post we’ll explore what wake locks are, what are some best practices for using them and how you can better understand your own app’s behavior with the Play Console metric.

Excessive partial wake lock usage in Android Vitals

The Play Console now monitors battery drain, with a focus on excessive partial wake lock usage, as a key performance indicator.

This feature elevates the importance of battery efficiency alongside existing core metric stability indicators: excessive user-perceived crashes and ANRs. Currently, an app exceeding the threshold will not be less discoverable on Google Play.

The excessive wake lock warning in the Android vitals overview.

For mobile devices, the Android vitals metric applies to non-exempted wake locks acquired while the screen is off and the app is in the background or running a foreground service. Android vitals considers partial wake lock usage excessive if:

• Wake locks are held for at least two hours within a 24-hour period.

• It affects more than 5% of your app’s sessions, averaged over 28 days.

Wake locks created by audio, location, and JobScheduler user initiated APIs are exempted from the wake lock calculation.

Understanding wake locks

A wake lock is a mechanism that allows an app to keep a device’s CPU running even when the user isn’t actively interacting with it. 

A partial wake lock keeps the CPU running even if the screen is off, preventing the CPU from entering a low-power “suspend” state. A full wake lock keeps both the screen and the CPU running.

There are 2 methods partial wake locks are acquired:

• The app manually acquires and releases the wake lock using PowerManager APIs for a specific use case, often this is acquired in conjunction with a Foreground Service – a platform lifecycle API intended for user-perceptible operation.

• Alternatively, the wake lock is acquired by another API, and attributed to the app due to usage of the API, more on this in the best practices section.

While wake locks are necessary for tasks like completing a user-initiated download of a large file, their excessive or improper use can lead to significant battery drain. We’ve seen cases where apps hold wake locks for hours or fail to release them properly, leading to user complaints about significant battery drain even when they’re not interacting with the app.

Best Practices for Wake Lock Usage

Before we go over how to debug excessive wake lock usage, ensure you’re following wake lock best practices. 

Consider these four critical questions.

1. Have you considered alternative wake lock options?

Before considering acquiring a manual partial wake lock, follow this decision-making flowchart:

Flowchart to decide when to manually acquire a wake lock

1. Does the screen need to stay on?

• Yes: Reference the Keep Screen On documentation instead

Is the application running a foreground service? 

• No: You don’t need to manually acquire a wake lock.

Is it detrimental to the user experience if the device suspends? 

• No: For instance, updating a notification after the device wakes up doesn’t require a wake lock. 

• Yes: If it’s critical to prevent the device from suspending, like ongoing communication with an external device, proceed.

Is there already an API keeping the device awake on your behalf?

• You can leverage the documentation Identify wake locks created by other APIs to identify scenarios where wake locks created by other APIs to identify scenarios where wake locks are created by other APIs such as LocationManager.

• If no APIs exist, proceed to the final question.

If you’ve answered all these questions and determined no alternative exists, you should proceed with manually acquiring a wake lock.

2. Are you naming the wake lock correctly?

When manually acquiring wake locks, proper naming is important for debugging:

• Leave out any Personally Identifiable Information (PII) in the name like email addresses. If PII is detected, the wake lock is logged as _UNKNOWN, hindering debugging.

• Don’t name your wake lock programmatically using class or method names, as these can be obfuscated by tools like Proguard. Instead, use a hard-coded string.

• Do not add counters or unique identifiers to wake lock tags. The same tag should be used every time the wake lock runs to allow the system to aggregate usage by name, making abnormal behavior easier to detect.

3. Is the acquired wake lock always released?

If you’re acquiring a wake lock manually, ensure the wake lock release always executes. Failing to release a wake lock can cause significant battery drain. 

For example, if an uncaught exception is thrown during processingWork(), the release() call might never happen. Instead, you can use a try-finally block to guarantee the wake lock is released, even if an exception occurs.

Additionally, you can add a timeout to the wake lock to ensure it releases after a specific period, preventing it from being held indefinitely.

fun processingWork() {
    wakeLock.apply {
        try {
            acquire(60 * 10 * 1000) // timeout after 10 minutes
            doTheWork()
        } finally {
            release()
        }
    }
}

4. Can you reduce the wake-up frequency?

For periodic data requests, reducing how often your app wakes up the device is key to battery optimization. Some examples of reducing wake-up frequency include:

• WorkManager: Increase the periodic interval in PeriodicWorkRequests.

• SensorManager: Leverage batching by specifying maxReportLatencyMs when registering the listener.

• Fused Location Provider: 

• Reduce location retrieval frequency by using getLastLocation for the most recent cached location. 

• Use setPriority(PRIORITY_PASSIVE) for a less battery-intensive update method. 

• Also, you can leverage the location batching mechanism by setting a minimum update interval with setMinUpdateIntervalMillis.

You can view more details in the wake lock best practices documentation.

Debugging excessive wake lock usage

Even with the best intentions, excessive wake lock usage can occur. If your app is flagged in the Play Console, here’s how to debug it:

Initial identification with Play Console

The Android vitals excessive partial wake lock dashboard provides breakdowns of non-exempted wake lock names associated with your app, showing affected sessions and durations. Reminder to use the documentation to help you identify if the wake lock name is app-held or held by another API.

The Android vitals excessive partial wake lock dashboard scrolled down to the breakdowns section to view excessive wake lock tags.

Debugging excessive wake locks held by workers/jobs

You can identify worker-held wake locks with this wake lock name:

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService

The full list of variations of worker-held wake lock names is available in documentation. To debug these wake locks, you can use Background Task Inspector to debug locally, or leverage getStopReason to debug issues in the field. 

Android Studio Background Task Inspector

Screen capture of the Background Task Inspector, where it has been able to identify a worker “WeatherSyncWorker” that has frequently retried and failed.

For local debugging of WorkManager issues, use this tool on an emulator or connected device (API level 26+). It shows a list of workers and their statuses (finished, executing, enqueued), allowing you to inspect details and understand worker chains. 

For instance, it can reveal if a worker is frequently failing or retrying due to hitting system limitations. 

See Background Task Inspector documentation for more details.

WorkManager getStopReason

For in-field debugging of workers with excessive wake locks, use WorkInfo.getStopReason() on WorkManager 2.9.0+ or for JobScheduler, JobParameters.getStopReason() available on SDK 31+. 

This API helps log the reason why a worker stopped (e.g., STOP_REASON_TIMEOUT, STOP_REASON_QUOTA), pinpointing issues like frequent timeouts due to exhausting runtime duration.

backgroundScope.launch {
    WorkManager.getInstance(context)
        .getWorkInfoByIdFlow(workRequest.id)
        .collect { workInfo ->
            logStopReason(workRequest.id, workInfo?.stopReason)
        }
}

See Optimize battery use for task scheduling APIs for more details.

Debugging other types of excessive wake locks

For more complex scenarios involving manually held wake locks or APIs holding the wake lock, we recommend you use system trace collection to debug.

System trace collection

A system trace is a powerful debugging tool that captures a detailed record of system activity over a period, providing insights into CPU state, thread activity, network activity, and battery-related metrics like job duration and wake lock usage.

You can capture a system trace using several methods: 

• Utilizing the system trace command line tool

• Using the Android Studio CPU Profiler

• Using the Perfetto UI

• Recording a trace manually on the device directly from the developer options. 

Enable “power:PowerManagement” Atrace category in the Perfetto UI under the Android apps & svcs tab. 

Regardless of the chosen method, it’s crucial to ensure that you are collecting the “power:PowerManagement” Atrace category to enable viewing of device state tracks. 

Perfetto UI inspection and SQL analysis

System traces can be opened and inspected in the Perfetto UI. When you open the trace, you will see a visualization of various processes on a timeline. The tracks we will be focused on in this guide are the ones under “Device State”.

Pin the tracks under “Device State” such as “Top app”, “Screen state”, “Long Wake locks”, and “Jobs” tracks to visually identify long-running wake lock slices.

Each block lists the name of the event, when the event started, and when it ended. In Perfetto, this is called a slice.

For scalable analysis of multiple traces, you can use Perfetto’s SQL analysis. A SQL query can find all wake locks sorted by duration, helping identify the top contributors to excessive usage.

Here’s an example query summing all the wake lock tags that occurred in the system trace, ordered by total duration:

SELECT slice.name as name, track.name as track_name,
SUM(dur / 100000) as total_dur_ms
FROM slice
JOIN track ON slice.track_id = track.id
WHERE track.name = 'WakeLocks'
GROUP BY slice.name, track.name
ORDER BY total_dur_ms DESC

Use ProfilingManager for in-field trace collection

For hard-to-reproduce issues, ProfilingManager (added in SDK 35) is a programmatic API that allows developers to collect system traces in the field with start and end triggers. It offers more control over the start and end trigger points for profile collection and enforces system-level rate limiting to prevent device performance impact. 

Check out the ProfilingManager documentation for further steps on how to implement in field system trace collection which include how to programmatically capture a trace, analyze profiling data, and use local debug commands.

The system traces collected using ProfilingManager will look similar to the ones collected manually, but system processes and other app processes are redacted from the trace.

Conclusion

The excessive partial wake lock metric in Android vitals is only a small part of our ongoing commitment to supporting developers in reducing battery drain and improving app quality. 

By understanding and properly implementing wake locks, you can significantly optimize your app’s battery performance. Leveraging alternative APIs, adhering to wake lock best practices, and using powerful debugging tools such as Background Task Inspector, system traces and ProfilingManager are key to ensuring your app’s success on Google Play.