Awesome

Unity Heap Crawler

Customizable heap snapshotting tool for Unity game engine. Can be used to detect memory leaks and analyze high heap usage.

Features

1. Reflection-based
2. Results are plain text (see output example)
3. Human readable results (objects are traversed using BFS)
4. Differential mode that displays only new objects in all reports (see diffs output)
5. Enable tracking all root paths for specific types (see output and diffs output)
6. Little memory overhead - most crawling data is discared after aggregation
7. Highly customizable - choose between fullness and low memory usage (see documentation)
8. References to destroyed Unity objects that still take heap space are clearly visible
9. Unity editor is not needed. You can make a snapshot in build

Motivation

When heap consumption and memory leaks became problems in our project I could not find a tool that could make a mono heap snapshot to help me find those leaks.

• Builtin Memory Profiler (Profiler window in Editor) is good for analyzing native resources but provides only heap size without any details
• Unity Memory Profiler does not collect heap objects on mono runtime (even though patch notes state it does in 2017.1). Also, taking snapshot in our project used up 32GB RAM and that is without heap objects.
• There is no access to mono runtime in Unity so mono HeapShot is not an option

Current solution relies heavily on ideas and memory estimation code from previous reflection based crawlers - my collegue's UnityHeapEx and UnityHeapDump by Zuntatos. I could not use them as is due high memory consumption (all references data won't fit in memory) and low results readability.

Usage

Create HeapSnapshotCollector class instance and call Start() after setting it up. See usage example for options overview. Check out documentation for more detailed options description.

Issues

• Static fields in generic types and not detected. User can supply those Type objects manually
• Type memory usage is an estimation and can be slightly off

Authors

• Vasily Boldyrev - Owlcat Games

Credits

• Cotoff for original UnityHeapEx
• Zuntatos for another implementation of the same idea UnityHeapDump

Licence

This code is distributed under the terms and conditions of the MIT license.