ArkTS Memory Snapshot Clustering: Three Rules to Pinpoint Leaks in 100K+ Objects

Clustering Background

When using ArkTS memory snapshots to locate memory leaks, analysts must prioritize objects with large retained sizes. In large projects, directories like jsobject and jsarray often contain 100,000+ objects created at different call sites but grouped under the same type, making manual differentiation of per-business-object memory impact impractical. Clustering rules are therefore essential to aggregate same-type objects by origin and quantify each leak's contribution.

Clustering Workflow

Anchor selection : Only cluster objects under the top 20 directories and directories whose retained size exceeds 5% of the snapshot total.

Apply type-specific clustering rules : Different directories require different rules because their object characteristics differ.

Statistics and sorting : Count objects per cluster and sum retained size; sort by count or size to surface the biggest leaks.

Three Core Clustering Rules

1. Shortest Reference Chain Clustering (default for basic types)

Applies to : Method, js_set, js_map, string, JSNativePointer, jsarray, etc.

Objects in these directories share identical names; the distinguishing factor is their creation context, captured by the reference chain to GC roots. For each object, compute the shortest reference chain (if multiple shortest chains exist, pick the one with the largest retained size). Objects with identical shortest chains belong to the same cluster.

2. Name + Reference Chain Clustering

Applies to : Function, framework, (array), and business-side class/function objects.

Business objects carry file-path and line-number metadata. The same class or function invoked from different call sites yields different reference chains. Clustering by both name and reference chain separates objects by allocation site.

3. Property + Reference Chain Clustering

Applies to : jsobject, js_shared_object.

These objects share names but represent distinct logical entities. First, split by reference chain to separate different call sites. However, many jsobject instances have distance-1 children that are indistinguishable via reference chains alone. For those, compare the directly held properties : if the set of property names and the holding relationships (purple-labeled edges in the tool) match exactly, merge them into one cluster.

Special Clustering Cases

4.1 Objects Requiring No Clustering

SourceTextModule

: One per TypeScript file, already groups exports — naturally clustered. HiddenClass (NonMovable): One-to-many with instances; each unique hidden class is its own cluster. global_env and global_object: Singletons per snapshot.

4.2 Async Task Objects

Applies to : Promise, PromiseRecord, PromiseCapability, PromiseReaction.

Cluster by the handle field inside PromiseReaction (represents the next async hop) combined with the shortest reference chain. Internal promise machinery ( Promise, PromiseRecord, PromiseCapability) is ignored.

4.3 Proxy Objects

Applies to : proxy.

Proxies are framework-heavy. Cluster by the target handle (the proxied object) plus reference chain, because the proxy itself is transparent; the meaningful distinction is what it wraps.