LeakCanary

https://github.com/square/leakcanary
Admin
LeakCanary is a memory leak detection library for Android that helps developers identify and fix...
Tokens:392,369
Snippets:2,471
Trust Score:9.4
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Basic test rule chain with DetectLeaksAfterTestSuccess

Source: https://github.com/square/leakcanary/blob/main/docs/ui-tests.md

Shows a basic RuleChain setup with LoginRule, ActivityScenarioRule, and LoadingScreenRule. This is the starting point for the examples that follow.

```kotlin
// Example test rule chain
@get:Rule
val rule = RuleChain.outerRule(LoginRule())
  .around(ActivityScenarioRule(CartActivity::class.java))
  .around(LoadingScreenRule())

```

--------------------------------

### Start harness for end-to-end investigation

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/shark-dive-agent/AGENTS.md

Starts the harness with a heap dump file. It builds the packaged app, copies it, and starts an agent. Use --print-command to stage everything and print the command instead.

```bash
shark/shark-dive/shark-dive-agent/harness/start-harness.sh [heap-dump.hprof]
```

--------------------------------

### Install docs dependencies and serve locally

Source: https://github.com/square/leakcanary/blob/main/docs/dev-env.md

Installs or updates the docs dependencies and then serves the documentation locally with mkdocs serve.

```bash
pip install --requirement docs/requirements.txt
```

```bash
mkdocs serve
```

--------------------------------

### Install GitHub CLI and jq

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Install the required tools for running a release: GitHub CLI and jq.

```bash
brew install gh jq
```

--------------------------------

### Install Shark CLI with Homebrew

Source: https://github.com/square/leakcanary/blob/main/docs/shark.md

Installs the Shark CLI via Homebrew. Requires Homebrew to be installed on your system.

```bash
brew install leakcanary-shark
```

--------------------------------

### Set up documentation toolchain

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Create a Python virtual environment and install the documentation requirements.

```bash
python3 -m venv venv
source venv/bin/activate
pip3 install --requirement docs/requirements.txt
```

--------------------------------

### Install shark-dive skill to user directory

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/notes/agent-surface.md

Copies the project skill directory into the user-level skills directory so agents on machines without this repository can load it. This is the install step documented in docs/shark-dive.md and should be carried as a release asset.

```bash
cp -R .claude/skills/shark-dive ~/.claude/skills/
```

--------------------------------

### Run list_heap_dumps via CLI and observe the protocol trace

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/notes/agent-surface.md

Shows the CLI invocation and the resulting six-line protocol trace. The first line is not JSON: it is `token[ sessionName]` answered `OK` or `NO`; `flowtrace` is the session these calls join, and a connection that names none gets its own. The trace shows one request line and exactly one response line, with `->` as the caller talking and `<-` as the run; timings are from the start of the trace and exclude JVM startup.

```bash
"Shark Dive.app/Contents/MacOS/Shark Dive" --cli list_heap_dumps \
  --session=flowtrace reason="Finding out what is already open"
```

```text
0.015 c1 -- connected
0.015 c1 -> 43e96b32f6462fd2b3669cf7c6ee36b0 flowtrace
0.015 c1 <- OK
0.015 c1 -> {"tool":"list_heap_dumps","arguments":{"reason":"Finding out what is already open"}}
0.019 c1 <- {"answer":{"heapDumps":[{"heapDumpKey":"leak_asynctask_o.hprof","heapDumpPath":"/…/leak_asynctask_o.hprof","sizes":{…},"verdictsSetByHand":[],"placesWithANote":0}]}}
0.019 c1 -- closed
```

--------------------------------

### Custom LiveHeapGrowthDetector setup for in-process Espresso tests

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

This setup creates a LiveHeapGrowthDetector for in-process Espresso UI tests. It configures reference matchers, a heap graph provider that dumps the heap to a file, and a looping detector with a maximum of 5 heap dumps and 5 scenario loops per dump. The heap dump file is deleted after analysis.

```kotlin
import leakcanary.AndroidDebugHeapDumper
import shark.AndroidReferenceMatchers
import shark.AndroidReferenceReaderFactory
import shark.CloseableHeapGraph
import shark.DiffingHeapGrowthDetector
import shark.HeapGraphProvider
import shark.HeapTraversal
import shark.HprofHeapGraph.Companion.openHeapGraph
import shark.IgnoredReferenceMatcher
import shark.LiveHeapGrowthDetector
import shark.LoopingHeapGrowthDetector
import shark.MatchingGcRootProvider
import shark.ReferencePattern.InstanceFieldPattern
import java.io.File
import java.text.SimpleDateFormat
import java.util.Date
import java.util.Locale

/**
 * Heap growth detector for in process Espresso UI tests.
 *
 * Call [LiveHeapGrowthDetector.detectRepeatedHeapGrowth] with a scenario to repeat,
 * then assert that the resulting [shark.HeapTraversalWithDiff.growingNodes] is empty.
 */
val HeapGrowthDetector by lazy {
  val referenceMatchers = AndroidReferenceMatchers.appDefaults +
    HeapTraversal.ignoredReferences +
    // https://cs.android.com/android/_/android/platform/frameworks/base/+/6985fb39f07294fb979b14ba0ebabfd2fea06d34
    IgnoredReferenceMatcher(InstanceFieldPattern("android.os.StrictMode", "sLastVmViolationTime"))

  val dateFormat = SimpleDateFormat("yyyy-MM-dd_HH-mm-ss_SSS'-heap-growth.hprof'", Locale.US)
  val uploadedTracesDirectory = File("/sdcard/traces/")
  uploadedTracesDirectory.mkdirs()
  check(uploadedTracesDirectory.exists()) {
    "Expected heap dump folder to exist: ${uploadedTracesDirectory.absolutePath}"
  }

  val heapGraphProvider = HeapGraphProvider {
    val fileName = dateFormat.format(Date())
    val heapDumpFile = File(uploadedTracesDirectory, fileName)
    AndroidDebugHeapDumper.dumpHeap(heapDumpFile)
    check(heapDumpFile.exists()) {
      "Expected file to exist after heap dump: ${heapDumpFile.absolutePath}"
    }
    val realGraph = heapDumpFile.openHeapGraph()
    object : CloseableHeapGraph by realGraph {
      override fun close() {
        realGraph.close()
        heapDumpFile.delete()
      }
    }
  }

  LiveHeapGrowthDetector(
    maxHeapDumps = 5,
    heapGraphProvider = heapGraphProvider,
    scenarioLoopsPerDump = 5,
    detector = LoopingHeapGrowthDetector(
      DiffingHeapGrowthDetector(
        referenceReaderFactory = AndroidReferenceReaderFactory(referenceMatchers),
        gcRootProvider = MatchingGcRootProvider(referenceMatchers)
      )
    )
  )
}
```

