Identify wake locks created by other APIs

Several libraries and system APIs can acquire wake locks that are attributable to your app. This can make it difficult to identify a wake lock in your app that might be causing a problem. If you misuse an API, that might result in your app holding a wake lock for too long, even though you aren't calling the wake lock APIs directly.

This document lists some common wake lock names you might see when you use the wake lock debugging tools. You might also see these names in a report from Android vitals. In some cases, the wake lock might have been created by a library or system API. In other cases, there is a reason why the tool is obfuscating the wake lock name you use in the app. You can use the debugging tools to identify misbehaving wake locks, then look the wake lock name up in this document to identify which API may be causing the problem and how to solve it.

This document covers the following wake lock names. In each case, while the wake lock might be created by some other library or API, the lock is attributed to the app which called that API.

*alarm*

This wake lock is acquired by AlarmManager and attributed to the calling app. AlarmManager acquires the wake lock when the alarm goes off, and releases the lock when the alarm broadcast's onReceive() method finishes executing.

Recommendation

We recommend the following practices to optimize alarm behavior:

  • Use AlarmManager to optimize alarm scheduling frequency.
  • Only use RTC_WAKEUP alarms (which wake up the device) when necessary.
  • Minimize the use of alarms, and avoid doing lengthy work in the onReceive() method.

AudioIn, AudioMix, etc.

Various wake locks whose names begin with Audio are acquired by media APIs when recording or playing audio. The wake locks are attributed to the calling app.

AudioIn is acquired during AudioRecord capture in camcorder mode, while the microphone is active. AudioMix is acquired during AudioTrack playback to the device. Other media APIs may acquire wake locks with other names beginning with Audio.

Recommendation

We recommend the following practices:

  • Don't use wake lock names that begin with Audio.
  • If you're using the media APIs, you shouldn't need to acquire wake locks directly; you can rely on the APIs to acquire the necessary wake locks for you.
  • When you use media APIs, end the media session when you no longer need it.

GOOGLE_C2DM

This wake lock is acquired by GCM while delivering a Firebase Cloud Message (FCM) broadcast to the app. The wake lock is released once the FCM broadcast onMessageReceived() method finishes executing.

Recommendation

We recommend the following practices to optimize FCM behavior:

  • Optimize the frequency of FCM delivery.
  • Don't use high-priority FCM unless the message actually needs to be delivered immediately.
  • Have the onMessageReceived() method complete as quickly as possible. See the firebase guidance for more information.

*job*/<package_name>/<package_and_job_name>

These wake locks are used by JobScheduler jobs while executing tasks in the background. The wake locks are attributed to the app that created the workers.

"<package_name>" is the name of your app's package, not the literal text <package name>. Similarly, "<package_and_job_name>" is the package name followed by the job name. *job* is the character sequence *job*, with asterisks; the asterisks are not being used as wild cards. Here's an example of such a wake lock name:

*job*/com.example.app/com.example.app.example.path.ExampleJobService

Recommendation

Audit your usage of JobScheduler tasks. In particular, follow our guidance for optimizing battery use for task scheduling APIs.

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

These wake locks are used by WorkManager workers while executing tasks in the background. The wake locks are attributed to the app that created the workers.

"<package_name>" is the name of your app's package, not the literal text <package name>. *job* is the character sequence *job*, with asterisks; the asterisks are not being used as wild cards.

Recommendation

Audit your usage of WorkManager workers. In particular, follow our guidance for optimizing battery use for task scheduling APIs.

NetworkLocationLocator, FusedLocation, *location*

These wake lock names are used by LocationManager and FusedLocationProviderClient to acquire and deliver the device location. The wake locks are attributed to the app that called those APIs.

Recommendation

Optimize location use. For example, set timeouts, batch location requests, or use passive location updates.

_UNKNOWN

If the debugging tools think a wake lock name contains personally identifiable information (PII), they don't display the actual wake lock name. Instead, they label the wake lock as _UNKNOWN. For example, tools might do this if the wake lock name contains an email address.

Recommendation

Follow wake lock naming best practices, and avoid using PII in the wake lock name. If you find a wake lock named _UNKNOWN attributed to your app, try to identify which wake lock that is, and give it a different name.