Memory Insights

An Overview of Memory Insights

Choose your operating system:

Windows

macOS

Linux

Unreal Engine 5 (UE5) expands the capabilities of Unreal Insights by adding improved memory tracking and profiling support into its Memory Insights feature. Developers can now see more detailed information about memory allocation and deallocation, including the Low Level Memory (LLM ) tags and callstacks associated with each block of memory at any point in time. Memory Insights also features a query system that can find live allocations at a certain point in time, recognize increases or decreases in memory usage, differentiate short-term and long-term allocations, and find memory leaks.

Initial Setup

You can run Unreal Insights directly from the Unreal Editor by navigating to Tools > Run Unreal Insights, or by downloading a source build of Unreal Engine, and navigating to the Engine/Binaries/Win64 directory where the Unreal Insights tool ships with Unreal Engine. If you are a developer who downloaded the Unreal Engine source code and compiled it locally, you can compile it either by building the entire Unreal Engine solution in Development or Shipping mode or by building the "UnrealInsights" project directly.

image alt text

Once you have located or built UnrealInsights.exe, you can run it on the machine that you want to use to record your data or view your live session.

Recording a Session

If you wish to enable Memory Trace Insights on a Source Build, navigate to Visual Studio and right-click on the Uproject.sln name > Properties > Debugging > Command Arguments > YourGame -trace=memory.

image alt text

If you have a Launcher build, you can create a shortcut to your .uproject file, then right-click on the shortcut and navigate to Properties, then in the Command field enter:

    `-trace=memory`.

Insights captures complete call stacks for each event in order to provide you with a complete analysis of your project's allocated memory.

Recording a session of your project requires the memory trace channel to be active from the beginning of the process. Otherwise it is not possible to start tracing allocation events in a late-connect session.

If everything is configured correctly, your UE5 session will appear in the Unreal Insights window, marked as "LIVE". You can then run through your test scenario, and Unreal Insights will record the data to your trace folder, which you can easily access through the Unreal Insights user interface.

image alt text

After starting Unreal Insights, it will open the Unreal Insight Session Browser, which contains the Trace Store panel (1), a directory which contains the Trace Sessions (2), and a connection menu panel (3).

If you want to view a session in real time, you can open that session in the Unreal Insights window.

Memory Allocation - Graph Tracks

The main interface for Memory Insights consists of a timeline showing an overview of memory usage during the session.

image alt text

The Memory Insights tracker shows information about the number of live allocations in memory. Pictured above is the Main Memory graph along with the Live Allocation and Free Event Count.

The Main Memory Graph shows the total amount of tracked memory in your project, including information on each tag gathered from LLM Additionally, there are graphs that display the total amount of live allocations:

Graph Type

Color

Description

Total Allocated Memory

Blue

Shows the total amount of memory allocated at each point in time, based on detailed allocation tracking.

Live Allocation Count

Yellow

Shows the total number of active allocations at any point in time.

Allocation Free Event Count

Green/Orange

Shows the number of allocation and free events per unit, which is represented as a "slice" of time.

Each of these graphs is based on detailed allocation tracking. They start at a time of 0 and have a granularity of approximately 1ms. The other graph series with the LLM prefix tags are based on a Low-Level Memory tracking runtime system. These tags will start tracking several seconds after the session has started and have a granularity of once per frame.

By default we emit one timestamp at each 4096 allocation / free event, You can change this amount if needed by modifying the MarkerSamplePeriod located in Engine/Source/Runtime/Core/Private/ProfilingDebugging/MemoryAllocationTrace.cpp. For example, setting this variable to 0 will emit a timestamp after each allocation / free event.

The Memory Insights timeline supports overlaying additional tracks onto the Timing Insights Window, such as bookmarks, asset loading and CPU/GPU timers.

The Timing Insights window is where you'll see per-frame performance data for different tracks along the CPU and GPU tracks. For additional information on toolbar tracks that can be made visible in this view, refer to the Timing Insights documentation.

When using Memory Insights view there are two panels available. The Investigation and LLM Tags panel.

Investigation panel

LLMTags Panel

  • The Investigation panel provides the capabilities to make different queries about allocations.investigation-panel

  • LLM Tags controls the visibility of different LLM Tags. llm-tags-panel

The previous runtime implementation of memory tracking is implemented in Engine\Source\Runtime\Core\Public\HAL\LowLevelMemTracker.h/.cpp The LLM Tags panel and the LLM graphs use data traced directly from this system. While the detailed allocations data comes from separate and specific trace implementation.

Querying Your Data

Memory Insights contains new querying features and tracked memory allocation information. You can identify blocks of memory that UE5 allocates and frees within certain time windows, before or after a specific moment in time, or even check for leaks. You can access the query system by navigating to the Investigation tab after opening a trace log.

Investigation - Allocation Queries