--------------------------------

### Changelog anchor link example

Source: https://github.com/square/leakcanary/wiki/Making-a-new-LeakCanary-release

Example of a changelog anchor link to include in the release description.

```markdown
See [Change Log](https://square.github.io/leakcanary/changelog#version-20-alpha-2-2019-05-21)
```

--------------------------------

### Run heap analysis in release builds with triggers and Firebase flag

Source: https://github.com/square/leakcanary/blob/main/docs/leakcanary-for-releases.md

Example application that starts heap analysis when the app enters background or screen turns off, checks a Firebase Remote Config flag to cancel analysis, and uploads results to Bugsnag. Uses private app storage and strips heap dump to remove user data.

```kotlin
import android.os.Process.THREAD_PRIORITY_BACKGROUND
import java.util.concurrent.Executors
import kotlin.concurrent.thread
import leakcanary.BackgroundTrigger
import leakcanary.HeapAnalysisClient
import leakcanary.HeapAnalysisConfig
import leakcanary.HeapAnalysisInterceptor
import leakcanary.HeapAnalysisInterceptor.Chain
import leakcanary.HeapAnalysisJob
import leakcanary.HeapAnalysisJob.Result.Done
import leakcanary.ScreenOffTrigger

class ReleaseExampleApplication : ExampleApplication() {

  override fun onCreate() {
    super.onCreate()

    // Delete any remaining heap dump (if we crashed)
    analysisExecutor.execute {
      analysisClient.deleteHeapDumpFiles()
    }

    // Starts heap analysis on background importance
    BackgroundTrigger(
      application = this,
      analysisClient = analysisClient,
      analysisExecutor = analysisExecutor,
      analysisCallback = analysisCallback
    ).start()

    // Starts heap analysis when screen off
    ScreenOffTrigger(
      application = this,
      analysisClient = analysisClient,
      analysisExecutor = analysisExecutor,
      analysisCallback = analysisCallback
    ).start()
  }

  /**
   * Call this to trigger heap analysis manually, e.g. from
   * a help button.
   *
   * This method returns a `HeapAnalysisJob` on which you can
   * call `HeapAnalysisJob.cancel()` at any time.
   */
  fun triggerHeapAnalysisNow(): HeapAnalysisJob {
    val job = analysisClient.newJob()
    analysisExecutor.execute {
      val result = job.execute()
      analysisCallback(result)
    }
    return job
  }

  private val analysisClient by lazy {
    HeapAnalysisClient(
      // Use private app storage. cacheDir is never backed up which is important.
      heapDumpDirectoryProvider = { cacheDir },
      // stripHeapDump: remove all user data from hprof before analysis.
      config = HeapAnalysisConfig(stripHeapDump = true),
      // Default interceptors may cancel analysis for several other reasons.
      interceptors = listOf(flagInterceptor) + HeapAnalysisClient.defaultInterceptors(this)
    )
  }

  // Cancels heap analysis if "heap_analysis_flag" is false.
  private val flagInterceptor = object : HeapAnalysisInterceptor {
    val remoteConfig by lazy { FirebaseRemoteConfig.getInstance() }

    override fun intercept(chain: Chain): HeapAnalysisJob.Result {
      if (remoteConfig.getBoolean("heap_analysis_flag")) {
        chain.job.cancel("heap_analysis_flag false")
      }
      return chain.proceed()
    }
  }

  private val analysisExecutor = Executors.newSingleThreadExecutor {
    thread(start = false, name = "Heap analysis executor") {
      android.os.Process.setThreadPriority(THREAD_PRIORITY_BACKGROUND)
      it.run()
    }
  }

  private val analysisCallback: (HeapAnalysisJob.Result) -> Unit = { result ->
    if (result is Done) {
      uploader.upload(result.analysis)
    }
  }

  private val uploader by lazy {
    BugsnagLeakUploader(this@ReleaseExampleApplication)
  }
}
```

--------------------------------

### Verify LeakCanary startup via Logcat

Source: https://github.com/square/leakcanary/blob/main/docs/faq.md

Filters Logcat for the LeakCanary tag to confirm that LeakCanary starts correctly. The expected output shows the 'Installing AppWatcher' message. If this message is not present, check dependencies with './gradlew app:dependencies'.

```bash
$ adb logcat | grep LeakCanary

D/LeakCanary: Installing AppWatcher
```

--------------------------------

### Install leakcanary-android-sample on emulator

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/AGENTS.md

Install the leakcanary-android-sample app on an emulator so device-reaching commands (heap dumps, bitmap fetches) can be tried for real. An emulator older than API 35 exercises shark-dive-jdwp.

```bash
ANDROID_SERIAL=emulator-5554 ./gradlew :samples:leakcanary-android-sample:installDebug
```

--------------------------------

### Customize Watchers with AppWatcher.manualInstall()

Source: https://github.com/square/leakcanary/blob/main/docs/recipes.md

