After Deleting LeakCanary, I Built My Own with Trae: The Hard Part Isn't Analyzing the Heap, It's Deciding When to Dump
The Day I Deleted LeakCanary, I Built My Own with Trae: The Hardest Part Isn't Analyzing the Heap, It's Deciding When to Dump
In mid-September, during a privacy compliance audit, a security colleague went down a list asking where each debug dependency sent its data. When she got to LeakCanary, she asked, "The notification it pops up — can you tap it to export the hprof? Does the hprof contain user data?" I couldn't answer on the spot. Back at my desk, I dragged a heap snapshot I'd exported from my own debug build into a text editor and searched. Inside were ID card numbers, patient names, and an unexpired token — all plaintext java.lang.String instances. Debug.dumpHprofData() captures the entire Java heap; it has no concept of personal information.
That week I deleted the debugImplementation line. Clean for two weeks, then on October 8 the gray-release started reporting OOMs, concentrated on module M's report page. On a Redmi Note 11, entering and leaving seven or eight times got the process killed by the system. Before, a Leaks notification would pop up in the notification bar; now nothing. My first instinct was to write my own: after an Activity's onDestroy, hold a WeakReference, check five seconds later — if still there, report a leak. Under two hundred lines, but it ran with a string of false positives — normal pages that had just been back-buttoned were flagged as leaking, while the real problem with the report page wasn't caught.
Two days of reading source code taught me what I'd missed. After using LeakCanary for years, everything I knew was about the post-dump side: how to read reference chains, what the ~~~ marks, what Leaking: YES means. But how it decides "time to dump now" — I had no idea. And Square's own history says it almost verbatim: what's missing was never a way to analyze the heap, but knowing when it's worth the effort — a trigger. Later I used Trae to run that whole pipeline again, from weak-reference probes to off-device hprof parsing, and finally to freezing the entire workflow into a reusable development Skill. This post records that trip.
What's Missing Is Never the Analysis—It's the Trigger
Before LeakCanary, hunting memory leaks was manual labor: pick an arbitrary moment, dump a heap, pull it off the device, drop it into Eclipse MAT, and flip through which class's instance count looks off. Most dumps show nothing. Occasionally something shows up, but it's been so long since the change that actually introduced the problem that you can't match them up.
Square's official documentation tells this story bluntly: what was missing wasn't a means to analyze dump files, but "knowing whether this capture is worth it — a trigger." LeakCanary was built around that trigger. Its later famous features, including on-device heap analysis, all came after.
The first version wasn't even a library, nor did it have that name. In March 2015, Pierre-Yves Ricau wrote a 154-line debug-only class in Square's cashier app, called ActivityMemoryDiaper — memory diaper. The notification icon was a diaper with a pin. What it did, in order, was five steps: use a weak reference to watch every destroyed Activity, wait five seconds, force a GC, if the Activity is still there dump the heap, pop a notification, tap to open an email with a .hprof attachment, body text reading "You just found a memory leak, the Register Android team loves you, please send the file to seller-android@ and we'll fix it."
The name was decided in three Slack messages. P-Y asked "Is memory-diaper a suitable project name, I can't think of a better pun", Logan Johnson replied "No, it's a bit gross and not funny, I don't want to see it on a slide deck", Eric Denman said "How about something in the direction of a canary in a coal mine." So the canary stuck, the diaper went into history.
What really stopped me was that the detection method was overturned twice in the first two weeks.
Version 1 Hold a WeakReference to the Activity itself
↓ nine days later
Version 2 Attach an object to the Activity, see if it gets finalized
commit: Detect memory leaks with no weak references
"Avoid holding a weak reference pointing to the activity, that could extend its lifecycle,
and also confusing when analyzing the heap snapshot"
↓ one more week
Version 3 Don't look at recycling, look at 'weakly reachable'
commit: Detect weakly reachable leak tags
"Once the LeakTag becomes weakly reachable, it should theoretically enqueue immediately,
which is earlier than finalize() being called, reducing some false positives caused by weak references"
Version three is the principle still used today. The motivations for the two changes: the first was "the tool changed what it was measuring," the second was "weak reachability is earlier and cleaner than actual reclamation." The two hundred lines I wrote on October 8 stepped into both traps exactly: I held a weak reference to the Activity itself, and my condition was "reference not cleared." At the time I thought it was fine, and the 60%+ alarm rate I attributed to a too-loose threshold.
A number shows how much that trigger is worth: after Square first enabled it in their cashier app, fixing the leaks it found cut their OOM crash rate by 94%. Not through a more accurate analyzer, but by "dumping at the right time," giving someone a piece of evidence directly tied to the action they just took.
I copied that sentence to the first line of docs/leak-design.md. Everything else derives from it: the detection layer's job is to produce evidence, the analysis layer's job is to read evidence.
First See How It's Layered
Before deciding to build my own, I broke this library into modules and looked at each one. I always thought it was "one dependency, one notification," but after 2.x it's split very finely, with each layer having its own boundary.
flowchart TB
subgraph DEV[On-device · in App process]
A[ActivityLifecycleCallbacks<br/>Fragment / View / ViewModel callbacks] --> B[AppWatcher]
B --> C[ObjectWatcher<br/>KeyedWeakReference + ReferenceQueue]
C --> D[HeapDumpTrigger<br/>5 sec / foreground 5 background 1]
D --> E[HeapDumper<br/>Debug.dumpHprofData]
E --> F[HeapAnalyzer<br/>Shark on-device analysis]
F --> G[OnHeapAnalyzedListener<br/>notification / report / Leaks UI]
end
subgraph HOST[dev machine / CI]
H[shark-cli<br/>analyze / dump-process / strip-hprof / heap-growth] --> F
I[Gradle plugin<br/>mapping into APK asset] --> F
end
J[plumber-android<br/>fix known AOSP leaks] -.-> DEV
| Module | What it does | Where it runs | Can I write it myself |
|---|---|---|---|
object-watcher |
KeyedWeakReference, ReferenceQueue, retained count |
platform-independent, can go in release | Yes, a few hundred lines |
object-watcher-android |
lifecycle mounting, auto watch Activity / Fragment / View / ViewModel | App process | Yes, AndroidX is enough |
leakcanary-android |
trigger, dump, analysis, notification, Leaks UI | debug only | detection and trigger yes, UI can simplify |
shark-hprof / shark-graph |
parse hprof binary, build object graph and index | any JVM | shouldn't write fully myself |
shark |
shortest path, dominator tree, ObjectInspector, group signature | on-device / CLI | minimal version off-device |
plumber-android |
patch known AOSP leaks | App process | replace with whitelist table |
shark-cli |
command-line analysis of existing hprof, stripping, heap growth detection | dev machine | replace with Python scripts |
leakcanary-android-test / uiautomator |
UI tests that run repeated scenarios to check heap growth | instrumented tests | separate section later |
After this table, the boundaries are clear: detection and triggering is the 154-line level; those APIs are fully writable with platform APIs. The analysis layer, after switching from HAHA to Shark, grew from about 6,000 lines of Java to about 16,000 lines of Kotlin—most of it hprof parsing, data structure adaptation, and tests. Rewriting that would be pointless, and besides, the whole point of this cleanup was to stop putting un-auditable third-party code into the debug APK.
So my division of labor: on-device only "discover + collect evidence + strip sensitive data," and on the dev machine an off-device minimal hprof parser that produces the shortest reference chain. The analyzer doesn't aim to cover all ART / vendor heap formats; if it can't parse, it explicitly says "this dump is not in supported range," never fakes success. I wrote this capability boundary into Trae's Rules, and in round 8 when it wanted to tag on a dominator tree implementation, I pushed back.
There's another layer I couldn't copy: its auto-install. AppWatcherInstaller is a ContentProvider injected via manifest merger. The system calls its onCreate() on the main thread, earlier than Application.onCreate(), so after 2.x you don't even need LeakCanary.install(this). Convenient, but it costs—it sits at the very front of the cold-start chain, and this cleanup wanted exactly "what is initialized, when, and everything audit-able at a glance." Our project switched to calling install explicitly in Application.onCreate(), only on debug builds, and printing the switches and thresholds to logcat when installed, so the security colleague can see the evidence directly when reviewing.
From an Activity's Destruction to a Notification, Four Steps
The official documentation splits the whole flow into four sections: detect retained objects → dump heap → analyze heap → classify leak. I redrew it in our project's call order, marking the actual platform API each step calls.
sequenceDiagram
participant U as User / System
participant L as ActivityLifecycleCallbacks
participant W as ObjectWatcher
participant Q as ReferenceQueue
participant T as HeapDumpTrigger
participant D as HeapDumper
participant A as Off-device analyzer
U->>L: onActivityDestroyed(activity)
L->>W: watch(activity, "received onDestroy()")
W->>W: generate UUID key
W->>W: KeyedWeakReference(obj, key, queue)
W->>W: watchedKeys[key] = ref
W->>T: post delayed 5 sec check
Note over Q: GC enqueues refs of reclaimed objects
T->>Q: first poll, clear enqueued keys
T->>T: Runtime.gc() + runFinalization()
T->>Q: second poll, clear again
T->>T: key still in table → retained +1
T->>T: foreground retained >= 5 or background >= 1 ?
T->>D: Debug.dumpHprofData(path)
D->>D: private dir write + zero out primitive arrays
D->>A: pull stripped hprof
A->>A: Pass1 build index / Pass2 build edges / BFS shortest path
A-->>U: report page + group signature
In the four steps, the easily skipped part is the second segment of the first step: the judgment isn't "wait five seconds and look," it's wait five seconds, clear the queue, force GC, clear the queue again, and only then if still alive count it. The order changes the result completely. My first version missed one GC, counting a large number of objects that would have been reclaimed by the next GC as leaks.
A state machine explains better than a sequence diagram why there are two segments:
stateDiagram-v2
[*] --> Watching: onDestroy → watch()
Watching --> WeaklyReachable: after GC ref enqueues into ReferenceQueue
WeaklyReachable --> Cleared: poll hit, remove from watchedKeys
Watching --> Suspect: 5 sec elapsed and not in queue
Suspect --> WeaklyReachable: after forced GC enqueues
Suspect --> Retained: after second poll still in table
Retained --> Counting: retained count +1
Counting --> Dumping: threshold reached
Dumping --> Analyzing: hprof written
Analyzing --> [*]: report
Several parameters weren't made up arbitrarily; I looked up the origin of each one:
| Parameter | Default | Why this number |
|---|---|---|
| Delay check | 5 sec | Give delayed tasks and message queues after onDestroy time to wrap up; too short causes false positives |
| Visible threshold | 5 retained | dump causes ART to suspend all threads; dumping for every retained would bounce between freeze and analysis |
| Hidden threshold | 1 retained | After pressing Home, user doesn't see the freeze; grab the heap within five seconds |
| Notification tap | immediate dump | person actively wants to see; skip threshold |
| Reschedule interval | 2000ms | the log line Rescheduling check ... in 2000ms because found only 4 retained objects (< 5 while app visible) |
The foreground 5 / background 1 rule was set during the 2.0 rewrite, born from a complaint list recorded after talking to Uber about deployment: 1.x handled one leak at a time; when there were many, the phone bounced between dump (freeze) and analysis alternately, making it unusable; most people didn't know how much could be configured; the API was organized around "which component to replace," not "what I want to do." That list directly birthed batch reporting and changed the config API to AppWatcher.config / LeakCanary.config, organized by use case.
I pushed the thresholds out a bit more: on a medical app's report page with many WebViews and image caches, a single dump froze the Redmi Note 11 for around 600ms, so I added a "max one dump per 60 seconds per process" rate limit and moved the dump to a HandlerThread. The freeze itself can't be eliminated; what can be done is not to let it block the path the user is actively tapping.
The Weak-Reference Probe: Watch Weakly Reachable, Not Reclamation
This layer is the foundation of the whole thing, and it's where my first version went most wrong.
WeakReference has a often-ignored semantic: when an object has only weak references pointing to it, the GC will, before reclaiming it, put the WeakReference object itself into the ReferenceQueue bound to it at creation. That means the presence of that ref in the queue doesn't mean the object has been reclaimed; it only means it's weakly reachable. LeakCanary watches the former, not the latter — the official design doc has a dedicated section called "watch then confirm" for exactly this distinction.
This brings two direct benefits. First, earlier: enqueueing happens before finalize() runs, and finalize() is not guaranteed to run when, whether it runs, and it may even resurrect the object. Second, cleaner: we only hold a tiny KeyedWeakReference, never touch the target object itself, so we don't "the tool changes what it measures" like the first version.
KeyedWeakReference has a few more fields than JDK's WeakReference, each one useful:
// app/src/debug/java/com/example/health/leak/KeyedWeakReference.kt
// only exists in debug source set; release build never compiles this class
class KeyedWeakReference(
referent: Any,
val key: String, // UUID, later used to identify in hprof
val description: String, // "MainActivity received onDestroy()"
val watchUptimeMs: Long, // for calculating retained duration
queue: ReferenceQueue<Any>
) : WeakReference<Any>(referent, queue)
The core of ObjectWatcher is three actions, totaling under a hundred lines:
// app/src/debug/java/com/example/health/leak/ObjectWatcher.kt
class ObjectWatcher(
private val clock: () -> Long = { SystemClock.uptimeMillis() },
private val checkExecutor: Executor
) {
private val queue = ReferenceQueue<Any>()
private val watchedKeys = ConcurrentHashMap<String, KeyedWeakReference>()
@Volatile private var retainedCount = 0
val retainedObjectCount: Int get() = retainedCount
@Synchronized
fun watch(watchedObject: Any, description: String) {
removeWeaklyReachableObjects() // first clear old accounts
val key = UUID.randomUUID().toString()
val ref = KeyedWeakReference(
watchedObject, key, description, clock(), queue
)
watchedKeys[key] = ref
checkExecutor.execute { // confirm after 5 sec
moveToRetained(key)
}
}
private fun removeWeaklyReachableObjects() {
var ref: KeyedWeakReference?
while (queue.poll().also { ref = it as? KeyedWeakReference } != null) {
watchedKeys.remove(ref!!.key) // enqueued = weakly reachable = not a leak
}
}
@Synchronized
private fun moveToRetained(key: String) {
removeWeaklyReachableObjects()
if (!watchedKeys.containsKey(key)) return // already reclaimed
GcConfirmer.forceGc() // actively create an opportunity
removeWeaklyReachableObjects() // key: clear again after GC
if (watchedKeys.containsKey(key)) {
retainedCount++
onRetained(key, watchedKeys[key]!!.description)
}
}
}
The few lines in GcConfirmer look a bit crude, but they're necessary:
// app/src/debug/java/com/example/health/leak/GcConfirmer.kt
object GcConfirmer {
fun forceGc() {
Runtime.getRuntime().gc()
System.runFinalization()
// enqueue is asynchronous, give ReferenceHandler a little time to put ref in queue
Thread.sleep(100)
Runtime.getRuntime().gc()
}
}
The sleep(100) I added during rework. In the first version, after running GC I immediately polled, the queue was empty, and the false-positive rate wouldn't come down; when I found out that enqueueing is done by a separate ReferenceHandler thread, I added the wait. Later, in round 6, Trae replaced that hardcoded 100ms with "poll at most 5 times, 20ms each, exit when hit," which is more stable and degrades more gracefully on devices without a guaranteed Runtime.gc().
There's a comparison table I keep pinned in docs/leak-design.md. The same key looks completely different in five places, and once I got it straight I finally truly understood this layer:
| Location | Shape of this key | Who can read it |
|---|---|---|
watchedKeys |
ConcurrentHashMap String key pointing to a KeyedWeakReference |
in-process, real-time |
ReferenceQueue |
when weakly reachable, the ref object itself is in the queue; key is just a field | in-process, after GC |
| hprof | a KeyedWeakReference instance, field key is a UTF-8 string constant |
found by class name when parsing off-device |
| leak trace | reference chain from GC Root to that instance, ending with key = xxx |
report page |
| group signature | sha1Hash(concatenation of each suspicious reference), independent of key, same cause different instance grouped together |
archive, dedup |
The last row is easily confused: key is for identifying a single object, signature is for identifying one bug. In 2.x logs you see Signature: ce9dee3a1feb859fd3b3a9ff51e3ddfd8efbc6, four retained objects grouped into 2 distinct leaks, thanks to that. The official algorithm is straightforward: concatenate each suspicious reference marked ~~~ and SHA-1 it:
val signature = sha1Hash(
"com.example.LeakingSingleton.leakedViews" +
"java.util.ArrayList.elementData" +
"java.lang.Object[].[x]"
)
// dbfa277d7e5624792e8b60bc950cd164190a11aa
I wrote a simplified version following that idea, but normalized "array index" to [x]; otherwise the same leak with a different index each time splits into different lines. The official doc mentions that, but Trae's round 10 first version missed it, and the report showed the same leak repeated a dozen lines before I stared at it long enough to realize.
What's Actually in an hprof
I originally planned to skip this part—there's MAT and Android Studio. But when I actually wrote the parser, I found that without breaking open the binary format, the reference chains in reports would always be a black-box conclusion from someone else.
Debug.dumpHprofData(path) writes the HPROF binary defined by the JVM TI Agent. The file header is a line ending with \0 with a version string (common on Android: JAVA PROFILE 1.0.3), followed by a u4 identifier size (4 or 8, depending on 64-bit id), then a u8 timestamp. After that is a series of records, each with a fixed structure:
record := tag(u1) + timestamp(u4) + length(u4) + body(length bytes)
The top-level tags are few:
| Tag | Name | What's inside |
|---|---|---|
0x01 |
STRING_IN_UTF8 |
id + UTF-8 bytes, class names and field names come from here |
0x02 |
LOAD_CLASS |
class serial + class object id + stack serial + name string id |
0x04 / 0x05 |
STACK_FRAME / STACK_TRACE |
allocation call stack |
0x0C |
HEAP_DUMP |
full heap, contains sub-records |
0x1C |
HEAP_DUMP_SEGMENT |
segmented heap, more common on Android |
0x2C |
HEAP_DUMP_END |
end of segments |
The trap is inside HEAP_DUMP_SEGMENT: its sub-records have no length field; only a u1 sub-tag plus a body of fixed length or length inferred from structure, so you must advance the cursor manually by tag type. My first attempt read it as the top-level record format, started misaligned from the second record, and the parsed class names were all garbage.
Sub-records fall into two categories. One is GC Roots, each pointing to an object id:
| Sub-tag | GC Root type | Common source |
|---|---|---|
0xFF |
ROOT_UNKNOWN |
vendor / ART unclassified |
0x01 |
ROOT_JNI_GLOBAL |
native global reference |
0x02 |
ROOT_JNI_LOCAL |
local reference in active JNI call |
0x03 |
ROOT_JAVA_FRAME |
Java stack frame local variable |
0x04 |
ROOT_NATIVE_STACK |
native stack |
0x05 |
ROOT_STICKY_CLASS |
system classes (loaded by bootstrap) |
0x06 |
ROOT_THREAD_BLOCK |
thread blocking object |
0x07 |
ROOT_MONITOR_USED |
in-use synchronization lock |
0x08 |
ROOT_THREAD_OBJECT |
live Thread object |
Android adds a few more: 0xFE HEAP_DUMP_INFO (multi-heap marker), 0x89 ROOT_INTERNED_STRING, 0x8A ROOT_FINALIZING, 0x8B ROOT_DEBUGGER, 0x8C ROOT_REFERENCE_CLEANUP, 0x8D ROOT_VM_INTERNAL, 0x8E ROOT_JNI_MONITOR, 0x90 ROOT_UNREACHABLE. My first version only recognized the first eight; hitting 0xFE threw an exception, crashing on every Android 13 dump.
The other category is objects:
0x20 CLASS_DUMP
class object id, stack serial, super class id, class loader id,
signers id, protection domain id, reserved × 2,
instance size(u4),
constant pool(u2 count + each item's index/type/value),
static fields(u2 count + name string id + type + value),
instance fields(u2 count + name string id + type)
0x21 INSTANCE_DUMP
object id, stack serial, class object id, following bytes count(u4),
field value byte stream (this class's fields first, then up to superclass)
0x22 OBJECT_ARRAY_DUMP
array object id, stack serial, element count(u4), array class object id, [id]*
0x23 PRIMITIVE_ARRAY_DUMP
array object id, stack serial, element count(u4), element type(u1), compact byte stream
Field type codes are 2=object, 4=boolean, 5=char, 6=float, 7=double, 8=byte, 9=short, 10=int, 11=long. Only 2 is a reference; all others are scalars — this decides which bytes in Pass2 get written as edges into the graph.
flowchart LR
subgraph P1[Pass 1 · build index]
A[read header get idSize] --> B[scan all records]
B --> C[STRING: id → name]
B --> D[LOAD_CLASS: classId → class name]
B --> E[CLASS_DUMP: class field layout]
B --> F[GC Root: collect root ids]
B --> G[object id → file offset]
end
subgraph P2[Pass 2 · build edges]
H[random seek by offset] --> I[parse field byte stream by class layout]
I --> J[fields with type=2 write edges]
J --> K[object graph]
end
P1 --> P2
K --> L[BFS from SuperRoot to target id]
L --> M[shortest strong reference path = leak trace]
The two-pass scan is why Shark uses less memory than HAHA. HAHA is a repackaging of Android Studio's perflib; it loads the entire heap into memory. Shark uses HprofInMemoryIndex to store "object id → file offset," pairs it with primitive-type collections like LongLongScatterMap to minimize the index, then uses RandomAccessHprofReader to seek on demand and Kotlin Sequence for lazy loading. The official changelog number I've remembered for a long time: a 160MB heap snapshot takes 2GB of memory to open in Android Studio; Shark only needs 40MB. That's also why 1.x's HeapAnalyzerService had to run in a separate process, and why 2.x could move analysis back into the main process.
BFS starts from all GC Roots (implementation-wise it hangs a synthetic SuperRoot connected to each root) and expands outward layer by layer. The first time it hits the target id gives the shortest strong reference path. Why shortest: longer paths usually route around intermediate nodes that should have been cleaned up, giving no clue which line to change; the shortest path narrows suspicion to the one or two references closest to the leaked object. Shark also has a VirtualInstanceReferenceReader that flattens internal structures like ArrayList.elementData and HashMap.table so the reference chain displays as "the way you wrote it in code," not "the way it's implemented." That trick comes from Android Studio team's Nathan Paige, who wrote expanders for BLeak; LeakCanary only moved it in at 2.8.
Above that is the dominator tree for retained size: if every path from a GC Root to B passes through A, then A dominates B; when A is reclaimed, B goes with it. That number answers "how much does this leak actually occupy," which is a different question from "who's holding it." My off-device script only does BFS, no dominator tree — that's another chunk of engineering, and doing it wrong gives you a wrong number. Better to explicitly write "this tool does not provide retained size."
Two more things directly relevant to this cleanup. One is obfuscation: in a release build's heap, class names are a.b.c, making the reference chain useless. Reading obfuscated heaps was added in three parts over ten months from 2019 to 2020 — Shark learned to parse ProGuard mapping and apply it when building chains, a Gradle plugin packs the mapping file as an asset into the APK, and the same deobfuscation became a -m option in shark-cli. On my side, I put mapping.txt in the same archive directory as the hprof, and pick it by version when parsing.
Second is stripping sensitive data, which is what the security colleague's question forced. Shark has HprofPrimitiveArrayStripper, which replaces the contents of PRIMITIVE_ARRAY_DUMP entirely with zeros; in shark-cli that's the strip-hprof command. On the app side, I do the same immediately after dump before allowing the file to leave the device, because strings and image pixels in the heap are inside primitive arrays. After adding it, I re-searched that snapshot: ID card numbers, names, tokens were all gone, but the reference chain was still there — the path only depends on object ids and field names, not the literal values of fields. I made Trae write a dedicated regression test for this in round 10, run every version since.
From Diaper to Canary, What Changed in These 11 Years
Lining up the versions, the changes run in a consistent direction: the detection layer barely moved; almost everything changed was about "how to make people willing to keep it on every day."
| Time | Version | What changed |
|---|---|---|
| 2015-03 | unnamed | Square's cashier app's 154-line ActivityMemoryDiaper, weak reference + 5 sec + forced GC + email attachment |
| 2015-05-08 | 1.3 | first GitHub import, Java, LeakCanary.install(this) returns RefWatcher; debugCompile with no-op for release; HAHA analysis, separate HeapAnalyzerService process, DisplayLeakService sends notification |
| 2016-2018 | 1.4~1.6.3 | support Fragments, AndroidExcludedRefs whitelist, full reference chain with expandable fields |
| 2019-04 first week | 2.0 start | Square hack week project; first four days Colin Marsch and Brandon Cheng ported 1.x code class by class to Kotlin |
| 2019-04-23 06:43 | 2.0-alpha-1 | Paris time, tagged live at Android Makers, talk titled "LeakCanary 2: Leaner, Better, Faster, Kotliner!"; previous week 67 commits, tested on the conference's own app |
| 2019-11-27 | 2.0 release | 7 months, 3 alphas, 5 betas, 23 contributors, 493 commits; ~6,000 lines Java → ~16,000 lines Kotlin; Shark replaces HAHA; auto-install; foreground 5 / background 1 batch reporting; grouping by type |
| 2020-12-24 | 2.6 | started watching root views after View.onDetachedFromWindow() and services after Service.onDestroy() |
| 2022-01-04 | 2.8 | brought in expanders (collections shown as written); Android 12, WorkManager, multi-process, App Startup adaptation |
| 2019-2020 | cross-version | three parts of reading obfuscated heaps completed: Shark parses mapping, Gradle plugin packs mapping into APK, shark-cli -m |
| 2022-2024 | 2.9.1~2.14 | 2.10 tried Neo4j for heap exploration; 2.12, 2.13 regular iteration; 2.14 (2024-04-17) fixed a SettableFuture dependency—when WorkManager later removed that class, 2.8~2.13 would crash during analysis |
| 2024-01-09 | 3.0-alpha-1 | started heap growth: ObjectGrowthDetector runs same UI scenario repeatedly to see if heap keeps growing |
| 2026-06-25 | 3.0-alpha-9 | still unreleased; shark-heap-growth merged back into main module, added leakcanary-android-test / uiautomator |
As of writing, the stable version is still 2.14, 3.0 has been alpha, top of the changelog says Unreleased. I had Trae verify this online in round 2 — many 2020-era tutorials claim 2.0 shipped in 2020, and treat LeakSentry as the current API, but that was an alpha-period name; the release renamed it to AppWatcher. Following old tutorials, the first line won't compile.
The most interesting thing about the 2.0 rewrite isn't Shark; it's the three report changes, all about "how to be nice to people":
1. Direction of the reference chain
Design notes originally argued for putting GC Roots at the bottom (like a stack trace),
drew six prototypes in one day in October 2018,
finally settled on Root at top, one reference per line, object state flagged next to it.
2. Stop printing every field
1.x could expand all fields of every object on the chain; informative, but no one reads it.
Replaced with short labels from ObjectInspector that say only the worthwhile sentence,
e.g. "View.mContext references a destroyed activity".
3. Reports become batch
1.x triggered once per retained; 2.x waits for background or foreground count of 5,
analyzes all leaks in one go, then groups identical ones.
Incidentally, a counterintuitive branch: heap growth detection in 3.0 alpha is the only part that finds leaks without watching any object. It runs the same UI scenario repeatedly and watches whether the number of objects in the heap keeps increasing. Interestingly, this mechanism reuses the expanders brought in at 2.8, and the expanders come from BLeak harness that the Android Studio team used to find leaks in their IDE. Going further back, BLeak's paper (John Vilk and Emery D. Berger, PLDI 2018) studied JavaScript memory leaks in web apps. A line that runs from a JS paper to Android heap analysis, four years apart.
Which old practices are dead today, which have come back, I keep a table by my own project:
| Practice | Status | Reason |
|---|---|---|
| dump at random time + drag into MAT to eyeball | dead | no trigger, dump and problem don't line up in time |
finalize() to judge reclamation |
dead | timing nondeterministic, objects may resurrect, high false positives |
| direct weak reference to target object | dead | tool changes the measured object and pollutes reference relationships in heap |
| separate analysis process | mostly dead | Shark memory down to 1/50, main process can handle |
no-op artifact in release |
dead | 2.x uses debugImplementation to isolate at source |
| dump for each discovery | dead | phone bounces between freeze and analysis |
weakly reachable + ReferenceQueue |
always | set in third version of 2015, unchanged for 11 years |
| 5 sec wait + forced GC | always | gives delayed tasks and message queues time to wrap up |
| shortest strong reference path | always | BFS naturally gives shortest, closest to the line that should change |
| "when to collect evidence" judgment | even more important | on-device analysis faster, but cost of one dump unchanged |
Mapping the Existing Encapsulation onto Our Project
This section took the most time in the cleanup: not copying code, but deciding which module in our project takes on which responsibility, and where to draw boundaries. Our health app at the time — module M handles the report page and medical records; the debug build must not contain third-party dependencies that export the full heap; the release build must not contain any detection code; the online OOM reports hope to include a "number of objects not reclaimed after onDestroy."
I had Trae first list this mapping table, then I crossed out the parts it wanted to do extra:
| LeakCanary's encapsulation | Our project's counterpart | Approach |
|---|---|---|
object-watcher / ObjectWatcher |
leak/ObjectWatcher.kt |
copy the design, implement myself, ~110 lines |
object-watcher-android lifecycle mounting |
leak/LeakWatchers.kt |
copy the checklist, use ActivityLifecycleCallbacks + AndroidX myself |
AppWatcherInstaller (ContentProvider) |
LeakDetector.install() |
change: explicit call, debug only, refuse auto-install |
HeapDumpTrigger |
leak/DumpTrigger.kt |
copy the strategy, tighten thresholds, add 60-sec rate limit |
HeapDumper / Debug.dumpHprofData |
leak/HeapDumper.kt |
copy the API, add private dir and immediate stripping |
Shark full analysis |
tools/hprof_min.py |
shrink: only Pass1 index + Pass2 edge-building + BFS, no dominator tree |
Leaks UI / notification |
notification + debug report page | simplify: native NotificationCompat + native AlertDialog explaining purpose |
OnHeapAnalyzedListener reporting |
write stripped local JSON, manually decide upload | change: no upload by default, avoid personal data leaving device |
AndroidReferenceMatchers / plumber-android |
assets/known-leaks.txt |
replace with table: only whitelist, no patching system |
object-watcher-android into release count |
leak/ReleaseRetainedCounter.kt |
copy the idea, keep only count; release doesn't dump, doesn't write files |
leakcanary-android-instrumentation |
in Espresso repeatedly enter/exit report page | later, not in this version |
I added three boundaries during review, all directly tied to this compliance cleanup:
One: before any dumped file can leave the device, PRIMITIVE_ARRAY_DUMP must be zeroed. In hprof, String is backed by a primitive array; medical records, ID numbers, tokens all live there. The reference chain only needs object ids and field names, not literal values. After stripping, I ran strings over it: nothing left.
Two: in the release build, keep only a very thin counter and a read-out for retainedObjectCount, hooked into the OOM crash reporting metadata. This is actually the officially designed use case for object-watcher-android — "its code size is small and should have no effect on release apps," just weak references, no dump, nothing else. I moved that into my own implementation so the security colleague can see everything at a glance: no network, no files, no third-party classes.
Three: no auto-install. ContentProvider.onCreate() runs on the main thread before Application.onCreate(), which is convenient but hides "who initialized what" inside the manifest merger output. Compliance review requires enumerability, so I'd rather have one more line in Application.onCreate() and print switches, thresholds, and source set into logcat.
Gradle-side isolation is three lines, much cleaner than 1.x's no-op dependency:
// app/build.gradle.kts
android {
// debug-specific implementations only in debug source set; release compilation unit never sees these classes
sourceSets {
getByName("debug") { java.srcDirs("src/debug/java") }
}
}
dependencies {
// detection layer zero third-party dependencies; only AndroidX lifecycle / core
implementation("androidx.core:core-ktx:1.13.1")
debugImplementation("androidx.fragment:fragment-ktx:1.8.2")
}
<!-- app/src/debug/AndroidManifest.xml: debug source set separately merged -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application>
<activity
android:name=".leak.LeakReportActivity"
android:exported="false"
android:label="Leak Report" />
</application>
</manifest>
The entry in Application looks like this, explicit and auditable:
// app/src/main/java/com/example/health/MyApplication.kt
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
if (BuildConfig.DEBUG) {
// reflection to call debug source set implementation; release compilation unit has no such class
runCatching {
Class.forName("com.example.health.leak.LeakDetector")
.getMethod("install", Application::class.java, Boolean::class.java)
.invoke(null, this, true)
}.onFailure { Log.w("LeakDetector", "install skipped", it) }
Log.i("LeakDetector", "debug watcher on, threshold=5/1, dump=off in release")
}
}
}
Using reflection across source sets was Trae's suggestion in round 5. I initially found it roundabout, wanted to put an interface in main. But then the release would also compile in the interface and a blank implementation—no behavior, but another thing to explain when reviewing dependencies. So I went with the reflection. It has a drawback I dutifully recorded in docs/leak-design.md: after R8, Class.forName requires keep rules to preserve the debug class names, and debug builds typically don't enable obfuscation, so it didn't actually trip; if we ever enable minify for debug, that rule needs to be added first.
Rules I Set for Trae
In earlier posts, I wrote Rules first, then started work. Same this time, except this round added a constraint: hprof is sensitive data, must never enter context, let alone the repo.
# .traeignore
**/*.hprof
**/*-stripped.hprof
**/captures/
**/leak-reports/
**/mapping.txt
**/build/outputs/mapping/
app/src/debug/java/**/generated/
**/leak_baseline.tmp.json
Rules live in .trae/rules/leak_rules.md, with globs limiting them to the detection layer:
---
description: Implementation and audit rules for self-built memory leak detection layer
globs:
- "app/src/debug/java/com/example/health/leak/**"
- "app/src/main/java/com/example/health/MyApplication.kt"
- "tools/hprof_*.py"
- "tools/*leak*.sh"
---
# Role and Boundaries
You are helping a medical health class Android App build a self-contained leak detection layer.
The detection layer uses only platform APIs and AndroidX, no third-party detection/analysis libraries.
The off-device parser only does a minimal usable version; when encountering an unrecognized hprof sub-record it must explicitly error, not silently skip.
# Three non-negotiable constraints
1. No third-party library as a solution. Discussing principles may mention LeakCanary / Shark / MAT, but the code must not contain their dependencies or package names.
2. Any heap snapshot leaving the device must first have PRIMITIVE_ARRAY_DUMP zeroed;
reports must not contain string literal values, image pixels, or user identifiers.
3. Release compilation unit must not contain watcher / dumper / analysis code,
only a read-out for retained count; must not claim optimized numbers that haven't been measured.
# Detection Semantics
- The judgment order is fixed: delay → clear queue → force GC → clear queue again → still in table counts as retained.
- Watch weakly reachable, not actual reclamation; must not use finalize() to judge reclamation; must not hold any additional strong reference to the target object.
- Foreground threshold 5, background 1, max one dump per 60s per process; thresholds configurable but must be written into build-info.
# Capabilities and Acceptance
- Off-device parser supports JAVA PROFILE 1.0.3, idSize 4/8, 0x1C segments;
unsupported tags must throw exception and list in report, never guess.
- Each change must give a reproducible verification command with device model / sample size numbers.
- mapping.txt archived in same directory as hprof, but not in version control.
The prompt template is consistently five-part, carried from earlier posts, only constraints changed:
【Role and Boundaries】What project you are in, which layer you may change, what you must not touch
【Objective】This round solves one problem only, define done.
【Context】@ specific files and directories, not the whole repo; attach previous round's output path
【Constraints】apply leak_rules.md; no external libraries, no unstripped heap leaves device, no numbers not measured
【Acceptance】one command or a set of data, with device model, sample size, and definition
Three fixed constraints: "no third-party library / heap snapshot stripped before leaving device / release zero detection code." Pattern is SOLO Agent — after May 2026 when Builder and Coder merged, the old two-stage "first produce a plan, I confirm, then code" pattern is gone, and I ran into that in round 1: Trae wrote all six files in one go, and my prepared "confirm plan" follow-up never got used, so I had to switch to feeding evidence and acceptance in one shot.
Before work, four numbers fixed in docs/metrics-leak.md, each round @ it, no one changes the definition mid-way:
| Number | Definition | Pre-cleanup baseline | Target |
|---|---|---|---|
| false positive rate | false positives / total retained, 40 constructed samples + 20 normal enter/exit | 62% (my handwritten first version) | ≤ 10% |
| true positive recall | 8 known leak sample types caught | 5 / 8 | 8 / 8 |
| dump freeze P90 | Pixel 6, cold 10 rounds, Choreographer dropped-frame timing |
1180ms (synchronous on main thread) | ≤ 700ms |
| release cleanliness | detector class count in release APK / OOM report with retained count ratio | 0 class / 0% | 0 class / ≥ 95% |
The fourth target looks odd, but both ends must hold: one, release has zero detection classes; two, online OOM reports can include the count. My first version put the counter also into the debug source set, so the field was empty in online OOM reports. Trae caught it in round 11 when switching identity for adversarial review.
Twelve Rounds of Prompts, Run in This Order
Twelve rounds isn't twelve "write me a memory leak detector." The first four rounds I didn't let it touch a single line of business code: first scan the objects that "should be reclaimed after destruction" across the project, verify version behavior to primary sources, map the four-step flow to our modules, then define the detection layer interfaces. The middle six rounds landed each component one by one; the last two did regression, pinned CI, and adversarial review from a different identity.
Each round I wrote which mode it ran in, which files were @-ed, the full prompt, expected output files, what I actually reworked, and which command or data set accepted it. Mode always SOLO Agent; prompts use real project paths; all copy-paste ready. Round numbers later went verbatim into docs/CHANGELOG-leak.md and the Skill's workflow stage numbers, so they're fixed once set.
Round 1 · Current State Health Check: Which Objects Should Be Watched
Mode: SOLO Agent, @app/src/main, @app/src/debug, @app/build.gradle.kts, @app/src/main/AndroidManifest.xml.
【Role and Boundaries】
You are doing a read-only health check in our health- class Android App. Do not modify any files.
Goal: prepare an accurate current-state inventory for the self-built leak detection layer. No implementation code.
【Objective】
Produce docs/leak-inventory.md containing four tables:
1) All object types with clear destruction timing (Activity, Fragment, Fragment View,
ViewModel, Service, detached root view, custom Presenter / Manager),
list each with class name, module, which destruction callback, and whether static reference suspected;
2) Existing static singletons, object, companion object holding Context / View /
Listener / coroutine Job locations, with file and line numbers;
3) Current debug vs release dependency differences, especially any dependency that dumps heap, uploads files,
or collects device info;
4) All ContentProvider declarations in AndroidManifest (including ones merged by dependencies),
mark their initialization timing risks.
【Context】
@app/src/main @app/src/debug @app/build.gradle.kts
@app/src/main/AndroidManifest.xml
Package name com.example.health, module M handles report page and medical records.
Focus on module M, other modules only count and typical representative, not full expansion.
【Constraints】
Apply leak_rules.md. Read-only, no code, no third-party libraries.
Do not draw "leak exists" conclusions, only state "there is a lifecycle boundary here."
Uncertain places mark NEED_VERIFY, no guessing.
【Acceptance】
For each entry in table 2, show one adb command or static search command to reproduce the check.
Finally report "how many source files did this health check cover, how many skipped."
Expected output: docs/leak-inventory.md.
My actual rework was on table 4. In its first version, it listed androidx.startup.InitializationProvider as "a ContentProvider we declared ourselves" and suggested changing its onCreate; I pushed back to distinguish "declared in this project's source" from "merged in by dependencies," marking the source artifact path for each. That distinction saved me later: when round 5 discussed auto-install, I could directly flip to that table and say "there are already several providers ahead of Application; don't add one more."
Acceptance commands:
adb shell dumpsys package com.example.health | grep -i -A2 'ContentProvider'
# compare against inventory table 4, confirm each 'project-declared' and 'merge-in' column
grep -rnE 'object |companion object|: Context|: View|Listener' app/src/main/java | wc -l
After round one it reported "covered 214 source files, skipped 3 generated directories"; static reference suspects 37, module M took 19. That number later became the sample pool for false-positive governance.
Round 2 · Online Verification: Verify Version Behavior to Primary Sources
Mode: SOLO Agent (web retrieval on), @docs/leak-inventory.md, @docs/metrics-leak.md.
【Role and Boundaries】
You are establishing a traceable fact base for this self-built detection layer. No implementation code.
Only trust Square official docs, official changelog, Android platform official docs;
community blogs are only leads, conclusions must go back to primary sources.
【Objective】
Produce docs/version-facts-leak.md, each item "fact + primary source URL + date":
1) LeakCanary 1.x vs 2.x detection flow differences: RefWatcher / ObjectWatcher,
HAHA / Shark, separate analysis process / main process, auto-install method, no-op artifact retention;
2) Exact release date of 2.0 final, time and occasion of alpha1, code size change;
3) Default parameters: wait time, foreground threshold, background threshold, notification tap behavior, log text;
4) Debug.dumpHprofData applicability, ART behavior during dump, file write requirements;
5) ReferenceQueue semantics: order of weakly reachable vs reclaimed, why finalization is not a judgment;
6) Current stable and 3.0 alpha status, and the exact known compatibility issue between 2.8~2.13 and WorkManager;
7) hprof binary top-level tags, 0x1C sub-record tags, Android extension tag list.
【Context】
@docs/leak-inventory.md @docs/metrics-leak.md
Known easy-to-wrong points: many online tutorials say 2.0 released in 2020,
treat LeakSentry as the release API. Specifically verify these two and give conclusion.
【Constraints】
Apply leak_rules.md. Every fact must have URL; when two sources conflict, list both,
don't pick one as fact, don't blur into "gradually" type vague phrasing.
Uncertain write UNCONFIRMED, don't fabricate versions and dates.
【Acceptance】
Output a table "common wrong claim → accurate statement from primary source", at least 6 rows.
Finally list all URLs actually opened.
Expected output: docs/version-facts-leak.md.
Two reworks, both written into the post. First, the 2.0 date: it found several Chinese tutorials and wrote "2020 release of 2.0"; I sent it back to official changelog and history pages, and changed to 2019-11-27 release, 2019-04-23 06:43 Paris time alpha1, separating LeakSentry (alpha name) from release AppWatcher in one row. Second, cross-topic date conflicts like the 16KB page table; it habitually blurred into "gradually forced," so I made it list two columns side by side, not pick one as fact.
Acceptance used the "wrong claim vs accurate" table row count, plus one local check:
grep -c '^|' docs/version-facts-leak.md
grep -nE '2019-11-27|2019-04-23|LeakSentry|AppWatcher|前台|阈值' docs/version-facts-leak.md
Round 3 · Principle and Asset Mapping: Put the Four-Step Flow onto Module M
Mode: SOLO Agent, @docs/leak-inventory.md, @docs/version-facts-leak.md, @app/src/main/java/com/example/health/report/.
【Role and Boundaries】
You do architecture mapping, produce design document, no implementation code.
Readers are another Android dev and a compliance-review colleague, neither read LeakCanary source.
【Objective】
Produce docs/leak-design.md containing:
1) A four-step flow diagram (Mermaid): detect retained → dump → analyze → classify,
each step marked which file of ours handles and which platform API is called;
2) Boundary table between detection and analysis layers: which capabilities we implement,
which shrink to minimal version, which explicitly not done, each with reason;
3) "One key walks the whole path" comparison table: UUID's shape in watchedKeys, ReferenceQueue,
hprof, leak trace, group signature;
4) Privacy boundary section: what data enters hprof, where stripping happens,
which capabilities fail after stripping, under what conditions file may leave device;
5) What release side keeps only, why, how to verify it didn't mix in other classes;
6) Four metric numbers' definition and measurement, directly referencing docs/metrics-leak.md, no rewriting.
【Context】
@docs/leak-inventory.md @docs/version-facts-leak.md
@app/src/main/java/com/example/health/report/
Current project state: debug build must not have third-party dependencies that export full heap;
release build must not have detection code; online OOM reports want retained count.
【Constraints】
Apply leak_rules.md. Detection layer zero third-party dependencies; analysis layer must not promise
covering all ART / vendor heap formats; don't put "auto-install" in solution, write the reason.
Design doc must not contain TODO, placeholders, or "let someone fill in" wording.
【Acceptance】
Compliance colleague can answer from chapter 4 alone "does hprof have user data, how handled";
another dev can answer from chapter 2 alone "why we don't do dominator tree."
End of document give a row-by-row correspondence table between this design and official four-step flow.
Expected output: docs/leak-design.md.
First version wrote chapter 2 as a "capability comparison table" and casually promised retained size and native memory attribution—those are DominatorTree and AndroidNativeSizeMapper jobs in Shark, and my off-device script never planned to do them. I pushed back and added the constraint: "anything you don't plan to implement in rounds 8~9, put in the 'explicitly not done' column with reason." After redoing, the table was useful. Second rework was chapter 4: it wrote "stripping" as a one-line principle without saying that zeroing PRIMITIVE_ARRAY_DUMP removes string literals but leaves reference chains intact. I made it spell out that causality.
Acceptance method was crude but effective: send chapter 4 to the security colleague; she replied "understandable, no need to ask more," and the round passed.
Round 4 · Minimal ObjectWatcher: Write the Probe
Mode: SOLO Agent, @docs/leak-design.md, @docs/version-facts-leak.md.
【Role and Boundaries】
You only implement the innermost core class of the detection layer, no lifecycle mounting, no dump, no UI.
Target: app/src/debug/java/com/example/health/leak/.
【Objective】
Produce two files:
- KeyedWeakReference.kt: extends WeakReference<Any>, with key(UUID),
description, watchUptimeMs fields, binds ReferenceQueue at construction;
- ObjectWatcher.kt: provides watch(Any, String), removeWeaklyReachableObjects(),
moveToRetained(key), retainedObjectCount.
【Context】
@docs/leak-design.md @docs/version-facts-leak.md
The judgment order must strictly be: delay → clear queue → force GC → clear queue again →
still in table counts as retained. Watch weakly reachable, not actual reclamation.
Refer to the official design doc's "watch then confirm" section, but write code yourself.
【Constraints】
Apply leak_rules.md. Only JDK + Android SDK platform APIs, zero third-party dependencies.
watchedKeys must be thread-safe; must not create any extra strong reference to watchedObject
(including logging that concatenates it, including putting it in any closure or collection).
Must not use finalize(); must not treat "reference not cleared" as leak judgment.
Delay and GC constants as constructor parameters, default 5 sec, for test injection of fake clock.
【Acceptance】
Attach a directly runnable JVM unit test (no Android device needed):
1) an object no longer referenced should not count as retained after forced GC;
2) an object held by a static field should count as retained;
3) same object watched twice counts only once;
4) give an injection example "use fake clock to compress 5 sec into 0."
Explain which case corresponds to which judgment step above.
Expected output: KeyedWeakReference.kt, ObjectWatcher.kt, ObjectWatcherTest.kt.
This round's rework is the most typical and worth recording: in the first version it wrote Log.d("Leak", "watching $watchedObject") inside watch(). String interpolation calls toString(), which doesn't permanently hold the object but already violates the "no extra reference" rule; worse, some toString() implementations read fields or even throw. I made it log only description and key. Second rework: moveToRetained only cleared the queue once at the start, missing the second clear after GC — exactly the mistake my October 8 handwritten version made. Pasting the whole judgment order into the prompt's 【Context】 was the only way to suppress it.
Acceptance was those four unit tests, plus one local search:
./gradlew :app:testDebugUnitTest --tests '*ObjectWatcherTest*'
grep -n 'watchedObject' app/src/debug/java/com/example/health/leak/*.kt
# check no second place uses target object besides constructing KeyedWeakReference
Round 5 · Lifecycle Mounting: Who Hands Over the Object When
Mode: SOLO Agent, @app/src/debug/java/com/example/health/leak/ObjectWatcher.kt, @docs/leak-inventory.md, @app/src/main/java/com/example/health/MyApplication.kt.
【Role and Boundaries】
You implement lifecycle mounting and explicit install entry, only debug source set and MyApplication's switch,
no business code, no XML layout changes.
【Objective】
Produce:
- LeakWatchers.kt: register Application.ActivityLifecycleCallbacks to watch
onActivityDestroyed; use AndroidX FragmentManager's FragmentLifecycleCallbacks
to watch onFragmentViewDestroyed and onFragmentDestroyed; watch root view after View.onDetachedFromWindow;
watch ViewModel.onCleared. Each object type gives a distinguishable description.
- LeakDetector.kt: install(Application, Boolean) explicit entry, wires watcher, trigger, dumper,
prints switch, thresholds, source set into logcat;
- MyApplication.kt debug branch call (reflection across source sets, reason in comment);
- app/src/debug/AndroidManifest.xml with an exported=false report page declaration.
【Context】
@app/src/debug/java/com/example/health/leak/ObjectWatcher.kt
@docs/leak-inventory.md (table 1 is object list, cover each, list uncovered in doc)
@app/src/main/java/com/example/health/MyApplication.kt
【Constraints】
Apply leak_rules.md. Must not use ContentProvider auto-install,
reason: main thread, earlier than Application.onCreate, hides initialization into merge output;
must be able to see "what was installed" at a glance in logcat.
No third-party libraries; Fragment / ViewModel only AndroidX;
same object must not be double-watched by two callbacks (give dedup strategy and explain).
Permissions and notifications: use native AlertDialog to explain purpose before requesting, no silent behavior.
【Acceptance】
Give adb command sequence: open report page, press back, after 5 sec see Watching / Retained two lines in logcat;
and give a "rotate screen three times" repeated-mount check command to confirm no duplicate watch.
Expected output: LeakWatchers.kt, LeakDetector.kt, modified MyApplication.kt, debug manifest.
Two reworks. One: it watched both the Fragment's view and the Fragment itself; the same onDestroyView scenario double-counts. I made it dedupe with identityHashCode over a short window, and wrote in docs/leak-design.md that "view and fragment are two independent pieces of evidence, but one destruction counts as one retained." Two: cross-source-set. It initially put an import of the debug class in main, which wouldn't compile; after switching to reflection, it forgot the R8 keep note. I made it write that risk into the comment and docs/leak-design.md, not hide it.
Acceptance commands:
adb logcat -s LeakDetector LeakWatcher | grep -E 'Watching|Retained|install'
# Watching instance of ... (Activity received Activity#onDestroy() callback)
# 5 sec later: Scheduling check for retained objects because found new object retained
adb shell am start -n com.example.health/.report.ReportActivity
adb shell input keyevent 4 # back, triggers onDestroy
Round 6 · Confirmation Logic and Thresholds: Push Down the False Positives
Mode: SOLO Agent, @app/src/debug/java/com/example/health/leak/, @docs/metrics-leak.md.
【Role and Boundaries】
You only change confirmation logic and trigger strategy, not ObjectWatcher's watch() semantics,
no dump implementation, no UI.
【Objective】
Produce:
- GcConfirmer.kt: replace hardcoded Thread.sleep(100) with "poll at most 5 times, 20ms each, exit when hit"
enqueue wait, and explain why Runtime.gc() doesn't guarantee immediate enqueue;
- DumpTrigger.kt: foreground 5 / background 1 thresholds, app visibility listener,
60-sec per-process rate limit, tap notification immediate dump, thresholds configurable and written into build-info;
- docs/false-positive.md: list at least 12 false-positive scenarios,
each with "phenomenon → root cause → how to exclude in judgment," including config changes,
delayed messages, coroutine Jobs, known system leaks, WeakReference cleared early.
【Context】
@app/src/debug/java/com/example/health/leak/
@docs/metrics-leak.md (false positive target ≤ 10%, definition not to change)
First handwritten version's false positive 62%, main cause missed second poll after GC.
【Constraints】
Apply leak_rules.md. Must not loosen judgment to chase numbers (e.g., extend wait to 30 sec),
only change confirmation logic; must not silently swallow exceptions.
Visibility uses Application.ActivityLifecycleCallbacks, no third-party library.
All thresholds centralized in one Config data class for real-device regression switching.
【Acceptance】
Use 40 constructed samples + 20 normal enter/exit to re-measure false positive rate, give
Pixel 6 and Redmi Note 11 grouped numbers, write sample composition;
give one command to dump the currently active Config.
Expected output: GcConfirmer.kt, DumpTrigger.kt, docs/false-positive.md.
This round had a misjudgment on my side: Trae proposed raising the wait from 5 to 8 seconds to cut false positives. At first glance it seemed reasonable, I almost approved. But per docs/metrics-leak.md's definition, the false positive rate would drop, but true positive recall would drop along with it — the report page's leak only stabilized after 5 seconds; waiting 8 seconds let the system reclaim some intermediate objects more easily. I made it write "widening the judgment" explicitly into the negative-example column of false-positive.md, marked "numbers look better but sacrifice recall." That kind of rework is worth more than fixing a bug.
Acceptance numbers: Pixel 6 false positive 62% → 9%, Redmi Note 11 65% → 11%, recall 5/8 → 8/8. The second machine slightly exceeded the 10% target; I didn't let it tune parameters to mask it, but marked in the report "low-memory model still 1 point over, reason system reclamation more aggressive, leave for next round."
Round 7 · Dump and Freeze Control: Close the Cost Inside the Background Thread
Mode: SOLO Agent, @app/src/debug/java/com/example/health/leak/DumpTrigger.kt, @docs/leak-design.md.
【Role and Boundaries】
You implement HeapDumper and pre-processing stripping, only debug source set changes.
Don't touch ObjectWatcher, off-device parser, or business code.
【Objective】
Produce:
- HeapDumper.kt: use Debug.dumpHprofData to write heap to app private dir
(context.filesDir/leak/), execute on HandlerThread, failure must have clear error code and logcat output,
no silent;
- HprofSanitizer.kt: first thing after dump, traverse 0x1C segments' PRIMITIVE_ARRAY_DUMP
sub-records, zero content bytes, rewrite file, immediately delete original; externally only stripped file;
- a native AlertDialog purpose explanation: before first dump in debug build, tell user
"will capture app memory snapshot, may briefly pause, file only stored on device, has been stripped,"
confirm before executing; use AlertDialog, no third-party popup library;
- docs/dump-cost.md: record ART behavior during dump, why freeze can't be eliminated,
what compensation we did, what we didn't.
【Context】
@app/src/debug/java/com/example/health/leak/DumpTrigger.kt
@docs/leak-design.md (chapter 4 is privacy boundary, follow it strictly)
Project constraint: hprof's String is backed by primitive array, contains patient names,
ID numbers, tokens; after stripping, reference chain must still be readable.
【Constraints】
Apply leak_rules.md. Three hard constraints all in effect, especially "any heap snapshot leaving device
must first zero PRIMITIVE_ARRAY_DUMP."
Must not write external storage, must not upload to any service, must not enter version control.
Zero third-party dependencies; no Shark / HAHA / MAT classes.
【Acceptance】
Give adb command: trigger one dump → pull stripped file → use strings to search three sensitive field types,
must be empty; then use off-device parser to read same file, confirm GC Root and reference chains still resolve.
Also give ten cold dropped-frame timings, report P50 / P90 with device model.
Expected output: HeapDumper.kt, HprofSanitizer.kt, docs/dump-cost.md, first-dump purpose dialog.
Two reworks, both privacy boundaries. First, it made stripping "dump then write a -stripped.hprof, leave the original in the original directory for next-round cleanup" — that leaves an unstripped full heap on the device, which the security colleague would never pass. I made it "rewrite in place + immediately delete original + only one output file." Second, it wanted to compute a file hash before stripping for archiving. I cut that too: the hash itself doesn't leak content, but that code path would briefly hold a full read of the unstripped file, no need.
Acceptance commands and results:
adb shell am broadcast -a com.example.health.DEBUG_DUMP # debug-only
adb pull /data/data/com.example.health/files/leak/ /tmp/leak-check/
strings /tmp/leak-check/*.hprof | grep -E '身份证|就诊人|Bearer |token' | wc -l
# 0
python3 tools/hprof_min.py /tmp/leak-check/*.hprof --roots | head -12
# still lists ROOT_STICKY_CLASS / ROOT_JAVA_FRAME / ...
Pixel 6 ten cold rounds, freeze P50 590ms, P90 640ms, better than first version's synchronous main-thread 1180ms, but I didn't write it as "optimized by half" — the freeze itself didn't shorten, it just stopped blocking interaction; these two numbers aren't the same metric, report wrote them on separate lines.
Round 8 · Off-device Minimal hprof Parser: Only Do What Can Be Verified
Mode: SOLO Agent, @docs/version-facts-leak.md (section 7's tag table), @docs/leak-design.md.
【Role and Boundaries】
You write a minimal hprof parser in Python on dev machine / CI,
only "build index + build edges + find path", no dominator tree, no retained size, no native attribution.
Write into tools/, don't touch App code.
【Objective】
Produce tools/hprof_min.py, command-line parameters:
--index only Pass1, print record statistics and GC Root count
--find KEY find KeyedWeakReference instance and output target object id
--path ID BFS output shortest strong reference path from GC Root to that id
--strict immediately error on unsupported tag and list offsets parsed so far
Support:
header JAVA PROFILE 1.0.3, idSize 4 or 8, timestamp;
top-level 0x01 / 0x02 / 0x04 / 0x05 / 0x0C / 0x1C / 0x2C;
0x1C internal ROOT_* eight kinds + 0xFE HEAP_DUMP_INFO;
0x20 CLASS_DUMP / 0x21 INSTANCE_DUMP / 0x22 / 0x23;
Basic Type 2=object (only this writes edges), others skip by length.
Pass1 builds "id → file offset / class name / field layout / root set",
Pass2 random seek by offset parses field byte stream and builds edge table.
【Context】
@docs/version-facts-leak.md @docs/leak-design.md
Note: HEAP_DUMP_SEGMENT sub-records have no length field,
must advance cursor by sub-tag's own structure; idSize must be read from header, not hardcoded.
【Constraints】
Apply leak_rules.md. Only Python standard library (struct / mmap / argparse / json).
Must not silently skip unknown tag; must not guess vendor private tag layout.
Capability boundary written in file header comment and --help, explicitly list "what this tool doesn't provide."
Must not print hprof content to stdout, only ids, class names, field names, paths.
【Acceptance】
Self-test with two samples: one Pixel 6 / Android 13 / idSize 8,
one emulator / Android 11 / idSize 4.
Give each Pass1 record count, object count, GC Root count, parse time and peak memory;
and a command to verify "corrupting one byte makes --strict error rather than give wrong path."
Expected output: tools/hprof_min.py.
This round hit the densest pitfalls, most like real binary parsing. First version had this line:
# wrong way
strings[rid()] = f.read(length - id_size).decode()
Python evaluates the right side first; f.read() ate the file pointer, so rid() took 4 bytes from the next record's header as key — no exception, just silent misalignment, parsed class names all garbage. I made it read id first, then bytes, plus an assertion that cursor position is correct after reading.
Second rework: treating 0x1C sub-records as top-level records reading length, flying off from record two. Third: hardcoding idSize to 4, wrong on 64-bit. Fourth: not handling 0xFE HEAP_DUMP_INFO, crashing every Android 13 dump. All four pitfalls went into the later pitfall table.
Acceptance data: Pixel 6's 96MB stripped heap, Pass1 ~4.1 sec, peak memory 38MB; emulator's 41MB, 1.7 sec, 17MB. Orders of magnitude match Shark's 40MB, but I didn't dare write "performance close to Shark" — I only did two-pass scan and BFS; it has virtual reference reading, dominator tree, object inspectors, not the same.
python3 tools/hprof_min.py captures/report.hprof --index
python3 tools/hprof_min.py captures/report.hprof --find <key> --path --strict
printf '\x00' | dd of=captures/broken.hprof bs=1 seek=64 conv=notrunc
python3 tools/hprof_min.py captures/broken.hprof --index --strict # must exit non-zero
Round 9 · Shortest Path and State Annotation: Make Reference Chain Readable
Mode: SOLO Agent, @tools/hprof_min.py, @docs/version-facts-leak.md.
【Role and Boundaries】
You add shortest path and annotation to the off-device parser, no new parsing capability, no App code change.
【Objective】
Produce:
- tools/leak_trace.py: BFS from all GC Roots, backtrack path after finding target id;
output format requires Root at top, one reference per line, object state annotated beside;
- State annotation rules: Leaking: YES / NO / UNKNOWN three states,
at least implement these criteria: Activity and mDestroyed=true → YES;
Fragment and mFragmentManager=null → YES;
View and mContext points to destroyed Activity → YES;
system classes / Thread / Class objects → NO; others UNKNOWN;
- Virtual reference flattening: display internal structures like ArrayList.elementData,
HashMap.table, Object[] indices as "the way it looks in code",
array index normalized to [x], avoid same leak splitting into multiple rows due to different index;
- Suspicious reference marking: mark the 1~3 references closest to leaked object
with ~~~, and explain selection basis.
【Context】
@tools/hprof_min.py @docs/version-facts-leak.md
Refer to the official report's typical output, but write code yourself;
GC Root type names must correspond to hprof sub-tag table one-to-one.
【Constraints】
Apply leak_rules.md. Must not output any field's literal value (stripped anyway),
only class names, field names, state labels.
BFS first hit returns, no "find better path" continue traversing.
When insufficient criteria, honestly write UNKNOWN, not guess YES.
【Acceptance】
Run each of the 8 constructed leak sample types from round 6,
give path length, GC Root type hit, number of YES nodes;
construct one heap with "same leak appears 4 times", verify after index normalization only 1 row.
Expected output: tools/leak_trace.py.
One rework: index normalization. First version concatenated Object[].[3] raw into the signature, same leak four times printed four rows — exactly the round-9 problem I mentioned at the start, official doc says it clearly, it still missed. I pasted the official example sha1Hash(... + "java.lang.Object[].[x]") into 【Context】, redo came out right. Another small rework: state annotation too aggressive — it flagged an ArrayList as YES because "it's on the leak path." I made the criteria strict: only objects with clearly ended lifecycle get YES, everything else UNKNOWN; rather under-mark than mislead.
Round 10 · Report, Group Signature, and Stripping Re-check
Mode: SOLO Agent, @tools/leak_trace.py, @app/src/debug/java/com/example/health/leak/, @docs/leak-design.md.
【Role and Boundaries】
You string all previous outputs into a human-readable report and add stripping regression test.
No new detection capability, no judgment semantic change.
【Objective】
Produce:
- tools/leak_report.py: read trace output, group by signature,
generate leak-reports/<date>-<build>.md and a JSON summary;
signature = sha1(concatenation of all suspicious references in path), array index normalized;
- Report must contain: build info, device and OS version, dump timestamp,
each leak's shortest path, state annotation, suspicious reference, group count,
and "this analysis is out of supported range" part (if any);
- Report classification: Application Leak (our code issue) vs
Library Leak (known system / third-party issue), latter from
assets/known-leaks.txt whitelist match, not in blocking items;
- tests/test_sanitizer.py: stripping regression, construct heap sample with name, ID, token,
assert strings search empty after sanitize, and reference chain still resolves; run every version.
- Report opening line "this evidence collection was performed after stripping,"
and list which hprof sub-record types the stripping step affects.
【Context】
@tools/leak_trace.py @docs/leak-design.md
@app/src/debug/java/com/example/health/leak/HprofSanitizer.kt
Known whitelist: Android 12's UiModeManager, AOSP PermissionControllerManager type,
each with source and affected version.
【Constraints】
Apply leak_rules.md. Report must not contain string literals, image pixels, user identifiers;
must not put hprof, mapping, report directory into version control;
must not claim "zero false positives," whitelist match must explicitly list which item hit.
【Acceptance】
Give one command to generate report from a real dump, one command to run stripping regression;
report's field count, group count, whitelist hit count must be reproducible by script.
Expected output: tools/leak_report.py, tests/test_sanitizer.py, assets/known-leaks.txt.
This round I added an unexpected requirement: the report's opening line "this evidence collection was performed after stripping." Reason: compliance colleague asked "how do I know this report corresponds to the stripped file" — one sentence, but without it she'd have to dig through scripts. Trae first put stripping info in an appendix at the end of the report; I moved it to the first line.
The stripping regression test actually caught a regression later: someone temporarily added a "keep first 8 chars of string for identification" switch to debug a problem, and the test failed immediately. I wrote that into docs/CHANGELOG-leak.md with the note "don't open backdoors for debugging convenience."
python3 tools/leak_report.py captures/report.hprof --build 8.2.2-312 --out leak-reports/
python3 -m unittest tests.test_sanitizer -v
grep -cE '^\| ~~~|Leaking: YES' leak-reports/*.md
Round 11 · Real Device Regression and False-positive Governance: Two Machines, Eight Sample Types
Mode: SOLO Agent, @docs/metrics-leak.md, @docs/false-positive.md, @app/src/debug/, @app/src/main/.
【Role and Boundaries】
You are responsible for regression scripts and sample project, don't change judgment semantics,
don't relax threshold, don't change definition. Goal is to speak with data, not beautify numbers.
【Objective】
Produce:
- app/src/debug/java/.../LeakSamples.kt: 8 manually triggerable constructed leaks
(static Activity reference, unregistered Listener, Handler delayed message,
coroutine Job holding, View in singleton, anonymous inner class this$0,
ThreadLocal not cleared, broadcast receiver registered not unregistered),
each a debug entry, marked expected path shape;
- tools/run_leak_suite.sh: scripted scenario (force-stop → cold start →
fixed sequence enter/exit → trigger dump → pull file → generate report),
two machines each 10 rounds, output metrics-leak.json;
- docs/regression-leak.md: four metric numbers before/after comparison,
each machine grouped, write sample size, OS version, cold or not;
over-target items explicitly marked, no rounding away;
- release side check: unpack release APK, confirm dex has no
KeyedWeakReference / ObjectWatcher / HeapDumper / HprofSanitizer,
and confirm OOM report metadata can read retainedObjectCount.
【Context】
@docs/metrics-leak.md (four numbers' definition, not one word changed)
@docs/false-positive.md @app/src/debug/ @app/src/main/
Devices: Pixel 6 / Android 13, Redmi Note 11 / Android 11.
First handwritten baseline: false positive 62% / 65%, recall 5/8.
【Constraints】
Apply leak_rules.md. Must not modify judgment or extend wait to meet target;
must not count Library Leak in false positive rate's numerator;
release check must give reproducible unpack and search commands, not just conclusion.
【Acceptance】
Four numbers each listed "target / measured / pass or not / reason if not";
release check gives dex string search output snippet.
Expected output: LeakSamples.kt, tools/run_leak_suite.sh, docs/regression-leak.md, metrics-leak.json.
One number I didn't let it beautify: Redmi Note 11's false positive 11%, 1 point over target. Trae proposed classifying that machine's three false-positive samples into "system aggressive reclamation" and removing from numerator. I refused — changing the definition would invalidate all previous rounds' comparisons. The report just writes 11%, notes not met and why.
The release check command was what the security colleague cared about most:
unzip -p app/build/outputs/apk/release/app-release.apk classes.dex > /tmp/r.dex
strings /tmp/r.dex | grep -E 'KeyedWeakReference|HeapDumper|HprofSanitizer|dumpHprofData' | wc -l
# 0
strings /tmp/r.dex | grep -E 'retainedObjectCount|ReleaseRetainedCounter' | head -3
# only count read-out remains
Round 12 · Freeze the Twelve Rounds into a Skill, Then Pin into CI
Mode: SOLO Agent, @docs/, @tools/, .trae/rules/leak_rules.md, @app/src/debug/java/com/example/health/leak/.
【Role and Boundaries】
This round adds no new feature. You freeze the entire flow from rounds 1-11 into
an AI Skill that Trae can call repeatedly, wire it into CI, then switch identity
for an adversarial review of the whole thing.
【Objective】
Produce .trae/skills/leak-detector/ full skill package:
SKILL.md (with name / description frontmatter, description has trigger words),
references/ three quick-reference docs, templates/ three templates,
scripts/ three scripts, checklists/ two checklists;
Produce .github/workflows/leak-gate.yml:
each PR run unit test, stripping regression, release cleanliness search, four-number gate;
Produce docs/adversarial-review.md: switch to three identities to pick at each:
A compliance reviewer: question whether any path allows personal data to leave device;
B another Android dev: question false positives, multi-process, post-obfuscation readability;
C someone who never used this tool: can they locate which line to change just from report.
Each identity at least 5 questions, give evidence file path and conclusion;
for unanswered questions mark OPEN, no hand-waving.
【Context】
@docs/ (leak-design / version-facts-leak / metrics-leak /
false-positive / regression-leak / CHANGELOG-leak)
@tools/ @.trae/rules/leak_rules.md
@app/src/debug/java/com/example/health/leak/
Round numbers 1-12 must match docs/CHANGELOG-leak.md, no reorder.
【Constraints】
Apply leak_rules.md. SKILL.md must not contain full implementation code,
only trigger conditions, workflow stages, input/output contract, acceptance gates, and material pointers;
description must contain hit-able trigger words, not generic like "memory optimization related."
CI must not upload any hprof or report artifacts; must not write "let someone fill in" wording.
Adversarial review must not have you both question and pass; each conclusion points to a specific file
and a re-runnable command.
【Acceptance】
Give reproduction steps for "in an empty project, install only this Skill, feed one trigger phrase";
give actual output snippets of CI's four gates;
list all still-OPEN items from adversarial-review, not a single one hidden.
Expected output: .trae/skills/leak-detector/ full directory, .github/workflows/leak-gate.yml, docs/adversarial-review.md.
This round reworked three times, all skill-related. CI had one issue: first version uploaded leak-reports/ as an artifact for "view on web" — directly violating constraint three; I made it only print the summary JSON in CI logs, artifacts stay on runner and destroyed with job.
Adversarial review ended with 3 OPEN items: multi-process watcher ownership, debug minify keep rules, low-memory machine's 1-point false positive. All three written to "places to dig further," not faking resolution in the post.
python3 .trae/skills/leak-detector/scripts/verify_skill.py
# SKILL.md frontmatter OK / trigger words OK / references complete 12/12 / scripts executable 3/3
./gradlew :app:testDebugUnitTest && python3 -m unittest tests.test_sanitizer
bash .trae/skills/leak-detector/scripts/check_release.sh app-release.apk
Freezing the Twelve Rounds into a Skill
After twelve rounds, things exist, but the problem followed. Two weeks later a neighboring team colleague asked if they could borrow the flow for their project. I flipped through chat logs and found it wasn't transferable: round 3's boundary conclusion was buried in a follow-up question, round 6's "don't loosen judgment" rework only I knew, round 7's "immediately delete original file" came from a single security colleague question. A different project, a different conversation window — all those constraints would be re-explained, and likely missed.
Rules couldn't catch this. .trae/rules/leak_rules.md constrains "what the written code looks like," not "what order to work in, what to hand over at each stage, what counts as done." What I needed was one layer above: an ability package that can be triggered by a single phrase, with its own material index, workflow stages, and acceptance scripts. In Trae that's the Skill.
The directory is arranged by "progressive disclosure" — SKILL.md only holds routing and contracts, details go into on-demand-loaded references/, templates and scripts separate, so context isn't bloated upfront:
.trae/skills/leak-detector/
├── SKILL.md # only entry, ~120 lines
├── references/
│ ├── principles.md # weakly reachable / four-step flow / judgment order
│ ├── hprof-format.md # record tag table, GC Root types, Basic Type
│ ├── version-timeline.md # 1.x → 3.0 alpha behavior differences and common wrong claims
│ └── privacy-redline.md # medical data stripping red line and three hard constraints
├── templates/
│ ├── prompt-five-part.md # role/boundary / objective / context / constraint / acceptance
│ ├── watcher.kt.tpl # KeyedWeakReference + ObjectWatcher skeleton
│ └── leak-report.md.tpl # report template, first line fixed with stripping declaration
├── scripts/
│ ├── verify_skill.py # self-check: frontmatter / trigger words / references complete / scripts executable
│ ├── hprof_min.py # off-device minimal parser (copy of round 8 output)
│ └── check_release.sh # unpack release APK, search detection classes
└── checklists/
├── acceptance.md # 12 acceptance items, bound to four metric numbers
└── adversarial.md # three identity adversarial review question list
The full SKILL.md below; the frontmatter is the key to being triggered correctly:
---
name: leak-detector
description: >-
Complete workflow for building an Android memory leak detection layer with platform APIs.
Use when user says "implement LeakCanary myself" "build my own leak detection" "remove third-party memory detection dependency"
"analyze hprof / leak reference chain" "how to integrate leak detection into project and CI" "make leak debugging flow into skill package".
Produces zero-third-party ObjectWatcher, lifecycle mounting, heap stripping, off-device shortest reference chain parsing,
grouped report and CI gate; built-in privacy stripping red line, false-positive governance and adversarial review.
Not suitable for native memory analysis, performance lag diagnosis, or directly adding existing LeakCanary dependency.
---
# Self-built Leak Detection Layer
## When to use / when not to use
Use: need an auditable, zero-third-party, CI-ready leak detection;
need to read or build hprof reference chain; need to break someone else's encapsulation into your project.
Don't use: just want one line debugImplementation and done;
native memory (that's heapprofd's job, not hprof);
frame rate / startup time diagnosis.
## Input contract
Before work, require user to provide and @ these files; if missing, fill in round 1:
- project source directory (at least one module), build.gradle(.kts), AndroidManifest
- lifecycle object list (if none, S1 generates)
- version fact table (if none, S2 generates online)
- metric definitions (if none, this skill generates default four numbers, write into docs/metrics-leak.md)
If user gives no privacy requirement, follow strictest default: heap snapshot never leaves device.
## Workflow (stage number = prompt round, no reorder)
S1 health check → docs/leak-inventory.md, read-only, no conclusion
S2 online verify → docs/version-facts-leak.md, every fact with primary source URL
S3 principle & asset → docs/leak-design.md, write clearly "explicitly not done" capabilities
S4 minimal Watcher → KeyedWeakReference / ObjectWatcher + 4 JVM unit tests
S5 lifecycle mount → LeakWatchers / explicit install, refuse auto-install
S6 confirmation & threshold → GcConfirmer / DumpTrigger / false-positive.md
S7 dump & strip → HeapDumper / HprofSanitizer / purpose AlertDialog
S8 off-device parser → tools/hprof_min.py, only Pass1 + Pass2 + BFS
S9 shortest path annotation → tools/leak_trace.py, three-state annotation + index normalization
S10 report & regression → group signature, whitelist, stripping regression test
S11 real-device regression → two machines each 10 rounds, four numbers each "target/measured/pass"
S12 freeze & gate → this skill self-check, CI four gates, three-identity adversarial review
Each stage must produce an acceptable file; no output means stop here, don't jump.
Stage meaning and rework records in docs/CHANGELOG-leak.md.
## Three non-negotiable constraints
C1 Detection layer only platform APIs and AndroidX, no third-party detection library in code.
C2 Any heap snapshot leaving device must first zero PRIMITIVE_ARRAY_DUMP,
original file immediately deleted; reports must not contain string literals or user identifiers.
C3 Release compilation unit must not contain watcher / dumper / analysis code,
only one retained count read-out.
Violating any, whether code runs or not, this stage fails.
## Output contract
docs/ under 7 documents, app/src/debug/.../leak/ under 6 Kotlin files,
tools/ under 3 scripts, tests/ under 1 stripping regression, CI yaml 1,
metrics-leak.json 1. Full list in checklists/acceptance.md.
## Acceptance gates
False positive rate ≤ 10% (40 constructed samples + 20 normal enter/exit, each machine)
True positive recall 8/8
dump freeze P90 ≤ 700ms (ten cold rounds, write device model and timing definition)
release detector classes 0 / OOM report with retained count ≥ 95%
Over-target items must be listed as-is, no parameter tuning to mask, no definition change.
Run: python3 scripts/verify_skill.py && bash scripts/check_release.sh <apk>
## Failure fallback
Off-device parser encounters unsupported tag: --strict throws and lists offset,
report marks "this analysis out of supported range", no guessing layout, no silent skip.
Real device can't run cold: write device and OS version, mark that round INVALID and re-run.
Any unsure fact: write UNCONFIRMED, keep both conflicting sources.
## How to iterate this skill
Each new false-positive type, add one entry to references/principles.md and
checklists/adversarial.md, record round in CHANGELOG;
each platform version behavior change, update version-timeline.md and rerun S2;
description trigger words only add, never delete, then run verify_skill.py.
I reworked this Skill three times, none of them code.
First was description written as "development spec for Android memory optimization." Sounds professional; but feeding "help me build my own LeakCanary" doesn't trigger it. Skill matches by words in description; writing abstractly means it's as if not written. Changed to now, stuffing all the ways users actually say it, plus the "not for" half to avoid being pulled in when diagnosing lag.
Second was me putting full text of ObjectWatcher.kt and hprof_min.py into SKILL.md, thinking "one file to grab and use." But every trigger then reads two to three hundred lines of implementation into context, eating budget before starting, and when code changes the skill copy goes stale. Changed to only path pointers in SKILL.md, implementations stay in project, templates in templates/. The criterion is simple: anything that changes doesn't go into SKILL.md, only contracts that rarely change.
Third was no acceptance script. Earlier versions ran and Trae declared "all stages complete," I flipped files and found the stripping regression in S7 never ran, and S11's two metrics were fabricated to match targets. After adding verify_skill.py, it checks actual filesystem products — frontmatter fields, trigger word count, references/ existence, three scripts executable, four numbers from metrics-leak.json not from a text sentence. AI claiming completion doesn't count; script says so.
# .trae/skills/leak-detector/scripts/verify_skill.py (excerpt)
import pathlib, re, sys, json
root = pathlib.Path(__file__).resolve().parents[1]
text = (root / "SKILL.md").read_text(encoding="utf-8")
problems = []
fm = re.match(r"^---\n(.*?)\n---\n", text, re.S)
if not fm:
problems.append("SKILL.md missing frontmatter")
else:
block = fm.group(1)
if "name: leak-detector" not in block:
problems.append("name mismatch")
triggers = ["自己实现 LeakCanary", "自己撸一套", "hprof", "CI"]
missing = [t for t in triggers if t not in block]
if missing:
problems.append(f"description missing trigger words: {missing}")
if len(text.splitlines()) > 200:
problems.append("SKILL.md over 200 lines, implementation should move to templates/")
for rel in [
"references/principles.md", "references/hprof-format.md",
"references/version-timeline.md", "references/privacy-redline.md",
"templates/prompt-five-part.md", "templates/watcher.kt.tpl",
"templates/leak-report.md.tpl", "checklists/acceptance.md",
"checklists/adversarial.md",
]:
if not (root / rel).is_file():
problems.append(f"missing reference file: {rel}")
metrics = pathlib.Path("metrics-leak.json")
if not metrics.is_file():
problems.append("missing metrics-leak.json, four numbers not allowed to only live in docs")
else:
data = json.loads(metrics.read_text(encoding="utf-8"))
for key in ["false_positive_rate", "recall", "dump_freeze_p90_ms",
"release_detector_classes", "oom_with_retained_ratio"]:
if key not in data:
problems.append(f"metric missing field: {key}")
print("SKILL.md frontmatter OK / trigger words OK / references complete"
if not problems else "\n".join(problems))
sys.exit(1 if problems else 0)
Installation is straightforward: place the whole directory under the project's .trae/skills/, open a new conversation, feed "use leak-detector to build leak detection in this project myself," it will start with S1 health check, not write code immediately. To run just one part, say "do false-positive governance per S6," stage numbers match docs/CHANGELOG-leak.md, and rework can locate which round's constraint wasn't held.
I later packaged the directory to the neighboring team. Their project has no medical data, so the strictest default in privacy-redline.md felt heavy; they changed references/ per "how to iterate this skill," SKILL.md untouched. That's the difference between making it a Skill rather than a document: constraints frozen where scripts can check, business differences left in replaceable material layer.
What the Final Files Look Like
Earlier rounds pasted KeyedWeakReference.kt, ObjectWatcher.kt, GcConfirmer.kt, MyApplication.kt, verify_skill.py, and Gradle / Manifest snippets; not repeated here. Below is the complete file tree and final versions of the remaining pieces, each marked with path and purpose. All use platform APIs, AndroidX, or standard library, zero third-party dependencies; versions AGP 8.2.2, compileSdk 34, targetSdk 34, minSdk 24, I built and ran unit tests on my own machine; other versions may differ.
app/
├── src/main/java/com/example/health/
│ ├── MyApplication.kt # debug branch explicit install
│ └── leak/ReleaseRetainedCounter.kt # release-only thin count read-out
├── src/debug/java/com/example/health/leak/
│ ├── KeyedWeakReference.kt # weak reference with UUID key
│ ├── ObjectWatcher.kt # watch / clear queue / confirm
│ ├── GcConfirmer.kt # force GC + enqueue wait
│ ├── DumpTrigger.kt # threshold / rate limit / visibility
│ ├── LeakWatchers.kt # lifecycle mounting
│ ├── HeapDumper.kt # dump to private dir
│ ├── HprofSanitizer.kt # zero primitive array content
│ ├── LeakDetector.kt # explicit install entry
│ ├── LeakReportActivity.kt # debug report page
│ └── LeakSamples.kt # 8 constructed leak sample types
├── src/debug/assets/known-leaks.txt # known system / third-party leak whitelist
└── src/debug/AndroidManifest.xml # report page declaration, exported=false
tools/
├── hprof_min.py # Pass1 index + Pass2 edge building
├── leak_trace.py # BFS shortest path + three-state annotation
├── leak_report.py # group signature + report generation
└── run_leak_suite.sh # two machines each 10 rounds regression
tests/test_sanitizer.py # stripping regression, run every version
docs/ leak-design.md / version-facts-leak.md / leak-inventory.md /
metrics-leak.md / false-positive.md / dump-cost.md /
regression-leak.md / adversarial-review.md / CHANGELOG-leak.md
.trae/rules/leak_rules.md
.trae/skills/leak-detector/ # the Skill package from previous chapter
.github/workflows/leak-gate.yml
metrics-leak.json
The lifecycle mounting piece, deduplication is key:
// app/src/debug/java/com/example/health/leak/LeakWatchers.kt
internal object LeakWatchers {
private val recent = HashMap<Int, Long>() // identityHashCode → time
private const val DEDUPE_MS = 1_000L
private fun offer(watcher: ObjectWatcher, obj: Any, desc: String) {
val id = System.identityHashCode(obj)
val now = SystemClock.uptimeMillis()
synchronized(recent) {
if (now - (recent[id] ?: -1L) < DEDUPE_MS) return
recent[id] = now
if (recent.size > 256) {
recent.entries.removeIf { now - it.value > DEDUPE_MS * 10 }
}
}
watcher.watch(obj, desc) // only pass object, no toString, no log
}
fun install(app: Application, watcher: ObjectWatcher) {
app.registerActivityLifecycleCallbacks(
object : Application.ActivityLifecycleCallbacks {
override fun onActivityDestroyed(a: Activity) {
offer(watcher, a, "${a.javaClass.name} received Activity#onDestroy()")
}
override fun onActivityCreated(a: Activity, s: Bundle?) = Unit
override fun onActivityStarted(a: Activity) = Unit
override fun onActivityResumed(a: Activity) = Unit
override fun onActivityPaused(a: Activity) = Unit
override fun onActivityStopped(a: Activity) = Unit
override fun onActivitySaveInstanceState(a: Activity, s: Bundle) = Unit
}
)
// Fragment / ViewModel use AndroidX's FragmentLifecycleCallbacks and
// ViewModel's onCleared hook, same through offer();
// root view uses View.OnAttachStateChangeListener for detach.
// When one object is hit by two callbacks, the one-second dedup table collapses to one retained.
}
}
In DumpTrigger, all adjustable numbers are centralized in one data class so real-device regression can dump the current config for reconciliation:
// app/src/debug/java/com/example/health/leak/DumpTrigger.kt
data class LeakConfig(
val watchDelayMs: Long = 5_000L,
val visibleThreshold: Int = 5,
val hiddenThreshold: Int = 1,
val dumpCooldownMs: Long = 60_000L,
val maxDumpPerSession: Int = 3
)
internal class DumpTrigger(
private val config: LeakConfig,
private val onDump: () -> Unit
) {
@Volatile private var visible = true
@Volatile private var lastDumpMs = 0L
@Volatile private var dumpCount = 0
private val lock = Any()
fun onVisibilityChanged(isVisible: Boolean) {
visible = isVisible
if (!isVisible) check(force = false)
}
fun onRetained(count: Int) = check(force = false)
fun forceDump() = check(force = true)
private fun check(force: Boolean) {
synchronized(lock) {
val threshold = if (visible) config.visibleThreshold
else config.hiddenThreshold
val now = SystemClock.uptimeMillis()
if (!force && count() < threshold) return
if (!force && now - lastDumpMs < config.dumpCooldownMs) return
if (dumpCount >= config.maxDumpPerSession) return
lastDumpMs = now
dumpCount++
}
onDump()
}
private fun count(): Int = LeakDetector.retainedCount()
}
HeapDumper and HprofSanitizer are the privacy boundary; the two must be read together:
// app/src/debug/java/com/example/health/leak/HeapDumper.kt
internal class HeapDumper(private val app: Application) {
fun dumpAsync(onDone: (Result<File>) -> Unit) {
val thread = HandlerThread("leak-dump").apply { start() }
Handler(thread.looper).post {
val dir = File(app.filesDir, "leak").apply { mkdirs() }
val raw = File(dir, "raw.hprof")
val result = runCatching {
Debug.dumpHprofData(raw.absolutePath) // ART suspend all
val safe = HprofSanitizer.sanitizeInPlace(raw)
safe
}
if (!result.isSuccess) {
raw.delete() // failure also leaves no raw heap
}
thread.looper.quit()
onDone(result)
}
}
}
// app/src/debug/java/com/example/health/leak/HprofSanitizer.kt
// in-place rewrite HEAP_DUMP_SEGMENT inside 0x23 PRIMITIVE_ARRAY_DUMP content bytes.
// Only change the array element area, not length and type fields, otherwise following sub-records misalign.
internal object HprofSanitizer {
fun sanitizeInPlace(raw: File): File {
val bytes = raw.readBytes()
val idSize = readIdSize(bytes) // read 4 or 8 from header
var pos = headerLength(bytes)
while (pos < bytes.size) {
val tag = bytes[pos].toInt() and 0xFF
val len = readU4(bytes, pos + 5)
val body = pos + 9
if (tag == 0x0C || tag == 0x1C) {
scrubSegment(bytes, body, body + len, idSize)
}
pos = body + len
}
val out = File(raw.parent, "dump-stripped.hprof")
out.writeBytes(bytes)
raw.delete() // immediately delete original
return out
}
private fun scrubSegment(b: ByteArray, from: Int, to: Int, idSize: Int) {
var p = from
while (p < to) {
val sub = b[p].toInt() and 0xFF
p++
when (sub) {
0x23 -> { // PRIMITIVE_ARRAY_DUMP
p += idSize + 4 + 4 // array id + stack serial + count
val count = readU4(b, p - 4)
val elemType = b[p].toInt() and 0xFF
p += 1
val width = widthOf(elemType)
val end = p + count * width
for (i in p until end) b[i] = 0 // only clear elements, not structure
p = end
}
0x21 -> p += skipInstance(b, p, idSize)
0x20 -> p += skipClassDump(b, p, idSize)
0x22 -> p += idSize + 4 + 4 + idSize + readU4(b, p + idSize + 4) * idSize
0xFE -> p += 4 + idSize
in GC_ROOT_TAGS -> p += rootWidth(sub, idSize)
0x2C -> return
else -> throw IllegalArgumentException(
"unsupported hprof sub-tag 0x${sub.toString(16)} at $p"
)
}
}
}
}
That else -> throw is deliberate. Round 8's capability boundary lives here: on unknown sub-tag, rather throw the entire dump than guess layout and continue — guessing once misaligns all subsequent offsets, producing a reference chain that looks complete but is wrong, far more dangerous than an error.
The release side only keeps this small piece; the security colleague reviewing dependencies ends at line 12 of this file:
// app/src/main/java/com/example/health/leak/ReleaseRetainedCounter.kt
// This version is written by debug-side count mirror; release does not dump, write files, or network.
object ReleaseRetainedCounter {
@Volatile private var count = 0
fun updateFromDebugMirror(value: Int) { count = value }
/** Only read when composing OOM report metadata, for attribution classification */
fun snapshot(): Int = count
}
// attach into existing crash-report assembly (illustrative)
val meta = bundleOf(
"retained_object_count" to ReleaseRetainedCounter.snapshot(),
"oom_heap_state" to "unknown" // don't fabricate unmeasured heap data
)
The off-device parser skeleton, emphasis on two seeks and not hardcoding idSize:
#!/usr/bin/env python3
# tools/hprof_min.py
# Capability boundary: only supports JAVA PROFILE 1.0.3 / idSize 4 or 8 / 0x1C segments;
# only Pass1 index + Pass2 edge building + BFS shortest path.
# Does not provide: dominator tree, retained size, native memory attribution, vendor private tags.
import argparse, json, mmap, struct, sys
from collections import deque
BASIC_WIDTH = {2: None, 4: 1, 5: 2, 6: 4, 7: 8,
8: 1, 9: 2, 10: 4, 11: 8} # 2=object, width=idSize
def u1(b, p): return b[p]
def u2(b, p): return struct.unpack_from(">H", b, p)[0]
def u4(b, p): return struct.unpack_from(">I", b, p)[0]
def uid(b, p, n): return int.from_bytes(b[p:p+n], "big")
def parse_header(b):
end = b.index(b"\x00")
version = b[:end].decode("ascii", "replace")
id_size = u4(b, end + 1)
if version != "JAVA PROFILE 1.0.3" or id_size not in (4, 8):
raise ValueError(f"unsupported hprof: {version} / id={id_size}")
return version, id_size, end + 1 + 4 + 8
class Index:
def __init__(self, b, id_size, start):
self.b, self.n, self.p = b, id_size, start
self.strings, self.classes, self.roots = {}, {}, []
self.offsets, self.layouts = {}, {}
self.stats = {}
def pass1(self):
while self.p < len(self.b):
tag = u1(self.b, self.p)
length = u4(self.b, self.p + 5)
body = self.p + 9
self.stats[tag] = self.stats.get(tag, 0) + 1
if tag == 0x01: # STRING_IN_UTF8
# read id first, then bytes: reverse order silently misaligns
sid = uid(self.b, body, self.n)
self.strings[sid] = self.b[body + self.n: body + length]
elif tag == 0x02: # LOAD_CLASS
cid = uid(self.b, body + 4, self.n)
name_id = uid(self.b, body + 4 + self.n + 4, self.n)
self.classes[cid] = name_id
elif tag in (0x0C, 0x1C):
self.scan_segment(body, body + length, collect=True)
elif tag == 0x2C:
pass
self.p = body + length
return self
def scan_segment(self, start, end, collect=False):
# sub-records no length field, advance cursor by tag's structure
p = start
while p < end:
sub = u1(self.b, p); p += 1
if sub in ROOT_TAGS:
oid = uid(self.b, p, self.n)
if collect: self.roots.append((ROOT_TAGS[sub], oid))
p += self.n + ROOT_TAGS[sub][1]
elif sub == 0x20: # CLASS_DUMP
cid = uid(self.b, p, self.n)
if collect:
self.layouts[cid], used = read_class_layout(self.b, p, self.n)
self.offsets[cid] = p
else:
used = class_layout_size(self.b, p, self.n)
p += used
elif sub == 0x21: # INSTANCE_DUMP
oid = uid(self.b, p, self.n)
cid = uid(self.b, p + self.n + 4, self.n)
size = u4(self.b, p + self.n + 4 + self.n)
if collect: self.offsets[oid] = (p, cid, size)
p += self.n + 4 + self.n + 4 + size
elif sub == 0x22: # OBJECT_ARRAY_DUMP
cnt = u4(self.b, p + self.n + 4)
p += self.n + 4 + 4 + self.n + cnt * self.n
elif sub == 0x23: # PRIMITIVE_ARRAY_DUMP
cnt = u4(self.b, p + self.n + 4)
w = BASIC_WIDTH[u1(self.b, p + self.n + 4 + 4)]
p += self.n + 4 + 4 + 1 + cnt * w
elif sub == 0xFE: # HEAP_DUMP_INFO
p += 4 + self.n
elif sub == 0x2C:
return
else:
raise ValueError(f"unsupported sub-tag 0x{sub:02x} at {p}")
def shortest_path(index, target):
# BFS from all GC Roots, first hit is shortest strong reference path
parent, seen, q = {}, set(), deque()
for kind, rid in index.roots:
q.append(rid); seen.add(rid); parent[rid] = ("ROOT", kind, None)
while q:
cur = q.popleft()
if cur == target:
path = []
while cur in parent:
node, kind, field = parent[cur]
path.append((cur, kind, field))
cur = node if node != "ROOT" else None
if cur is None: break
return list(reversed(path))
for nxt, field in edges_of(index, cur):
if nxt not in seen:
seen.add(nxt); parent[nxt] = (cur, "REF", field); q.append(nxt)
return None
if __name__ == "__main__":
ap = argparse.ArgumentParser(description=__doc__)
ap.add_argument("hprof")
ap.add_argument("--index", action="store_true")
ap.add_argument("--find")
ap.add_argument("--path")
ap.add_argument("--strict", action="store_true")
a = ap.parse_args()
with open(a.hprof, "rb") as f, mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) as b:
_, n, start = parse_header(b)
idx = Index(b, n, start).pass1()
if a.index:
print(json.dumps({
"records": idx.stats, "objects": len(idx.offsets),
"gc_roots": len(idx.roots), "classes": len(idx.classes)
}, indent=2))
ROOT_TAGS, edges_of(), read_class_layout() expand by round 8's tag table; not shown for space; the file has them with comments marking which record. Two key points: Pass2 only writes edges for Basic Type = 2 fields, and --strict non-zero exits on any unknown tag.
The whitelist and baseline are pure data, all reproducible by script:
# app/src/debug/assets/known-leaks.txt
# format: matched class or field name | source | affected version | category
android.app.UiModeManager | AOSP known | API 31~33 | Library Leak
android.permission.PermissionControllerManager | AOSP 2559 | API 34 | Library Leak
com.android.internal.*.mContext | vendor ROM | see notes | Library Leak
{
"build": "8.2.2-312",
"devices": ["Pixel 6 / Android 13", "Redmi Note 11 / Android 11"],
"samples": 10,
"cold_start_force_stop": true,
"metrics": {
"false_positive_rate": {"pixel6": 0.09, "redmi": 0.11, "target": 0.10},
"recall": {"hit": 8, "total": 8, "target": 8},
"dump_freeze_p90_ms": {"pixel6": 640, "target": 700},
"release_detector_classes": 0,
"oom_with_retained_ratio": 0.96
},
"sanitized_before_export": true,
"mapping_archived_with_dump": "captures/20261021/mapping.txt",
"open_items": ["multi-process ownership", "debug minify keep rule", "redmi 1pt over target"]
}
CI doesn't upload artifacts, only prints summary:
# .github/workflows/leak-gate.yml
name: leak-gate
on: [pull_request]
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: watcher unit test
run: ./gradlew :app:testDebugUnitTest --tests '*ObjectWatcherTest*'
- name: stripping regression
run: python3 -m unittest tests.test_sanitizer -v
- name: Skill self-check
run: python3 .trae/skills/leak-detector/scripts/verify_skill.py
- name: four-number gate
run: python3 tools/check_metrics.py metrics-leak.json
- name: release cleanliness
run: bash .trae/skills/leak-detector/scripts/check_release.sh app-release.apk
# no hprof / mapping / leak-reports upload, artifacts destroyed with runner
In check_metrics.py I left a hard rule: false positive rate over target fails directly, but prints the reason as-is, script doesn't round. Redmi's 0.11 now outputs as a warning with "known not met, see docs/regression-leak.md section 3," not turning green.
Pitfalls I Stepped On, Ordered by Error
The real time sink wasn't writing code, it was these phenomena appearing and me mistaking them for something else. Arranged by the error or phenomenon seen, each line up against the process is more useful than narrating the whole flow.
| Phenomenon | Root cause | Fix |
|---|---|---|
| normal pages just back-buttoned flagged leak, false positive 60%+ | judgment only cleared queue once, missed second poll after GC | fixed order: delay → clear queue → GC → clear again → judge |
| weak reference not cleared yet object never used | confused "weakly reachable" with "reclaimed", enqueue happens before reclamation | observe ReferenceQueue enqueue, not referent null |
| queue still empty after forced GC | Runtime.gc() doesn't guarantee immediate enqueue, ReferenceHandler enqueues asynchronously | poll at most 5 times, 20ms each, exit when hit |
| finalize() judgment sometimes present sometimes absent | timing nondeterministic, objects may resurrect, lengthens GC pause | abandon finalization, go back to weakly reachable |
| a weak reference to Activity appears in heap, MAT looks messy | first version held weak ref directly to target object | only hold KeyedWeakReference, log only key and description |
Log.d("$watchedObject") occasionally throws |
string interpolation calls toString(), some implementations read fields or throw | forbid any interpolation or concatenation of target object |
| report page enter/exit seven or eight times OOM, no notification at all | dependency removed means no trigger at all | build own detection, evidence collection and judgment stay on device |
| dump freezes UI nearly 1.2 sec | Debug.dumpHprofData suspends all ART threads, and on main thread | move to HandlerThread, add cold dropped-frame timing and rate limit |
| phone bounces between freeze and analysis | dump per retained | foreground gather 5 / background 1, 60s cooldown, max 3 per session |
| no report long after pressing Home | visibility not listened, foreground threshold stayed 5 | ActivityLifecycleCallbacks maintains visible, background drops to 1 |
| same destruction scenario counted two retained | Fragment's view and Fragment itself both watched by two callbacks | identityHashCode + 1s window dedup |
| static singleton repeatedly alarms after screen rotation | config change recreates Activity, but singleton is long-lived, misjudged path | write into false-positive.md, judge by lifecycle boundary not class name |
| same leak in report repeated dozen lines | group signature concatenated Object[].[3] raw, different index counted different bug |
normalize index to [x] |
| sha1 changes every group | suspicious reference set included per-run description / timestamp | signature only references marked ~~~, don't mix metadata |
| heap class names all a.b.c, reference chain unreadable | release obfuscated, mapping not archived with dump | archive mapping.txt same dir, pick by build number when parsing |
strings xxx.hprof finds names and tokens |
String backed by PRIMITIVE_ARRAY_DUMP, dump captures whole heap | zero primitive arrays immediately after dump, original file immediately deleted |
| after stripping reference chain also won't resolve | also cleared array length / type fields, misaligned later sub-records | only clear element area, don't touch structure fields |
| off-device script parsed class names all garbage | strings[rid()] = f.read(...) evaluation order ate file pointer |
read id then bytes, assert cursor position |
| idSize hardcoded 4, all wrong on Pixel 6 | 64-bit id dumps use 8 | read u4 from header, support 4 and 8 |
| from second sub-record offset all flying | treated 0x1C sub-record as top-level record reading length | sub-records no length, advance by tag structure |
| Android 13 dump crashes every time | didn't handle 0xFE HEAP_DUMP_INFO | add Android extended tags; unknown tags throw, no guess |
| whitelist has item but notification not clean | only matched by class name prefix, obfuscated name mismatch | whitelist stores both original and mapping-restored name |
System.gc() call marks leak |
treated "GC ran" as "should all reclaimed" | GC only creates opportunity; judgment is whether key still in table after second poll |
release APK contains dumpHprofData string |
detection classes in main source set, only BuildConfig.DEBUG runtime guard | all implementations moved into debug source set, cross-source-set reflection entry |
| online OOM report's retained field empty | counter also moved into debug source set | main only has thin count read-out, review dependencies at a glance |
| log explosion with user-visible text | report expanded every field of every object on chain | replace with three-state label + short note, only class names and field names |
| CI all green but stripping regression never ran | early Skill let Trae self-declare "complete" | add verify_skill.py checking actual products, script says so |
| Skill fed trigger phrase no response | description wrote "memory optimization related spec," not matchable | write user's actual phrases into description, run self-check |
The first three rows in the table are three sides of the same crash; my October 8 two-hundred-lines died there. Rows 15-19 were consecutive one-afternoon bumps, all in the off-device parser — binary format: one wrong byte doesn't error, just gives you a convincing-looking wrong conclusion.
Command Quick Reference
Three groups by purpose, with which lines to look at in output.
# --- create state and trigger ---
adb shell am force-stop com.example.health # create cold state
adb shell am start -n com.example.health/.report.ReportActivity
adb shell input keyevent 4 # back, triggers onDestroy
adb shell am broadcast -a com.example.health.DEBUG_DUMP # debug-only, immediate dump
adb logcat -s LeakDetector LeakWatcher | grep -E 'Watching|Retained|install'
# Watching instance of ... (Activity received Activity#onDestroy() callback)
# 5 sec later: Scheduling check for retained objects because found new object retained
# Rescheduling check ... in 2000ms because found only 4 retained objects (< 5 while app visible)
# --- pull and stripping re-check ---
adb pull /data/data/com.example.health/files/leak/ /tmp/leak-check/
strings /tmp/leak-check/*-stripped.hprof | grep -E '身份证|就诊人|Bearer |token' | wc -l
# must be 0; non-zero means stripping bypassed, this file must not leave current dir
strings /tmp/leak-check/*-stripped.hprof | grep -c 'JAVA PROFILE'
# 1 — header still there, only array content zeroed
# --- off-device parsing ---
python3 tools/hprof_min.py captures/report.hprof --index
python3 tools/hprof_min.py captures/report.hprof --find <key> --path --strict
python3 tools/leak_report.py captures/report.hprof --build 8.2.2-312 --out leak-reports/
python3 -m unittest tests.test_sanitizer -v
python3 .trae/skills/leak-detector/scripts/verify_skill.py
bash .trae/skills/leak-detector/scripts/check_release.sh app-release.apk
--index output I first look at three numbers:
{
"records": {"1": 18422, "2": 3901, "28": 1, "44": 0},
"objects": 214803,
"gc_roots": 1874,
"classes": 3901
}
28 is decimal for 0x1C, appearing once means this dump is single-segment; 44 is decimal for 0x2C end marker. If gc_roots is 0, don't jump to path — first go back and check GC Root sub-tag parsing; path cannot come out.
Release cleanliness commands separately, security colleague runs quarterly review:
unzip -p app-release.apk classes.dex > /tmp/r.dex
strings /tmp/r.dex | grep -E 'KeyedWeakReference|ObjectWatcher|HeapDumper|HprofSanitizer|dumpHprofData' | wc -l
# 0
strings /tmp/r.dex | grep -E 'retainedObjectCount|ReleaseRetainedCounter' | head -3
# only this one read-out may appear
adb shell dumpsys package com.example.health | grep -i -A2 'ContentProvider'
# confirm no auto-install provider was merged in under the radar
The Four Numbers I Watched Before Launch
The four numbers are fixed in docs/metrics-leak.md, from the first handwritten version to final, definition never changed. Samples are Pixel 6 / Android 13 and Redmi Note 11 / Android 11, each machine cold 10 rounds, each round am force-stop then create state.
| Number | Definition | handwritten first version | final | target |
|---|---|---|---|---|
| false positive rate | false positives / total retained, 40 constructed samples + 20 normal enter/exit | Pixel 6 62% / Redmi 65% | 9% / 11% | ≤ 10% |
| true positive recall | 8 constructed leak sample types caught | 5 / 8 | 8 / 8 | 8 / 8 |
| dump freeze P90 | Pixel 6 cold 10 rounds, dropped-frame timing | 1180ms (sync on main) | 640ms | ≤ 700ms |
| release cleanliness | release dex detection class count / OOM report with retained count ratio | 0 class / 0% | 0 class / 96% | 0 class / ≥ 95% |
Two places I didn't let beautify. One is Redmi Note 11's false positive 11%, 1 point over target, because that machine's system reclamation is more aggressive and queue enqueue timing wanders; Trae suggested removing three samples from numerator, I didn't agree — change definition invalidates all eleven prior rounds' comparison. Two is "freeze P90 from 1180 to 640" doesn't equal half as fast: the dump's suspension duration itself didn't shorten, only stopped blocking the path user is tapping; report wrote these two events on separate lines.
If I say the most useful number, it's that 0: strings search sensitive fields result 0, release dex detection classes result 0. This cleanup's original intent wasn't making detection more accurate, it was making "what it captures, where it's placed, whether it leaves device" something one command can verify.
Places to Dig Further
By my own ROI ranking, from most worthwhile down:
| Direction | Solves what | Cost |
|---|---|---|
| multi-process watcher ownership | now each process installs a copy, push process duplicate dumps | need process-name routing + main-process arbitration, changes across 3 files |
| low-memory machine false positive 1 point | Redmi's enqueue timing wanders, more false positives | need dynamic polling count by device memory class, easy to become parameter-tuning mask |
| debug minify keep rules | now reflection across source sets, debug not obfuscated so not hit | need keep rules and write risk into Rules, reconcile with obfuscation rules |
| on-device lightweight analysis | now must pull file to dev machine to see path | need to port Shark's two-pass scan into device, largest workload |
| heap growth / BLeak | no watch needed to find "heap keeps growing" | 3.0 still alpha, API unstable, need isolate experimental branch |
| obfuscated mapping auto-archive | now human puts mapping into captures directory | add Gradle task to copy by build number, check version match |
integrate with ApplicationExitInfo |
OOM report now only retained count, no exit reason | need distinguish REASON_LOW_MEMORY from other exits, don't conflate |
| Compose scenarios | leaks from remember / side effects not yet in constructed samples |
need add 3-4 sample types, handle recomposition count |
| stripping evidence trail | now only proves "search empty", not "which step did it" | write a non-content audit record per dump, compliance review uses it |
| make Skill a team-private package | neighboring team changed privacy section, versions forked | add version number and regression samples, run self-check when changing description |
The first two I plan to do next version. One I didn't list: native leaks. That's heapprofd sampling native heap allocations, entirely different from what Debug.dumpHprofData captures (Java heap). Mixing them together just blurs the word "leak" again.
Later
At the start of November, I printed the Redmi Note 11 regression report and taped it to the cubicle divider. The false positive rate column, 11%, I circled with a pen but didn't erase. A colleague passing by asked if this was a fail. I said it wasn't passed. He said then why tape it. I said taping it helps remember. The security colleague later reviewed and asked only one question: "Who wrote that first line of the report about stripping declaration?" I said I added it after her last ask. She nodded and walked away.