Memory Insights

Trace and analyze memory usage in real time with Memory Insights, part of the Unreal Insights performance analysis tool.

Windows
MacOS
Linux

Unreal Engine 5 (UE5) expands the capabilities of Unreal Insights by adding memory leak detection and improved tracking and profiling support into its Memory Insights feature. Developers can now see more detailed information about memory allocation and deallocation, including the 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

Unreal Insights is included with UE5, but exists a separate, standalone program. To start working with Unreal Insights, make sure that you have a compiled executable. Go into your source directory and find the /Engine/Binaries/Win64/ path. If UnrealInsights.exe is present, you can run it to begin listening for game sessions. If you cannot find it, open the UE5 solution file in your programming IDE and look for the UnrealInsights project within the Programs folder. Compile this code and run the resulting executable.

Recording a Session

When you want to record a session, run Unreal Insights before the UE5 editor or project that you want to profile. In the future, Unreal Insights will be able to connect with UE5 sessions that are already running, but at this time, you must start Unreal Insights before the UE5 editor or your compiled UE5 project. Use the following command-line arguments when running UE5 to track memory usage information and report it to Unreal Insights:

  • -tracehost=address: Replace address with the network address of the machine running Unreal Insights, and UE5 will send data to it. You can replace address with localhost if you are running Unreal Insights on the same machine, although this will have a greater impact on performance than running Unreal Insights on a separate machine.

  • -trace=channel1[,channel2[,channelN]]: This option tells UE5 to create and transmit specific types of data for Unreal Insights. Replace the channel* arguments with the channel names you want to record. The following channel names are useful with Memory Insights:

    • memory: Captures and reports all Memory Insights data. This includes every allocation and free, with callstacks. This is a good default for new users to learn about the system, but it produces large trace files.

For developers running UE5 on Win64 systems, these channels provide more precise control over what data UE5 will send to Unreal Insights. The following channels are meaningful only if the memory channel is not specified:

  • memalloc: Captures information related to memory allocation. This channel (or memory) is required to use Memory Insights.

  • callstack: Stores the function callstack that led to each memory allocation.

  • module: Tracks information about runtime modules (such as the main UE5 executable and DLLs); this is required for resolving callstack symbols.

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. If you want to view a session in real time, you can open that session in the Unreal Insights window. However, viewing a live session is independant from recording the session to a file; Unreal Insights will record all sessions that it observes regardless of whether or not a user watches it as the data comes in.

UnrealInsights.png

Unreal Insights, capturing its first live session.

When you hold the mouse cursor over a session in the Sessions Browser, you can see several important pieces of information about that session log, including the arguments that you sent to UE5.

MouseOverInfo.png

Sample mouseover information for an Unreal Insights trace log.

Querying Your Data

Memory Insights contains new querying features 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. Access the query system by going to the Investigation tab after opening a trace log.

InvestigationTab.png

Configure and launch queries from the Investigation tab.

After you select a query type, one or more text entry boxes, labeled A through D, will appear. Fill these out with values for the variables that your query uses either by typing them in directly, or by mouse-dragging the appropriate Time Markers along the ruler at the top of the Timing view.

TimeMarkers.png

A query with four variables. You can adjust their values by typing directly into the panel on the right, or mouse-dragging the Time Markers on the left.

Once you have selected your query type and input your values, you can designate a new or existing window to contain your results, and press the Run Query button. This will open an Allocs Table tab in a separate window, where you can view the results of your query. The full range of queries in the current version of Memory Insights follows:

Query Type

Time Variables (ascending order)

Resulting Data

Active Allocs

A

A snapshot of all currently-allocated memory as of time A.

Before

A

All memory allocated and freed before A.

After

A

All memory allocated and freed after A.

Decline

A and B

Memory allocated before A, then freed after A but before B.

Growth

A and B

Memory allocated after A but before B, and not freed until after B.

Short Living Allocs