Install custom watchers at runtime by filtering out FragmentAndViewModelWatcher from the default watchers. Use this to control which retained object types are detected.

```kotlin
val watchersToInstall = AppWatcher.appDefaultWatchers(this)
  .filter { it !is FragmentAndViewModelWatcher }
AppWatcher.manualInstall(
  application = this,
  watchersToInstall = watchersToInstall
)
```

--------------------------------

### Before: Default setup code in Application class

Source: https://github.com/square/leakcanary/blob/main/docs/upgrading-to-leakcanary-2.0.md

The old default setup code in an Application class, checking for the analyzer process and calling LeakCanary.install(). This is no longer needed in LeakCanary 2.0.

```java
public class ExampleApplication extends Application {

  @Override public void onCreate() {
    super.onCreate();
    if (LeakCanary.isInAnalyzerProcess(this)) {
      // This process is dedicated to LeakCanary for heap analysis.
      // You should not init your app in this process.
      return;
    }
    LeakCanary.install(this);
    // Normal app init code...
  }
}
```

--------------------------------

### Shark CLI heap-growth command with output

Source: https://github.com/square/leakcanary/blob/main/docs/heap-growth.md

This example shows the shark-cli heap-growth command that analyzes a directory of heap dumps in name order. The output includes the list of heap dumps analyzed and the growth detection results, including the growing nodes and retained sizes.

```text
$ shark-cli --hprof heap_dumps_object_growth heap-growth --loops 2
Detecting heap growth by going analyzing the following heap dumps in this order:
2026-07-29_21-31-33_894_CartTest-adding_item_to_cart_does_not_grow_heap.hprof
2026-07-29_21-31-39_046_CartTest-adding_item_to_cart_does_not_grow_heap.hprof
2026-07-29_21-31-45_149_CartTest-adding_item_to_cart_does_not_grow_heap.hprof
2026-07-29_21-31-51_126_CartTest-adding_item_to_cart_does_not_grow_heap.hprof
2026-07-29_21-31-57_063_CartTest-adding_item_to_cart_does_not_grow_heap.hprof
Results: HeapGrowthTraversal(traversal=5, isGrowing=true, scenarioLoopsPerGraph=2, growingNodes=

┬───
│ GcRoot(ThreadObject) (14 objects)
│ 
├─LOCAL Instrumentation$InstrumentationThread. -> instance of com.example.cart.CartTest (1 objects)
│ 
├─INSTANCE_FIELD CartTest.cart -> instance of com.example.cart.Cart (1 objects)
│ 
╰→INSTANCE_FIELD Cart.itemsById -> instance of java.util.LinkedHashMap (1 objects)
    Retained size: 777 B (+ 132 B)
    Retained objects: 32 (+ 6)
    Children:
    10 objects (2 new): ARRAY_ENTRY LinkedHashMap.[x] -> instance of java.lang.String
    10 objects (2 new): ARRAY_ENTRY LinkedHashMap.[x] -> instance of com.example.cart.Item

)
Found 1 growing objects
```

--------------------------------

### Install default watchers except ServiceWatcher

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Manually installs LeakCanary watchers, excluding `ServiceWatcher` from the default set. Use this after disabling automatic installation.

```kotlin
class DebugExampleApplication : ExampleApplication() {

  override fun onCreate() {
    super.onCreate()

    val watchersToInstall = AppWatcher.appDefaultWatchers(application)
      .filter { it !is ServiceWatcher }

    AppWatcher.manualInstall(
      application = application,
      watchersToInstall = watchersToInstall
    )
  }
}
```

--------------------------------

### Run Shark Dive headless with --no-ui and list leak groups

Source: https://github.com/square/leakcanary/blob/main/docs/shark-dive.md

Starts a headless Shark Dive run with --no-ui, then lists leak groups from the opened dump. The first command opens the dump without drawing a window; the second reuses the same heapDumpKey. --no-ui is only valid for commands that start a run, and show is refused because there is no UI to display tabs.

```bash
"/Applications/Shark Dive.app/Contents/MacOS/Shark Dive" --cli open_heap_dump --no-ui \
  path=/var/dumps/bug-4821.hprof reason="No display on this machine"
"/Applications/Shark Dive.app/Contents/MacOS/Shark Dive" \
  --cli list_leak_groups heapDumpKey=bug-4821.hprof reason="Starting from what the dump says about itself"
```

--------------------------------

### Install Shark CLI and deobfuscate hprof

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Commands to install the Shark CLI via Homebrew and deobfuscate a heap dump using a mapping file. The deobfuscate-hprof command requires the hprof file and mapping file.

```bash
brew install leakcanary-shark

shark-cli --hprof heapdump.hprof -m mapping.txt deobfuscate-hprof
```

--------------------------------

### Build and test a shark:// link with createDistributable

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/AGENTS.md

Builds a distributable Shark Dive app, copies it to ~/Applications, re-registers it with LaunchServices, launches it with a debug title prefix, and opens a shark:// link. Use this loop to test deep links from a run started from Gradle, since runNamed processes are not reachable by links.

```bash
./gradlew :shark:shark-dive:shark-dive-app:createDistributable
cp -R "shark/shark-dive/shark-dive-app/build/compose/binaries/main/app/Shark Dive.app" \
  ~/Applications/
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
  -f ~/Applications/"Shark Dive.app"
open -a ~/Applications/"Shark Dive.app" --args --debug-title-prefix="Links" path/to/dump.hprof
open "shark://dump.hprof/leaks"
```

--------------------------------

### Open heap dump and list leak groups via CLI

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/shark-dive-agent/AGENTS.md

Commands to open a heap dump and list leak groups, each with a reason parameter. These start a run if none is up.

```bash
"Shark Dive.app/Contents/MacOS/Shark Dive" \
  --cli open_heap_dump path=<path> reason="Trying it"
"Shark Dive.app/Contents/MacOS/Shark Dive" \
  --cli list_leak_groups heapDumpKey=<file name> reason="Trying it"
```