While the timeline provides an overview of memory usage, there are various queries that can be made to evaluate further details of the data . A Query is defined by a Rule and one or more Timestamps, such as the labels A and B.

image alt text

The Investigation panel contains Query rules to evaluate data.

The available Query Rules are as follows:

Query Rule

Time Variables

Description

Active Alloc

A

Shows all active allocations at time A.

Before

A

Shows all allocations before time A

After

A

Shows all allocations after time A

Decline

A and B

Shows all allocations that were allocated before time A and freed

Growth

A and B

Shows all allocations that were allocated between time A and B and freed after time B.

Growth Vs Decline

A and B

Identifies "growth" allocations, allocated between time A and time B and freed after time B.

"Decline" allocations are allocated before time A and freed between time A and time B.

The decline allocations are changed to have negative size, so the size aggregation shows variation between A and B.

Free Events

A and B

Shows all allocations that were freed between time A and B.

Alloc Events

A and B

Shows all allocations that were allocated between time A and B.

Short Living Allocs

A, B, and C

Shows all allocations that were allocated after time A and freed before time B. Can be used to identify allocations that could possibly be stack allocations.

Long Living Allocs

A, B, and C

Shows all allocations that were allocated before time A and freed after time B.

Memory Leaks

A, B, and C

Shows all allocations that were allocated between time A and B and not freed until after time C. This is useful to find memory that would be expected to be released at a given time, for example during a level transition.

Limited Lifetime

A, B, and C

Shows all allocations that were allocated between time A and B and freed between time B and C.

Decline of long living allocs

A, B, and C

Shows all allocations that were allocated before time A and freed between time B and C.

Specific lifetime

A, B, C, and D

Shows all allocations that were allocated between time A and B and freed between time C and D.

Queries are made by selecting a rule and dragging the labelled markers in the timeline to desired locations, or by specifying a time in the Investigation tab.

image alt text

Once the desired rules and times have been selected press the Run Query button in the Investigation tab to make the query.

image alt text

Depending on the query and data set that is being captured the queries may take a considerable amount of time to execute.

Allocation Breakdown View

When the query is run a new window will appear, upon completion of the query the table will be populated with the result. By default, these results will be displayed in a flat list. Each allocation is displayed with Size, Tag and the Function that made the allocations. Hovering over the function or the information icon will display additional details and the full call stack.

image alt text

Hovering over an allocation will display an information icon which can provide further details on the full call stack.

image alt text

The Full call stack displayed when hovering over the Information icon.

Sorting

Hover your mouse over a column to show all available sorting options. By clicking on the table headers, you can be sort the list into different groups.

image alt text

Grouping

It is common for a large number of allocations to be displayed on the table. In an effort to simplify sorting through patterns among the allocations, Memory Insights includes several types of Preset options that can be used to group allocations together.

image alt text

Navigating to Hierarchy and clicking All will open a drop-down menu to change the default Flat view into additional, alternative groups.

image alt text

Default

Shows the default allocations

Detailed

Configures the tree view to show detailed allocation information.

Heap

Investigates how different types of memory are used. See the "Multiple Addresses spaces" section below.

Size

Finds any large allocations quickly.

Tags

Displays the allocations per system.

Callstack

Investigates which call stack allocations are coming from. image alt text

Inverted Callstack

Configures the tree view to show a breakdown of allocations by Inverted Callstack. image alt text

Unique Value

Groups allocations into 4k aligned memory pages based on their address.

  • When grouped by Callstack or Inverted Callstack, the context menu will display the action to "Open in Visual Studio".

  • Pressing the "R" key shortcut will expand the critical path in the current tree.

Call Stack Symbol Resolving

Callstack tracing from your project is accomplished by using program counter addresses. In analysis these addresses need to be resolved to readable strings along with information about the corresponding source files.

This requires that Insights has access to the correct version of the file containing the debug information .pdb or .elf file depending on platform. Insights searches for the correct file according to the following list:

  1. Any new paths entered by the user this session.

  2. Path of the executable (if available).

  3. Paths from UE_INSIGHTS_SYMBOLPATH.

  4. Paths from the user configuration file.

Any time symbols have been resolved, the result is stored in the cache file. This provides the capability for users to open old trace files and use symbols even though the debug information for the traced version has been overwritten.

Symbol resolving is currently available on Win64, XB1/XSX, PS4/PS5 and Switch.

Multiple Address Spaces

Memory tracing tracks memory in different heaps. Conceptually, any allocation must belong to a root heap, representing one type of memory.

For example, on desktop platforms one root heap is the system memory, and the other is the video memory on the graphics card. Each root heap has its own address space.

Under each root heap, other heap allocations are made that can host allocations. This means virtual memory allocations which backs up allocations, but block style allocators can also be represented with heap allocations. This provides the investigation of utilization of those blocks of memory.