Working with the Memory Profiler

1. Working with the Memory Profiler

Verified with: 2019.4 and Memory Profiler preview.1 - 0.2.6

Verified with: 2019.3 - https://learn.unity.com/tutorial/working-with-the-memory-profiler-2019-3

The Memory Profiler allows you to analyze a project’s memory usage to find leaks and fragmentation. Memory leaks can occur when memory is allocated but not deallocated after it’s no longer needed. Program performance worsens as memory runs out, eventually leading to the program (and potentially even the host device) crashing. When memory is allocated in many small chunks, rather than fewer large contiguous chunks, it’s known as memory fragmentation. This causes the small spans of unallocated memory between the allocated blocks to become unavailable for use.

2. Installing the Memory Profiler

The Memory Profiler works with both the Unity Editor and development builds and is available as a Preview package in the Package Manager. To install the Memory Profiler:

1. Select Package Manager from the Window drop-down in the Unity Editor.

2. Click Advanced, and select Show Preview Packages.

3. Locate Memory Profiler and click Install in the bottom-right corner of the Package Manager window.

4. Once it’s installed, you can access the Memory Profiler by selecting Analysis > Memory Profiler from the Window drop-down.

3. Capturing a Memory Snapshot

The Memory Profiler can target a currently running development build, either on the local machine or by giving it a specific IP address for a networked machine.

1. Before you can capture a memory snapshot, you must select a target. By default, the Unity Editor is the target.

2. To select a new target, click the drop-down menu in the upper left corner of the Memory Profiler (Figure 01).

Figure 01: Selecting a target for the Memory Profiler

Click the Capture button to capture the current Memory Profile from the selected target (Figure 02). Note that the capture itself consumes some memory; in some cases, this can cause the target to freeze or crash when memory is low.

Figure 02: The Memory Profiler can target a local or networked development build, the Unity Editor, or a memory snapshot from the Bitbucket Profiler.

4. Importing a Captured Memory Snapshot

1. Click the Import button at the top of the Memory Profiler window (Figure 03).

Figure 03: Click here to import a Memory Snapshot

2. Using the file format drop-down in the lower right corner of the “Import snapshot file” dialog, select the format of the Memory Snapshot you wish to import (Figure 04). Options include .snap files captured using the Memory Profiler, and .memsnap* using the Bitbucket Memory Profiler.

Figure 04: Selecting the Memory Snapshot’s format

3. Navigate to and select your Snapshot. Click Open.

4. The first time you capture a Memory Snapshot, a folder called MemoryCaptures is created (in the same level of the Assets folder, rather than within it). You can also drop Memory Snapshots into this folder to make them accessible.

5. Viewing a Memory Snapshot

1. After capture or import (including moving the snapshot into the MemoryCaptures folder), the snapshot will be visible in the left column of the Memory Profiler window. Click Open to view the Memory Profile (Figure 05).

Figure 05: A captured memory snapshot

The default and most intuitive view is the Tree Map (Figure 06). In this view, the amount of memory used by each element type is represented proportionally. In our example, 126 shaders collectively consume 80 MB of memory.

Figure 06: The Tree Map

To view a category in more detail, click it to reveal all member elements and their respective memory footprints. More detailed information will appear below the Tree Map in a table (Figure 07). Click the headers to sort the table by value or group.

Figure 07: The table view, which sits below both the Tree Map and Memory Map, gives more detailed information on the memory usage of individual elements.

A more direct view, the Memory Map, shows the memory layout, with different colors
representing different types of memory (Figure 08). This can be helpful for locating memory fragmentation.

Figure 08: The Memory Map is a more direct representation of the virtual memory layout of your project.

6. Finding a Memory Leak

To find a memory leak:

1. Launch the player, set it as your Memory Profiler target, and take a snapshot of an empty Scene.

2. Load the Scene you wish to test. Play through some of the Scene to load the necessary assets.

3. Unload the Scene by either calling Resources.UnloadUnusedAssets() or by loading/creating an empty Scene twice.

4. Take another snapshot, and exit Play Mode.

5. In the Workbench, load the first screenshot, then the second, and click Diff. Unity will calculate the difference between the two screenshots. This could take a few seconds, depending on the size of the snapshot.

6. In the Table view, click the header for the Diff column and select Group.

7. Entries will be grouped: same in both snapshots, deleted from the first snapshot, and new. New entries are potential memory leaks.

7. Conclusion

The Memory Profiler is a great way to audit your project’s memory usage. Not only can you see what’s consuming the most memory, but also the way your project is using or misusing memory. Memory leaks and fragmentation are two of the most common issues that impact project performance, and the Memory Profiler makes troubleshooting these issues easy.