--------------------------------

### Merge release branch and bump to snapshot

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Merge the release branch back to main and start the next development iteration with a -SNAPSHOT version.

```bash
git checkout main && git pull && \
git merge --no-ff --no-edit release_$NEW_VERSION && \
sed -i '' "s/VERSION_NAME=.*/VERSION_NAME=$NEXT_VERSION-SNAPSHOT/" gradle.properties && \
git commit -am "Prepare for next development iteration" && \
git push
```

--------------------------------

### Promote Shark Dive release with gh workflow run

Source: https://github.com/square/leakcanary/blob/main/docs/releasing-shark-dive.md

Triggers the promote-shark-dive.yml workflow to write the latest.properties asset for the rolling shark-dive-latest release. Run this only after installing the release and opening a heap dump with it, so a broken release is not offered to anyone.

```bash
gh workflow run promote-shark-dive.yml -f version=$NEW_VERSION
```

--------------------------------

### Example heap analysis output from assertNoLeaks (text)

Source: https://github.com/square/leakcanary/blob/main/docs/ui-tests.md

Shows the failure output when application leaks are detected. The output includes the heap analysis result and the stack trace pointing to the test method.

```text
leakcanary.NoLeakAssertionFailedError: Application memory leaks were detected:
====================================
HEAP ANALYSIS RESULT
====================================
1 APPLICATION LEAKS

┬───
│ GC Root: System class
│
├─ com.example.MySingleton class
│    Verdict: Expected (a class is always expected)
│    ↓ static MySingleton.leakedView
│                         ~~~~~~~~~~
├─ android.widget.TextView instance
│    Verdict: Stuck (View.mContext references a destroyed activity)
│    ↓ TextView.mContext
╰→ com.example.MainActivity instance
     Verdict: Stuck (Activity#mDestroyed is true)
====================================
  at leakcanary.AndroidDetectLeaksAssert.assertNoLeaks(AndroidDetectLeaksAssert.kt:34)
  at leakcanary.LeakAssertions.assertNoLeaks(LeakAssertions.kt:21)
  at com.example.CartTest.addItemToCart(TuPeuxPasTest.kt:41)
```

--------------------------------

### Configure event listener in main process

Source: https://github.com/square/leakcanary/blob/main/docs/recipes.md

Kotlin example showing how to configure a custom event listener in the main process. It checks if the app is running in the analyzer process and returns early if so, then adds an event listener that uploads the heap analysis result.

```kotlin
class DebugExampleApplication : ExampleApplication() {

  override fun onCreate() {
    super.onCreate()
    if (LeakCanaryProcess.isInAnalyzerProcess(this)) {
      return
    }
    LeakCanary.config = LeakCanary.config.run {
      copy(eventListeners = eventListeners + EventListener { event ->
        if (event is HeapAnalysisDone<*>) {
          uploadToMyBackend(event.heapAnalysis)
        }
      })
    }
  }
}
```

--------------------------------

### Create synthetic heap dump with dump DSL

Source: https://github.com/square/leakcanary/blob/main/docs/dev-env.md

Creates a synthetic heap dump for testing heap analysis without committing binary .hprof files. Requires testImplementation(projects.shark.sharkHprofTest). See VerdictTest or AndroidObjectInspectorsTest for examples.

```kotlin
val heapDump = dump {
  "com.example.MyClass" watchedInstance {
    field["fieldName"] = BooleanHolder(true)
  }
}
```

--------------------------------

### Skip initialization in analyzer process

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Skip initialization code in the Application class when running in the analyzer process. This is required for the multi-process setup; event listeners related to analysis will fire in the remote process.

```kotlin
class ExampleApplication : Application() {

  override fun onCreate() {
    if (LeakCanaryProcess.isInAnalyzerProcess(this)) {
      return
    }
    super.onCreate()
    // normal init goes here, skipped in :leakcanary process.
  }
}
```

--------------------------------

### Heap analysis metadata output with assertionTag

Source: https://github.com/square/leakcanary/blob/main/docs/ui-tests.md

Example output of heap analysis metadata showing the assertionTag field. Tags are reported in the metadata and can be retrieved via HeapAnalysisSuccess.assertionTag.

```text
====================================
METADATA

Please include this in bug reports and Stack Overflow questions.

Build.VERSION.SDK_INT: 23
...
assertionTag: Second Assertion
```

--------------------------------

### Add EventListener to upload heap analysis

Source: https://github.com/square/leakcanary/blob/main/docs/uploading.md

Shows how to add an EventListener that triggers when heap analysis succeeds, allowing you to upload the HeapAnalysis to a server. The example uses LeakCanary.config.copy to add the listener.

```kotlin
class DebugExampleApplication : ExampleApplication() {

  override fun onCreate() {
    super.onCreate()
    val analysisUploadListener = EventListener { event ->
      if (event is HeapAnalysisSucceeded) {
        val heapAnalysis = event.heapAnalysis
        TODO("Upload heap analysis to server")
      }
    }

    LeakCanary.config = LeakCanary.config.run {
      copy(eventListeners = eventListeners + analysisUploadListener)
    }
  }
}
```

--------------------------------

### Run Shark Dive with runNamed and a debug title prefix

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/AGENTS.md

Launches the Shark Dive app via the runNamed task, which wraps the run task in a bundle named after the --debug-title-prefix value. The dock reads the bundle's file name, so this is the way to get a distinct dock tile. The command also passes the HPROF file to analyze.

```bash
./gradlew :shark:shark-dive:shark-dive-app:runNamed \
  --args="--debug-title-prefix=\"Hover previews\" shark/shark-android/src/test/resources/compose_leak.hprof"
```

--------------------------------

### Leak trace for Helper singleton

