Standard Profiling

Last updated on June 13, 2024

Overview​

You can use AccelByte Development Toolkit (ADT) CLI to store and view performance data from your game sessions and tests. Your tests should be able to record frame-by-frame performance statistics and generate output in a JSON file. This guide shows you how to set up standard profiling.

Performance test output​

Your performance test will have two types of output:

  • UE4 Log: This log will be printed in the command line if you run it in the command line, or in the Unreal Engine 4 (UE4) log window if you run it in UE4 editor. By default, the logs will be saved in the following directory: 
 \<ProjectRoot>\ProjectName\Saved\Logs
  • ADT Log files: The test should generate n-number of ADT log files. Each file contains test results from one level of your game. The file should be in JSON lines format. The layout of the ADT log file should be as follows: 
<header>
---
<body>

Each time the UE4 automates test runs, it generates an ADT log file. The path can be anywhere and it will be used later to upload the file through the ADT CLI. For example:

\<ProjectRoot>\ProjectName\Saved\AutomationTest\PerformanceTest\PerformanceTest_Windows_Level1.json

ADT log files​

Test result header​

The <header> part should be:

{
  "@encoding": "blackbox/performancetest+json.v1.0.1"
}

The "@encoding" is the encoding version of this ADT log file. This encoding enables ADT Web to recognize the format of this file.

Test result body​

The <body> part should be:

{map: "", location: "", frame_no: "", total_run_time: ", "frame_time: "", game_time: "", gpu_time: "", draw_time: "", fps: "", physical_memory_usage: ""}
  • map is the level name of current test
  • location is the location name in the map where the current row generated.
  • frame_no is the frame number of the current test. starts at 0.
  • total_run_time is total time spent doing the test
  • frame_time is time between each frame. value is in ms.
  • game_time is time needed for the CPU to render the current frame. value is in ms.
  • gpu_time is time needed for the GPU to render the current frame. value is in ms.
  • draw_time is time needed to do the draw call to the GPU. value is in ms.
  • fps is the fps recorded in this frame
  • physical_memory_usage is the memory usage recorded in this frame

Examples of test results​

Here is an example of a sample ADT Log file. Your file should follow this format.

{
  "@encoding": "blackbox/performancetest+json.v1.0.1", "location": "Level_1"
}
---
{"map":"Escape_Persistent","location":"StartOfLevel","frame_no":1,"total_run_time":9.1677160263061523, "frame_time":916.7716064453125,"game_time":24.550630569458008,"gpu_time":794.19097900390625,"draw_time":0.092030003666877747,"fps":1.0907841920852661,"physical_memory_usage":12586881024}
{"map":"Escape_Persistent","location":"StartOfLevel","frame_no":2,"total_run_time":10.1677160263061523, "frame_time":1078.765869140625,"game_time":48.986068725585938,"gpu_time":1041.8829345703125,"draw_time":0.21141700446605682,"fps":0.92698520421981812,"physical_memory_usage":12632846336}
{"map":"Escape_Persistent","location":"Helipad","frame_no":3,"total_run_time":11.1677160263061523, "frame_time":1062.9801025390625,"game_time":54.457942962646484,"gpu_time":1264.8056640625,"draw_time":0.31886529922485352,"fps":0.94075137376785278,"physical_memory_usage":12636585984}
---
{"test_id": "25D53E184192CDEA948125A38F6D0920"}

Get frame statistics​

Here's how to get the UE4 frame statistics that we suggest (taken from UnrealClient.cpp)

Frame time

const float RawFrameTime = (FApp::GetCurrentTime() - FApp::GetLastTime()) * 1000.f;
if (FrameTime == 0.0f) FrameTime = RawFrameTime;
else FrameTime = 0.9 * FrameTime + 0.1 * RawFrameTime;

Game time

const float RawGameTime = FPlatformTime::ToMilliseconds(GGameThreadTime);
if (GameThreadTime == 0.0f) GameThreadTime = RawGameTime;
else GameThreadTime = 0.9 * GameThreadTime + 0.1 * RawGameTime;

GPU time

const float RawGPUFrameTime = FPlatformTime::ToMilliseconds(GGPUFrameTime);
if (GPUFrameTime == 0.0f) GPUFrameTime = RawGPUFrameTime;
else GPUFrameTime = 0.9 * GPUFrameTime + 0.1 * RawGPUFrameTime;

Draw time

const float RawDrawTime = FPlatformTime::ToMilliseconds(GRenderThreadTime);
if (DrawTime == 0.0f) DrawTime = RawDrawTime;
else DrawTime = 0.9 * DrawTime + 0.1 * RawDrawTime;

Frame per second (FPS)

float fps = 1000.0f / FMath::Clamp(FrameTime, 0.00001f, FLT_MAX));

Physical memory usage

Int64 PhysicalMemoryUsage = int64(FPlatformMemory::GetStats().UsedPhysical);

Use Unreal Insights​

Our performance test can produce reports in the format of UE4's application profiling tool, Unreal Insights. To make a performance test produce the results in the Unreal Insight .utrace file type, add the -trace command to the performance test:

-trace="<channel1>,<channel2>,..." -tracefile="<TargetPath>/PerformanceTest_<Platform>_<level>.utrace"

As listed in UE4 documentation, the available trace channels are:

  • Log
  • Bookmark
  • Frame
  • CPU
  • GPU
  • LoadTime
  • File
  • Net

Use the -tracefile command to specify:

  • Where the *.utrace file is stored
  • The *.utrace performance test file name following the ADT log file name format: PerformanceTest_<platform>_<level>.json
  • Where <platform> can be Windows, macOS, iOS, Android, PS4, Xbox One, or Linux. This can be retrieved from UE4's GetPlatformName function.
Last updated on

On this page