Profiler Tool Reference

Profiler is the replacement for Unreal Engine 3's StatsViewer tool and is used to monitor the performance of a game by collecting and tracking game data. This data can then be used to identify possible sources of slowdowns or hitches in your game.

If you are new to performance tuning, you may want to refer to the Performance and Profiling documentation first, as there are several tips in there that will help illustrate how to monitor your game's performance.

Enabling Profiler

There are two methods you can use to enable Profiler and collect data:

1. Live Connection
   • Run the game with the parameter -\messaging (for example: UE4Editor-Win64-Debug.exe -messaging).
   • Run the UFE with the parameter -\messaging (for example: UnrealFrontend-Win64-Debug.exe -messaging).
   • Select Session Frontend from the Developer Tools section of the Window menu bar, then select the Profiler tab.
2. Load previously captured data
   • By pressing the Load button on the toolbar from the Profiler tab and selecting a .ue4stats file.
   • By dropping a stats file from explorer or other file manager into the Profiler window.

You can also launch the stand-alone UnrealFrontEnd.exe from the C:\Program Files\Unreal Engine\4.3\Engine\Binaries\Win64 folder to gain access to Session FrontEnd and the Profiler tab. (Note: your version number may differ from the path above).

Profiler Window

Below is the Profiler window and UI components:

Click image for full view.

1. The Connected Session and Session Information window - used as the session to obtain the stats data.
2. The Main Toolbar window - contains basic global functionality.
3. The Data Graph Full window - provides a full view of the graphical presentation of stats.
4. The Data Graph window - is the graphical presentation of the stats.
5. The Filter and Presets window - contains all stats and groups (user can filter and sort these stats and groups).
6. The Event Graph window - shows the selected frame or frames as the event graph.

Main Toolbar

Below are descriptions of each action contained on the Main Toolbar:

Data Captured files are stored in the following location ...\UE4\Engine\Programs\UnrealFrontend\Saved\Profiling\UnrealStats\Received...

Filters and Presets

Below are descriptions of each action contained on the Main Toolbar:

How to Track Stats

There are three methods you can track stats:

1. Double-click on the selected stat to add/remove it from displaying on the Data Graph View.
2. Drag-and-drop it from the Stats/Groups Window into the Data Graph View (see the image below).
3. Drag-and-drop it from the Event Graph View.

If a stat is being tracked, it will be displayed in a different color and with an "*" symbol next to the name.

Also, you can see how many stats are being tracked in a group by looking at the second number in the () following the Group Name.

The image above for Audio, there are 11 items in the group, 1 of which is currently being tracked.

Data Graph

The Data Graph view displays all tracked stats. To stop tracking a stat, press the (X) button in front of the stats' text.

The stat's text consists of the following information and is broken down below:

1. (Group Name) - The Group Name of the stat.
2. Stat Name - The name of the stat.
3. Actual Value - The actual value of the stat.
4. Min Value - The minimum value based on the whole capture.
5. Avg Value - The average value based on the whole capture.
6. Max Value - The maximum value based on the whole capture.
7. Calls - The percent of frames with a call to this stat (for hierarchical data only).
8. Min Value - The minimum number of calls to this stat based on the whole capture (for hierarchical data only).
9. Avg Value - The average number of calls to this stat based on the whole capture (for hierarchical data only).
10. Max Value - The maximum number of calls to this stat based on the whole capture (for hierarchical data only).

The values denoted with for hierarchical data only are only displayed for hierarchical data and may not be displayed.

An explanation of the Data Graph axes are also outlined below:

• Bottom - Display the time from the beginning, starting from 0.0.
• Top - Display the frame number from the beginning, starting from 0.0.
• Left - Display adaptive information about time, in ms, based on the zoom level. Using the Mouse Wheel, there are three predefined axes for a game running at 30, 60 or 100 FPS each displayed in a different color.
• Right - Display adaptive information about other stats like float or memory. This axis has different scale than the left one due to the fact that float or memory values are usually larger than time related stats.

Right-clicking in the Data Graph window will also present a context menu with additional options:

• View Mode - At this time only Index based mode is supported (Time based mode is only available in the multisession mode of the Profiler and is an experimental feature disabled by default).
• Select All Frames - This selects all frames and updates the Event Graph View.
• Live Preview - This option is the same as presented in the main toolbar.

Event Graph

The Event Graph View consists of the following:

1. Title - Displays the current connected session name or the currently loaded stats file.
2. Event Graph Toolbar - Used for Event Graph filtering and other functionality.
3. Function Details - Detailed view of the selected event/function.
4. Main Event Graph - Hierarchical view of the selected frame or frames.

Event Graph Toolbar

Below are descriptions of each action contained on the Event Graph Toolbar:

Function Details

Function Details show relationships between a function/event that the user selects and the callings functions that executed the selected function/event. These relations are displayed using the buttons scaled accordingly to the percentage values.

The user can easily follow from the top event to the bottom event looking for the performance offenders. Function Details view is synchronized with the Main Event Graph in both ways, so selecting a new function will also select that function in the Main Event Graph.

Function Details consist of the following elements:

• Calling Functions - Shows the functions that called the selected function. The size of the widget is scaled based on the percentage values.
• Current Functions - Currently selected event/function in the Main Event Graph event.
• Called Functions - The functions called by the selected function. The size of the widget is scaled based on the percentage values.
  • - When this is shown, the event has been culled in the Main Event Graph window (more information on this in the next section).
  • - When this is shown, the event has been filtered out in the Main Event Graph window (more information on this in the next section).

Remember that hovering over the icon will display additional information about the item.

Main Event Graph

The Main Event Graph window shows the event execution paths. There is no one root, but each thread has its own starting event. This is usually indicated by the "thread" in the name or the numeric ID of the thread, such as "[0x1234]".

The Main Event Graph allows you to filter, cull, and many other functions. These functions are outlined below and are accessible by Right-clicking in the Main Event Graph window and choosing the desired action from the context menu that appears.