Source: https://github.com/square/leakcanary/blob/main/docs/fundamentals-fixing-a-memory-leak.md

Example leak trace showing the strong reference path from a GC root to the leaking Helper instance. The trace indicates a local variable in native code as the GC root, followed by a PathClassLoader, an Object array, the Utils class, and finally the Helper instance.

```text
┬───
│ GC Root: Local variable in native code
│
├─ dalvik.system.PathClassLoader instance
│    ↓ PathClassLoader.runtimeInternalObjects
├─ java.lang.Object[] array
│    ↓ Object[].[43]
├─ com.example.Utils class
│    ↓ static Utils.helper
╰→ java.example.Helper
```

--------------------------------

### Install the shark-dive skill for Claude Code

Source: https://github.com/square/leakcanary/blob/main/docs/shark-dive.md

Clones the LeakCanary repository and copies the shark-dive skill into the user's Claude skills directory. This makes the skill available to Claude Code, Codex, Cursor, and Gemini CLI, so an agent can be prompted to investigate a heap dump.

```bash
git clone git@github.com:square/leakcanary.git
cp -R leakcanary/.claude/skills/shark-dive ~/.claude/skills/
```

--------------------------------

### Count retained objects with AppWatcher.objectWatcher

Source: https://github.com/square/leakcanary/blob/main/docs/upgrading-to-leakcanary-2.0.md

Use this to get the number of retained objects, for example to add metadata to OutOfMemoryError crashes. Requires the object-watcher-android artifact on release builds.

```kotlin
val retainedObjectCount = AppWatcher.objectWatcher.retainedObjectCount
```

--------------------------------

### Espresso heap growth test with HeapDiff.repeatingAndroidInProcessScenario

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Setup for the Espresso heap growth test: add the leakcanary-android-test dependency, enable largeHeap in the app under test's manifest (required for in-process analysis), and use HeapDiff.repeatingAndroidInProcessScenario() to detect growing objects.

```groovy
dependencies {
  androidTestImplementation 'com.squareup.leakcanary:leakcanary-android-test:3.0-alpha-7'
}
```

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android">

  <!-- Performing the heap growth analysis in process requires more heap. This has to be the
       manifest of the app under test: an instrumentation process is created from the
       ApplicationInfo of the app under test, so largeHeap in src/androidTest/AndroidManifest.xml,
       which ends up in the manifest of the test apk, has no effect. -->
  <application
      android:largeHeap="true"/>
</manifest>
```

```kotlin
class MyEspressoTest {
  val detector = HeapDiff.repeatingAndroidInProcessScenario()

  @Test
  fun greeter_says_hello_does_not_grow_heap() {
    // Runs repeatedly until the heap stops growing or we reach max heap dumps.
    val heapDiff = detector.findRepeatedlyGrowingObjects {
      onView(withId(R.id.name_field)).perform(typeText("Steve"))
      onView(withId(R.id.greet_button)).perform(click())
      onView(withText("Hello Steve!")).check(matches(isDisplayed()))
    }

    assertThat(heapDiff.growingObjects).isEmpty()
  }
}
```

--------------------------------

### Generate API docs and deploy site

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Generate the API docs and deploy the documentation site. Preview locally with mkdocs serve if desired.

```bash
rm -rf docs/api && ./gradlew siteDokka && \
source venv/bin/activate && \
mkdocs gh-deploy
```

--------------------------------

### Run shark-dive.sh with --help and --cli

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/AGENTS.md

Run the Shark Dive command-line tool from the repo root. The first command prints help; the second sends a command to a running Shark Dive instance over a loopback socket, filtered by build sha.

```bash
./shark-dive.sh --help
./shark-dive.sh --cli list_heap_dumps reason="what is open"
```

--------------------------------

### Disable automatic watcher installation with leak_canary_watcher_auto_install

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Disables the automatic installation of LeakCanary watchers by setting the resource `leak_canary_watcher_auto_install` to false. This is required before manually installing watchers.

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
  <bool name="leak_canary_watcher_auto_install">false</bool>
</resources>
```

--------------------------------

### Build shark-cli and create GitHub release

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Build the shark-cli distribution and create the GitHub release. Must be done while VERSION_NAME is still the release version.

```bash
./gradlew shark:shark-cli:distZip && \
gh release create v$NEW_VERSION ./shark/shark-cli/build/distributions/shark-cli-$NEW_VERSION.zip --title v$NEW_VERSION --notes 'See [Change Log](https://square.github.io/leakcanary/changelog)'
```

--------------------------------

### Run Shark CLI heap-growth command

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Run the heap-growth command from the Shark CLI zip (alphas cannot be released to brew). Replace the package name with your app's debug package.

```bash
$ ~/Downloads/shark-cli-3.0-alpha-7/bin/shark-cli -p com.example.app.debug heap-growth
```

--------------------------------

### DetectLeaksAfterTestSuccess test rule example

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Example of using the DetectLeaksAfterTestSuccess test rule and the @SkipLeakDetection annotation in an instrumentation test. Requires setting up the TestDescriptionHolder rule.

```kotlin
class CartTest {
  @get:Rule
  val rules = RuleChain.outerRule(TestDescriptionHolder)
    .around(DetectLeaksAfterTestSuccess())
    .around(ActivityScenarioRule(CartActivity::class.java))

  @Test
  fun addItemToCart() {
    // ...
  }

  @SkipLeakDetection("See #1234")
  @Test
  fun removeItemFromCart() {
    // ...
  }
}
```

--------------------------------

### Infinite ObjectAnimator leak example

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Example of an infinite ObjectAnimator that is never cancelled, causing a leak. LeakCanary now detects this leak and reports animator state information.

```kotlin
class ExampleActivity : Activity() {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main_activity)
    findViewById<Button>(R.id.button).setOnClickListener { view ->
      ObjectAnimator.ofFloat(view, View.ALPHA, 0.1f, 0.2f).apply {
        duration = 100
        repeatMode = ValueAnimator.REVERSE
        repeatCount = ValueAnimator.INFINITE
        start()
      }
    }
  }
}
```

