Merge pull request #2918 from square/py/heap-dumps-in-no-backup-dir

Store heap dumps in the app's no backup directory

Author: pyricau

docs/changelog.md

@@ -19,6 +19,13 @@ Releases before 2.8.1 predate these markers.
 
 ## Unreleased
 
+* 🔀 [#2790](https://github.com/square/leakcanary/issues/2790) [#2719](https://github.com/square/leakcanary/issues/2719) [#2174](https://github.com/square/leakcanary/issues/2174) Heap dumps are now always stored in a `leakcanary` directory inside the app's [no backup directory](https://developer.android.com/reference/android/content/Context#getNoBackupFilesDir()), i.e. `/data/data/com.example/no_backup/leakcanary/`. They used to go to a `leakcanary-com.example` directory in the public `Download` folder, falling back to the app's cache directory when that wasn't writable, which in practice meant three different behaviors: on API 26 to 28 the destination depended on whether the app happened to hold `WRITE_EXTERNAL_STORAGE`, which LeakCanary declared but never requested; on API 29 scoped storage made the public directory unwritable and everything fell back to the cache directory; and from API 30 on, writing there needs no permission, so every heap dump went to `Download` and the fallback became unreachable. Storing heap dumps in public storage is what caused the failures above: a heap dump in `Download` belongs to the app in `MediaStore`, and clearing the app's data or reinstalling it clears that ownership while leaving the file on disk, after which the app can't read the file (the analysis fails with *"Hprof file missing"*), can't list it (so the `maxStoredHeapDumps` cleanup stops seeing it — one reporter accumulated 400+ heap dumps, about 40 GB) and can't delete it. None of that applies to app storage, which behaves the same way on every Android version.
+    * ⚠️ LeakCanary no longer declares the `READ_EXTERNAL_STORAGE` and `WRITE_EXTERNAL_STORAGE` permissions, so they disappear from the merged manifest of debug builds.
+    * ⚠️ `LeakCanary.Config.requestWriteExternalStoragePermission` and `LeakCanary.Config.Builder.requestWriteExternalStoragePermission()` are deprecated and do nothing. There's no external storage permission to request anymore.
+    * 🔀 Heap dumps taken by `leakcanary-android-test` and `leakcanary-android-instrumentation` move from the files directory of the app under test to its no backup directory, so they aren't backed up either. Heap dumps taken by `leakcanary-android-uiautomator` stay in `/data/local/tmp`: they're written by `am dumpheap` running as the shell user, which can't write to an app's private directory.
+    * 🔀 `adb pull /sdcard/Download/leakcanary-com.example/…` doesn't work anymore. Share the heap dump from the LeakCanary UI, or run `adb exec-out run-as com.example cat no_backup/leakcanary/<name>.hprof > dump.hprof`.
+    * 🔀 Heap dumps written by an earlier version of LeakCanary are left where they are. LeakCanary only cleans up the directory it writes to, and on API 30 and above it couldn't delete the ones it no longer owns anyway. Delete the `Download/leakcanary-com.example` directory by hand to reclaim that space.
+* ⚠️ The *"Render Heap Dump"* screen in the LeakCanary UI is gone, along with its *"Generate HQ Bitmap"* action. The action rendered the heap dump to a PNG in the public `Download` folder, gated on the `WRITE_EXTERNAL_STORAGE` permission — which apps targeting Android 11 and above can't be granted, so since 2020 tapping it only ever showed a toast asking for a permission that would have bought nothing.
 * 💥 [#2789](https://github.com/square/leakcanary/issues/2789) [#2773](https://github.com/square/leakcanary/issues/2773) The heap analysis of a large heap failed with an `OutOfMemoryError` while growing the set of objects the path finding traversal has already visited. That set was keyed by object id, so it held every reachable object in an 8 byte per slot hash table at a 0.75 load factor, sized from a guess (`instanceCount / 2`) that is always too small: on the Android heap dumps in our test resources the traversal ends up visiting 0.65x to 1.08x of `instanceCount`. Growing doubles the table and rehashes into it while the old one is still referenced, so the moment of growth needs 1.5x the new table — on a heap of 4 million objects, a 33.6 MB table and a 67.1 MB one live at the same time, in an app capped at a 512 MB growth limit. The visited set is now one bit per object in the heap dump, keyed by the object's index rather than by its id, allocated once at a size that's known upfront, so it can't grow and can't rehash: 509 KB rather than a 100.7 MB peak on that 4 million object heap. On a 4.4 million object Android heap dump, the smallest heap the analysis completes in goes from 513 MB to 385 MB.
     * 🔀 Mapping an object id to its index is a binary search where a hash lookup used to do, and the traversal does that once per reference it reads, so the analysis is about 2% slower end to end (4% to 8% of the path finding step) on the Android heap dumps in our test resources.
 * 💥 [#2773](https://github.com/square/leakcanary/issues/2773) The path finding traversal also kept a set of the object ids waiting in its queue, keyed by object id and therefore growing to the size of the traversal frontier — on a heap dump whose objects are reachable through a wide array, most of the heap. It turned out to be write-only: an object is added to exactly one of the two queues and removed from it when polled, so an object waiting in the low priority queue is never in the high priority queue as well, which is all the one read of that set was checking. Removing it takes the smallest heap the analysis of a 4.4 million object Android heap dump completes in from 385 MB to 321 MB, and makes path finding 2.6% to 4.3% faster, since maintaining the set cost a hash insert per reference enqueued and a hash removal per object visited.

docs/faq.md

@@ -37,8 +37,22 @@ D/LeakCanary: Updated LeakCanary.config: Config(dumpHeap=false)
 
 ## Where does LeakCanary store heap dumps?
 
-The default behavior is to store heap dumps in a `leakcanary` folder under the app directory. If the app has been granted the `android.permission.WRITE_EXTERNAL_STORAGE` permission, then heap dumps will be stored
-in a `leakcanary-com.example` folder (where `com.example` is your app package name) under the `Download` folder of the external storage. If the app has not been granted the `android.permission.WRITE_EXTERNAL_STORAGE` permission but that permission is listed in `AndroidManifest.xml` then LeakCanary will show a notification that can be tapped to grant permission.
+In a `leakcanary` folder inside the app's [no backup directory](https://developer.android.com/reference/android/content/Context#getNoBackupFilesDir()),
+i.e. `/data/data/com.example/no_backup/leakcanary/` where `com.example` is your app package name.
+That directory needs no permission on any Android version, and heap dumps stored there are excluded
+from Android Auto Backup, so they never count against the user's backup quota.
+
+LeakCanary keeps the [LeakCanary.Config.maxStoredHeapDumps](/leakcanary/api/leakcanary-android-core/leakcanary-android-core/leakcanary/-leak-canary/-config/max-stored-heap-dumps/)
+most recent heap dumps, 7 by default, and deletes the older ones.
+
+To pull a heap dump off the device, either share it from the LeakCanary UI (go to a heap analysis
+screen, click the overflow menu and select *Share Heap Dump*), or read it through the app's own
+user with `run-as`, which works because LeakCanary is a `debugImplementation` dependency and the app
+is therefore debuggable:
+
+```
+adb exec-out run-as com.example cat no_backup/leakcanary/2026-07-31_22-30-41_484.hprof > dump.hprof
+```
 
 ## How can I dig beyond the leak trace?
 

leakcanary/leakcanary-android-core/detekt-baseline.xml

@@ -2,7 +2,6 @@
 <SmellBaseline>
   <ManuallySuppressedIssues/>
   <CurrentIssues>
-    <ID>ChainWrapping:HeapDumpRenderer.kt$HeapDumpRenderer$&amp;&amp;</ID>
     <ID>ChainWrapping:LeakCanaryTextView.kt$LeakCanaryTextView$+</ID>
     <ID>ChainWrapping:SquigglySpanRenderer.kt$SquigglySpanRenderer.Companion$||</ID>
     <ID>FinalNewline:HeapAnalysisTable.kt$leakcanary.internal.activity.db.HeapAnalysisTable.kt</ID>
@@ -43,7 +42,6 @@
     <ID>NoConsecutiveBlankLines:InternalLeakCanary.kt$InternalLeakCanary$ </ID>
     <ID>NoConsecutiveBlankLines:LeakCanary.kt$LeakCanary.Config.Builder$ </ID>
     <ID>NoConsecutiveBlankLines:LeakCanaryAndroidInternalUtils.kt$ </ID>
-    <ID>NoConsecutiveBlankLines:RenderHeapDumpScreen.kt$ </ID>
     <ID>NoMultipleSpaces:LogcatEventListener.kt$LogcatEventListener$ </ID>
     <ID>NoMultipleSpaces:NotificationEventListener.kt$NotificationEventListener$ </ID>
     <ID>NoSemicolons:NotificationType.kt$NotificationType.LEAKCANARY_MAX$;</ID>

leakcanary/leakcanary-android-core/src/main/AndroidManifest.xml

@@ -17,10 +17,6 @@
 <manifest
     xmlns:android="http://schemas.android.com/apk/res/android">
 
-  <!-- To store the heap dumps and leak analysis results. -->
-  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
-  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
-
   <!-- To allow posting notifications on Android 13 -->
   <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
 
@@ -94,7 +90,7 @@
         android:name="leakcanary.internal.RequestPermissionActivity"
         android:excludeFromRecents="true"
         android:icon="@mipmap/leak_canary_icon"
-        android:label="@string/leak_canary_storage_permission_activity_label"
+        android:label="@string/leak_canary_permission_activity_label"
         android:taskAffinity="com.squareup.leakcanary.${applicationId}"
         android:theme="@style/leak_canary_Theme.Transparent"
         />

leakcanary/leakcanary-android-core/src/main/java/leakcanary/LeakCanary.kt

@@ -123,14 +123,12 @@ object LeakCanary {
     val maxStoredHeapDumps: Int = 7,
 
     /**
-     * LeakCanary always attempts to store heap dumps on the external storage if the
-     * WRITE_EXTERNAL_STORAGE is already granted, and otherwise uses the app storage.
-     * If the WRITE_EXTERNAL_STORAGE permission is not granted and
-     * [requestWriteExternalStoragePermission] is true, then LeakCanary will display a notification
-     * to ask for that permission.
-     *
-     * Defaults to false because that permission notification can be annoying.
+     * No longer does anything. LeakCanary used to store heap dumps in the public `Download`
+     * directory when the app held the `WRITE_EXTERNAL_STORAGE` permission, and would show a
+     * notification asking for that permission when this was true. Heap dumps are now always stored
+     * in the app's own storage, which needs no permission on any Android version.
      */
+    @Deprecated("LeakCanary no longer stores heap dumps on the external storage, so this does nothing.")
     val requestWriteExternalStoragePermission: Boolean = false,
 
     /**
@@ -241,6 +239,8 @@ object LeakCanary {
       private var metadataExtractor = config.metadataExtractor
       private var computeRetainedHeapSize = config.computeRetainedHeapSize
       private var maxStoredHeapDumps = config.maxStoredHeapDumps
+
+      @Suppress("DEPRECATION")
       private var requestWriteExternalStoragePermission =
         config.requestWriteExternalStoragePermission
       private var leakingObjectFinder = config.leakingObjectFinder
@@ -281,6 +281,7 @@ object LeakCanary {
         apply { this.maxStoredHeapDumps = maxStoredHeapDumps }
 
       /** @see [LeakCanary.Config.requestWriteExternalStoragePermission] */
+      @Deprecated("LeakCanary no longer stores heap dumps on the external storage, so this does nothing.")
       fun requestWriteExternalStoragePermission(requestWriteExternalStoragePermission: Boolean) =
         apply { this.requestWriteExternalStoragePermission = requestWriteExternalStoragePermission }
 
@@ -301,6 +302,7 @@ object LeakCanary {
         apply { this.showNotifications = showNotifications }
 
 
+      @Suppress("DEPRECATION")
       fun build() = config.copy(
         dumpHeap = dumpHeap,
         dumpHeapWhenDebugging = dumpHeapWhenDebugging,

leakcanary/leakcanary-android-core/src/main/java/leakcanary/internal/InternalLeakCanary.kt

@@ -66,11 +66,9 @@ internal object InternalLeakCanary : (Application) -> Unit, OnObjectRetainedList
 
   fun createLeakDirectoryProvider(context: Context): LeakDirectoryProvider {
     val appContext = context.applicationContext
-    return LeakDirectoryProvider(appContext, {
+    return LeakDirectoryProvider(appContext) {
       LeakCanary.config.maxStoredHeapDumps
-    }, {
-      LeakCanary.config.requestWriteExternalStoragePermission
-    })
+    }
   }
 
   internal enum class FormFactor {

leakcanary/leakcanary-android-core/src/main/java/leakcanary/internal/LeakCanaryFileProvider.kt

@@ -24,7 +24,6 @@ import android.content.pm.ProviderInfo
 import android.database.Cursor
 import android.database.MatrixCursor
 import android.net.Uri
-import android.os.Environment
 import android.os.ParcelFileDescriptor
 import android.os.StrictMode
 import android.provider.OpenableColumns
@@ -364,19 +363,11 @@ internal class LeakCanaryFileProvider : ContentProvider() {
 
     private const val META_DATA_FILE_PROVIDER_PATHS = "android.support.FILE_PROVIDER_PATHS"
 
-    private const val TAG_ROOT_PATH = "root-path"
-    private const val TAG_FILES_PATH = "files-path"
-    private const val TAG_CACHE_PATH = "cache-path"
-    private const val TAG_EXTERNAL = "external-path"
-    private const val TAG_EXTERNAL_FILES = "external-files-path"
-    private const val TAG_EXTERNAL_CACHE = "external-cache-path"
-    private const val TAG_EXTERNAL_MEDIA = "external-media-path"
+    private const val TAG_NO_BACKUP_FILES_PATH = "no-backup-files-path"
 
     private const val ATTR_NAME = "name"
     private const val ATTR_PATH = "path"
 
-    private val DEVICE_ROOT = File("/")
-
     private val sCache = HashMap<String, PathStrategy>()
 
     /**
@@ -479,52 +470,17 @@ internal class LeakCanaryFileProvider : ContentProvider() {
           val name = resourceParser.getAttributeValue(null, ATTR_NAME)
           val path = resourceParser.getAttributeValue(null, ATTR_PATH)
 
-          var target: File? = null
-          if (TAG_ROOT_PATH == tag) {
-            target = DEVICE_ROOT
-          } else if (TAG_FILES_PATH == tag) {
-            target = context.filesDir
-          } else if (TAG_CACHE_PATH == tag) {
-            target = context.cacheDir
-          } else if (TAG_EXTERNAL == tag) {
-            target = Environment.getExternalStorageDirectory()
-          } else if (TAG_EXTERNAL_FILES == tag) {
-            val externalFilesDirs = getExternalFilesDirs(context, null)
-            if (externalFilesDirs.isNotEmpty()) {
-              target = externalFilesDirs[0]
-            }
-          } else if (TAG_EXTERNAL_CACHE == tag) {
-            val externalCacheDirs = getExternalCacheDirs(context)
-            if (externalCacheDirs.isNotEmpty()) {
-              target = externalCacheDirs[0]
-            }
-          } else if (TAG_EXTERNAL_MEDIA == tag) {
-            val externalMediaDirs = context.externalMediaDirs
-            if (externalMediaDirs.isNotEmpty()) {
-              target = externalMediaDirs[0]
-            }
-          }
-
-          if (target != null) {
-            strat.addRoot(name, buildPath(target, path))
+          // LeakCanary only ever shares files it wrote to its own no backup directory, so that's
+          // the only root this provider knows how to resolve.
+          if (TAG_NO_BACKUP_FILES_PATH == tag) {
+            strat.addRoot(name, buildPath(context.noBackupFilesDir, path))
           }
         }
       }
 
       return strat
     }
 
-    private fun getExternalFilesDirs(
-      context: Context,
-      type: String?
-    ): Array<File> {
-      return context.getExternalFilesDirs(type)
-    }
-
-    private fun getExternalCacheDirs(context: Context): Array<File> {
-      return context.externalCacheDirs
-    }
-
     /**
      * Copied from ContentResolver.java
      */