A and B

All memory allocations that happen after A, but are freed before B.

Long Living Allocs

A and B

All memory allocations that happen before A, and are not freed until after B.

Memory Leaks

A, B, and C

Memory that is allocated between A and B, and is still not freed as of time C.

Limited Lifetime

A, B, and C

Memory allocations that happen after A, last through B, and are freed before C.

Decline of Long Living Allocs

A, B, and C

Allocations from before A that are freed between B and C.

Specific Lifetime

A, B, C, and D

Allocations that happen between A and B, and are freed between C and D.

Your results will appear in a tab, labeled Allocs Table, within a separate window.

AllocsTable.png

The Allocs Table tab, which opens in a separate window and displays query results. In this image, two queries have opened tabs within the same window.

After querying information, Memory Insights can filter, sort, and aggregate the data in the Allocs Table tab by one or more of the following fields:

  • The number of blocks allocated (within a group).

  • The size of a memory allocation.

  • The category (LLM Tag) associated with the allocation.

  • The function callstack leading to the allocation, if that callstack tracking was enabled in UE5 while recording the session, or the inverse of that callstack.

Sorting

Click on a column to sort your results by the column's value. You can sort by ascending or descending value. Right-click a column to show all available options.

SortedBySize.png

This view shows all allocations made after ten seconds into the session, sorted in ascending size order.

Grouping

You can expand the Hierarchy heading (not the Hierarchy column) to add groupings. By default, Memory Insights provides a single grouping, labeled All. By clicking the > symbol, you can create layer of subgroups. Each subgroup will exist in its own layer of the hierarchy in the main graph view. You can also move, reset, remove, or change groupings after creating them.

As an example, the following view uses size grouping:

GroupedResults.png

This view shows all allocations made after ten seconds into the session, grouped by size. The groups are sorted by total size, in ascending order.

Adding a subgrouping by function looks like this:

GroupedResults2.png

This view is the same as the previous view, but now you can break each size group down by function.

Advanced Filters

Within an Allocs Table* tab, you can press the Advanced Filters to open the Filter Configurator** window. Here, you can configure your own filtering and grouping. Use this if you need specific information that none of the predefined options provides.

AdvancedFilter1.png

This custom filter finds all allocations that occurred between ten and twenty seconds into the session, and held onto the allocated memory for less than one minute.

The filters and groups that you set up can accept results that match any or all of the conditions that you describe. In this view, you have access to the following variables:

Variable Name

Value Type

Description

Start Time

Numerical

When the memory was allocated

End Time

Numerical

When the memory was freed

Duration

Numerical

How much time passed between allocating and freeing the memory

Address

Numerical

The base address of the memory

Allocation Count

Numerical

Size

Numerical

The size of the block of memory

LLM Tag

String

The LLM tag (category) of the allocation

Function

String

The function that requested the allocation

Full Callstack

String

The full callstack of functions leading to the allocation request

Numerical values support basic comparison operations: Less than, less than or equal to, equal to, greater than, and greater than or equal to.

String values support two comparison operations: Equal to, and contains.

All comparison operations are performed against a user-provided constant value of the same type as the variable.

By using groups, you can collect allocations in ways that a series of ungrouped filters could not. For example, the following filter collects all allocations that are exactly one byte, or that are at least 1024 bytes:

AdvancedFilter2.png

By putting the two mutually-exclusive size filters into different groups, this configuration collects allocations that exclude a specific size range.

Running this filter configuration on the results of a query for all allocations that happened after ten seconds yields customized results.

AdvancedFilter2Results.png

Sorted by size (ascending), you can see the break point between the "single byte" and the "kilobyte or larger" allocations that happened after ten seconds in our session.

After configuring your filters, you can press OK to apply them and return to the Alloc Table, which will recalculate your view of the data based on your filter settings, or press Cancel to return without altering your results. When you go return, you can apply sorting and grouping to your customized results.