--------------------------------

### Run Shark CLI heap-growth command (Shell)

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Runs the heap-growth command from the Shark CLI zip. Replace the path and package name as needed.

```shell
$ ~/Downloads/shark-cli-3.0-alpha-2/bin/shark-cli -p com.example.app.debug heap-growth
```

--------------------------------

### Leak trace for the bad code example

Source: https://github.com/square/leakcanary/blob/main/docs/fundamentals-fixing-a-memory-leak.md

Leak trace produced by LeakCanary for the bad code example. Shows the reference path from a GC root (FontsContract.sContext) to the leaked MainActivity instance.

```text
┬───
│ GC Root: System class
│
├─ android.provider.FontsContract class
│    ↓ static FontsContract.sContext
├─ com.example.leakcanary.ExampleApplication instance
│    ↓ ExampleApplication.leakedViews
├─ java.util.ArrayList instance
│    ↓ ArrayList.elementData
├─ java.lang.Object[] array
│    ↓ Object[].[0]
├─ android.widget.TextView instance
│    ↓ TextView.mContext
╰→ com.example.leakcanary.MainActivity instance
```

--------------------------------

### Shark Dive CLI help commands

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/shark-dive-agent/AGENTS.md

Shows the CLI help surface: general help, help for the open_heap_dump command, and leak investigation help.

```bash
"Shark Dive.app/Contents/MacOS/Shark Dive" --help
"Shark Dive.app/Contents/MacOS/Shark Dive" --help open_heap_dump
"Shark Dive.app/Contents/MacOS/Shark Dive" --leak-investigation-help
```

--------------------------------

### Kotlin HashMap usage example

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Example of a Kotlin class that stores tabs in a HashMap, used to illustrate how LeakCanary's improved data structure support surfaces logical keys in leak traces.

```kotlin
class CheckoutController {

  val tabs = HashMap<String, Tab>()

  fun addItemsTab(tab: Tab) {
    tabs["ItemsTab"] = tab
  }
}

```

--------------------------------

### Publish shark-cli to Homebrew with brew bump-formula-pr

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Use this command to publish a stable release of shark-cli to Homebrew. Only run it for stable versions, as homebrew-core does not accept alpha or beta releases.

```bash
brew bump-formula-pr --url https://github.com/square/leakcanary/releases/download/v$NEW_VERSION/shark-cli-$NEW_VERSION.zip leakcanary-shark
```

--------------------------------

### Shark Dive launcher commands: --help, open_heap_dump, list_leak_groups

Source: https://github.com/square/leakcanary/blob/main/docs/shark-dive.md

Shows the launcher commands for the Shark Dive app: --help prints all commands, and --cli commands open a heap dump and list leak groups. The --cli flag distinguishes commands from app runs, and commands answer with JSON on stdout.

```bash
"/Applications/Shark Dive.app/Contents/MacOS/Shark Dive" --help
"/Applications/Shark Dive.app/Contents/MacOS/Shark Dive" \
  --cli open_heap_dump path=/var/dumps/bug-4821.hprof reason="The dump the report came with"
"/Applications/Shark Dive.app/Contents/MacOS/Shark Dive" \
  --cli list_leak_groups heapDumpKey=bug-4821.hprof reason="Starting from what the dump says about itself"
```

--------------------------------

### Set up milestone management aliases

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Define optional GitHub CLI aliases for listing open milestones, creating a milestone, and closing a milestone.

```bash
gh alias set listOpenMilestones "api graphql -F owner=':owner' -F name=':repo' -f query='
    query ListOpenMilestones(\$name: String\!, \$owner: String\!) {
        repository(owner: \$owner, name: \$name) {
            milestones(first: 100, states: OPEN) {
                nodes {
                    title
                    number
                    description
                    dueOn
                    url
                    state
                    closed
                    closedAt
                    updatedAt
                }
            }
        }
    }
'"

gh alias set --shell createMilestone "gh api --method POST repos/:owner/:repo/milestones --input - | jq '{ html_url: .html_url, state: .state, created_at: .created_at }'"

gh alias set --shell closeMilestone "echo '{\"state\": \"closed\"}' | gh api --method PATCH repos/:owner/:repo/milestones/\$1 --input - | jq '{ html_url: .html_url, state: .state, closed_at: .closed_at }'"
```

--------------------------------

### Create release branch and set version

Source: https://github.com/square/leakcanary/blob/main/docs/releasing.md

Create the release branch and set the release version in gradle.properties.

```bash
git checkout main && git pull && \
git checkout -b release_$NEW_VERSION && \
sed -i '' "s/VERSION_NAME=.*/VERSION_NAME=$NEW_VERSION/" gradle.properties
```

--------------------------------

### Configure throwaway Gradle project for Dagger/Metro heap dump

Source: https://github.com/square/leakcanary/blob/main/shark/shark-dive/notes/dependency-injection.md

Sets up a throwaway Gradle project that includes both Dagger and Metro so one heap dump can compare both frameworks. The properties file forces the Kotlin compiler to run in-process because jvmToolchain(21) alone doesn't move the Kotlin daemon to Java 21, which Metro's compiler plugin requires. The bash command runs the probe with Java 21 and writes the heap dump to /tmp/di-probe.hprof.

```kotlin
// build.gradle.kts
plugins {
  kotlin("jvm") version "2.4.10"
  id("com.google.devtools.ksp") version "2.3.10"
  id("dev.zacsweers.metro") version "1.4.0"
  application
}
kotlin { jvmToolchain(21) }
application { mainClass.set("probe.MainKt") }
dependencies {
  implementation("com.google.dagger:dagger:2.60.1")
  ksp("com.google.dagger:dagger-compiler:2.60.1")
}
```

