dart-sdk/runtime/tools/heapsnapshot/README.md

Obtaining a heapsnapshot

There's several ways one can obtain a heapsnapshot

Obtain snapshot from live VM

One can use existing tools (e.g. observatory / DevTools) to load & save a heapsnapshot.

For convenience there's also a bin/download.dart script in package:heapsnapshot that can be given an URL to a live VM and it will fetch a heapsnapshot.

Programmatically

Note: enabled for debug and release Dart build modes, but not for product mode.

It's possible to programmatically dump a heapsnapshot to a file by using a dart:developer API:

import 'dart:developer';

foo() {
  ...
  // Will dump the heapsnapshot at a specific place in program execution.
  // Allows very precise analysis of what data is live at a particular place.
  NativeRuntime.writeHeapSnapshotToFile('dump.heapsnapshot');
  ...
}

CLI Usage:

Loading a snapshot

After launching bin/explore.dart one has to load a heapsnapshot before doing anything else. This can be done with the load command. It will auto-complete directories and any file with the .heapsnapshot extension.

# Load
load <file>

Finding all live objects

# Find all live objects by finding transitive closure of roots.
# We assign to a `all` variable for later usage.
all = closure roots

Show known sets of objects

# Show named sets / known variables
info

Show statistics of objects

To examine how many objects there are per class and how large they are one can use the stats command:

stats all

Example usage session

# Filter lists from "all" into "lists"
lists = filter all _List

# Find empty lists into "empty-lists"
empty-lists = dfilter lists ==0

# Who's using the empty lists?
users empty-lists

# print that info (from $0 in this case as we didn't give it a name but it was
# the first one we didn't give a name)
stat $0

# Filter more
empty-growable-lists = filter (users empty-lists) _GrowableList

# Print
stats empty-growable-lists

# Who's using them?
retainers empty-growable-lists

# Look into strings next
strings = filter all String

# What's inside the strings
dstats strings

# Who's pointing to the big strings?
retainers (dfilter strings >=1024)

# Small strings
small-strings = dfilter strings <100

# See them
dstats small-strings

# Who's retaining the string "foo"
f = dfilter small-strings foo
retainters f

# Find stuff with specific field
hasField = filter all :specificField
stats closure hasField :specificField
foo = follow hasField :specificField
stats closure foo

# Stop the closure search if going into specific files
stats closure foo ^file1.dart ^file2.dart ^file3.dart