Standard Profiling
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 testlocation
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 testframe_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 framephysical_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.