```properties
# gradle.properties — jvmToolchain(21) alone isn't enough, the Kotlin daemon still starts on the
# JVM Gradle runs on, and Metro's compiler plugin won't load there.
kotlin.compiler.execution.strategy=in-process
```

```bash
JAVA_HOME=$(/usr/libexec/java_home -v 21) gradle --no-daemon -q run --args="/tmp/di-probe.hprof"
```

--------------------------------

### Retrieve ObjectWatcher after upgrading

Source: https://github.com/square/leakcanary/blob/main/docs/upgrading-to-leakcanary-2.0.md

After upgrading, use AppWatcher.objectWatcher to get an ObjectWatcher instance. This is the replacement for the deprecated LeakCanary.installedRefWatcher().

```kotlin
val objectWatcher: ObjectWatcher = AppWatcher.objectWatcher
```

--------------------------------

### show

Source: https://github.com/square/leakcanary/blob/main/docs/shark-dive.md

Opens a tab and brings it to the front.

```APIDOC
## show

### Description
Opens a tab in the window and brings it to the front. Returns a `shark://` link to the tab.

### Method
Command

### Endpoint
`show`

### Parameters
- **tab** (string) - Required - The tab to open.
- **reason** (string) - Required - Reason for the call.

### Response
Returns a `shark://` link to the opened tab.
```

--------------------------------

### Run shark-cli neo4j command to explore heap dump

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Converts a heap dump into an embedded Neo4j database and opens Neo4j Browser. The `--process` flag specifies the target app process (e.g., `com.example.app.debug`).

```bash
shark-cli --process com.example.app.debug neo4j
```

--------------------------------

### Before: Test Application class in Java

Source: https://github.com/square/leakcanary/blob/main/docs/upgrading-to-leakcanary-2.0.md

Before LeakCanary 2.0, this Java test Application class installs an instrumentation RefWatcher using InstrumentationLeakDetector.instrumentationRefWatcher().

```java
public class InstrumentationTestExampleApplication extends DebugExampleApplication {
  @Override protected void installLeakCanary() {
    InstrumentationLeakDetector.instrumentationRefWatcher(this)
      .buildAndInstall();
  }
}
```

--------------------------------

### Customize Heap Dumping with LeakCanary.config

Source: https://github.com/square/leakcanary/blob/main/docs/recipes.md

Update LeakCanary.config to change the retained visible threshold for heap dumping. This example sets it to 3.

```kotlin
LeakCanary.config = LeakCanary.config.copy(retainedVisibleThreshold = 3)
```

--------------------------------

### Run Gradle Tasks: build, test, detekt, updateKotlinAbi, siteDokka

Source: https://github.com/square/leakcanary/blob/main/AGENTS.md

Use these Gradle commands for typical development tasks: run CI, test a single module, run static analysis, update ABI dumps after a public API change, or regenerate API docs. The repository uses Java 17 to build and targets Java 8 bytecode.

```bash
./gradlew build                       # what CI runs
./gradlew :shark:shark:test           # one module's unit tests
./gradlew detekt                      # static analysis, also run by the pre-push hook
./gradlew updateKotlinAbi             # after any public API change, see below
./gradlew siteDokka                   # regenerate docs/api

```

--------------------------------

### Retrieve RefWatcher before upgrading

Source: https://github.com/square/leakcanary/blob/main/docs/upgrading-to-leakcanary-2.0.md

Before upgrading to LeakCanary 2.0, this was how you retrieved the RefWatcher instance. Replace it with the new ObjectWatcher API shown in the 'Now' example.

```kotlin
val refWatcher: RefWatcher = LeakCanary.installedRefWatcher()
```

--------------------------------

### shark-cli interactive command help

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Shows the interactive command's help output after running shark-cli with a heap dump file. The interactive prompt lists available commands for exploring the heap dump, including analyze, class, instance, array, and path-finding commands.

```bash
$ shark-cli -h heapdump.hprof interactive
Enter command [help]:
help

Available commands:
  analyze                   Analyze the heap dump.
  class NAME@ID             Show class with a matching NAME and Object ID.
  instance CLASS_NAME@ID    Show instance with a matching CLASS_NAME and Object
ID.
  array CLASS_NAME@ID       Show array instance with a matching CLASS_NAME and
Object ID.
  ->instance CLASS_NAME@ID  Show path from GC Roots to instance.
  ~>instance CLASS_NAME@ID  Show path from GC Roots to instance, highlighting
suspect references.
  help                      Show this message.
  exit                      Exit this interactive prompt.

```

--------------------------------

### Custom ReachabilityWatcher filtering instances

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Creates a custom `ReachabilityWatcher` that delegates to `AppWatcher.objectWatcher` but filters out specific instances (e.g., `BadSdkLeakingFragment`). The default watchers are installed with this delegate.

```kotlin
class DebugExampleApplication : ExampleApplication() {

  override fun onCreate() {
    super.onCreate()

    val delegate = ReachabilityWatcher { watchedObject, description ->
      if (watchedObject !is BadSdkLeakingFragment) {
        AppWatcher.objectWatcher.expectWeaklyReachable(watchedObject, description)
      }
    }

    val watchersToInstall = AppWatcher.appDefaultWatchers(application, delegate)

    AppWatcher.manualInstall(
      application = application,
      watchersToInstall = watchersToInstall
    )
  }
}
```

--------------------------------

### Deploy documentation site with siteDokka and mkdocs gh-deploy

Source: https://github.com/square/leakcanary/blob/main/docs/releasing-shark-dive.md

Deploys the documentation site from the current checkout. siteDokka is required even for a Shark Dive window release because docs/api is generated and git ignored; without it gh-deploy publishes API pages that 404. Run from main to avoid publishing unrelated documentation work.

```bash
rm -rf docs/api && ./gradlew siteDokka && mkdocs gh-deploy
```

--------------------------------

### Leak trace with View resource id

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Example of a leak trace line showing the resource id name for a View instance, as displayed in the LeakCanary UI.

```text
├─ android.widget.TextView instance
│    View.mID = R.id.helper_text
```

--------------------------------

### Navigate the heap object graph with shark-graph

Source: https://github.com/square/leakcanary/blob/main/docs/shark.md

Add the shark-graph dependency and use HprofHeapGraph.indexHprof() to build a heap graph, then find the java.lang.Thread class and iterate its instances to read the name field as a Java string.

```groovy
// build.gradle
dependencies {
  implementation 'com.squareup.leakcanary:shark-graph:$sharkVersion'
}

```

```kotlin
import java.io.File
import shark.Hprof
import shark.HprofHeapGraph

fun main(args: Array<String>) {
  val heapDumpFile = File(args[0])

  // Prints all thread names
  Hprof.open(heapDumpFile).use { hprof ->
    val heapGraph = HprofHeapGraph.indexHprof(hprof)
    val threadClass = heapGraph.findClassByName("java.lang.Thread")!!
    val threadNames: Sequence<String> =
      threadClass.instances.map { instance ->
        val nameField = instance["java.lang.Thread", "name"]!!
        nameField.value.readAsJavaString()!!
      }
    threadNames.forEach { println(it) }
  }
}

```

--------------------------------

### Configure LeakCanary with Java-friendly Config.Builder

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Use the Java-friendly builder to update LeakCanary configuration. This example sets retainedVisibleThreshold to 3 and disables computeRetainedHeapSize, then applies the new config.

```java
LeakCanary.Config config = LeakCanary.getConfig().newBuilder()
  .retainedVisibleThreshold(3)
  .computeRetainedHeapSize(false)
  .build();
LeakCanary.setConfig(config);
```

--------------------------------

### Clean build

Source: https://github.com/square/leakcanary/wiki/Making-a-new-LeakCanary-release

Performs a clean build to ensure everything compiles before tagging.

```bash
./gradlew clean build
```

--------------------------------

### Leak trace output with Verdict: Expected / Stuck

Source: https://github.com/square/leakcanary/blob/main/docs/changelog.md

Example of a leak trace output after the breaking change, showing the new Verdict labels (Expected and Stuck) and the reasons for each object.

```text
├─ com.example.MySingleton class
│    Verdict: Expected (a class is always expected)
│    ↓ static MySingleton.leakedView
│                         ~~~~~~~~~~
├─ android.widget.TextView instance
│    Verdict: Stuck (View.mContext references a destroyed activity)
│    ↓ TextView.mContext
╰→ com.example.MainActivity instance
     Verdict: Stuck (Activity#mDestroyed is true)
```

--------------------------------

### list_processes

Source: https://github.com/square/leakcanary/blob/main/docs/shark-dive.md

Lists processes on a device.

```APIDOC
## list_processes

### Description
Lists processes on a device for taking a heap dump.

### Method
Command

### Endpoint
`list_processes`

### Parameters
- **device** (string) - Required - Device identifier.
- **reason** (string) - Required - Reason for the call.

### Response
Returns a list of processes.
```

--------------------------------

### Leak trace text with underlined references

Source: https://github.com/square/leakcanary/blob/main/docs/fundamentals-how-leakcanary-works.md

Example of a leak trace shared as text. Suspicious references are underlined with `~~~` and correspond to the references used to compute the leak fingerprint.

```text
...
│  
├─ com.example.leakcanary.LeakingSingleton class
│    Verdict: Expected (a class is always expected)
│    ↓ static LeakingSingleton.leakedViews
│                              ~~~~~~~~~~~
├─ java.util.ArrayList instance
│    Verdict: Unknown
│    ↓ ArrayList.elementData
│                ~~~~~~~~~~~
├─ java.lang.Object[] array
│    Verdict: Unknown
│    ↓ Object[].[0]
│               ~~~
├─ android.widget.TextView instance
│    Verdict: Stuck (View.mContext references a destroyed activity)
...
```

--------------------------------

### Tag and push release

Source: https://github.com/square/leakcanary/wiki/Making-a-new-LeakCanary-release

Creates a tag for the release and pushes it to origin.

```bash
git tag v1.5
git push origin v1.5
```

--------------------------------

### Use DetectLeaksAfterTestSuccess rule to assert no leaks at end of test

Source: https://github.com/square/leakcanary/blob/main/docs/ui-tests.md

Adds the DetectLeaksAfterTestSuccess rule to automatically call LeakAssertions.assertNoLeaks() at the end of each test. The rule is applied via @get:Rule.

```kotlin
class CartTest {
  @get:Rule
  val rule = DetectLeaksAfterTestSuccess()

  @Test
  fun addItemToCart() {
    // ...
  }
}
```

--------------------------------

### list_devices

Source: https://github.com/square/leakcanary/blob/main/docs/shark-dive.md

Lists available devices.

```APIDOC
## list_devices

### Description
Lists available devices for taking a heap dump.

### Method
Command

### Endpoint
`list_devices`

### Parameters
- **reason** (string) - Required - Reason for the call.

### Response
Returns a list of devices.
```

--------------------------------

### Heap analysis result output

Source: https://github.com/square/leakcanary/blob/main/docs/fundamentals-how-leakcanary-works.md

Example output shown in Logcat after LeakCanary analyzes a heap dump. It reports the number of application leaks, displays a leak fingerprint, and shows the beginning of a leak trace.

```text
====================================
HEAP ANALYSIS RESULT
====================================
2 APPLICATION LEAKS

Displaying only 1 leak trace out of 2 with the same leak fingerprint
Leak fingerprint: ce9dee3a1feb859fd3b3a9ff51e3ddfd8efbc6
┬───
│ GC Root: Local variable in native code
│
...
```
Tokens:
Raw