Unreal Engine 5 Documentation has been moved to the Epic Developer Community

The Stats System enables you to collect and display performance data so that it can be used to optimize your game.

Types

The Stats System supports the following types:

Grouping Stats

Each stat must be grouped, which usually corresponds with displaying the specified stat group. For example, stat statsystem displays stats' related data.

To define a stat group, use one of the following methods:

Where:

• GroupDesc is a text description of the group

• GroupId is a UNIQUE id of the group

• GroupCat is reserved for future use

• CompileIn , the compiler may strip it out if it is set to true

Example Usage

DECLARE_STATS_GROUP(TEXT("Threading"), STATGROUP_Threading, STATCAT_Advanced);
DECLARE_STATS_GROUP_VERBOSE(TEXT("Linker Load"), STATGROUP_LinkerLoad, STATCAT_Advanced);

Declaring and Defining Stats

Now, you can declare and define a stat, but before you do, note that a stat can be used in:

• Only one cpp file

• The function scope

• The module scope

• The whole project

For a Single File

For the scope of a single file, you must use one of the following methods, depending on the stat type:

For Multiple Files

If you want to have stats accessible to the whole project (or for a wider range of files) you need to use extern version. These methods are the same as the previously mentioned but with _EXTERN and the end of the name:

DECLARE_CYCLE_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_FLOAT_COUNTER_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_DWORD_COUNTER_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_FLOAT_ACCUMULATOR_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_DWORD_ACCUMULATOR_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_MEMORY_STAT_EXTERN(CounterName, StatId, GroupId, API)
DECLARE_MEMORY_STAT_POOL_EXTERN(CounterName, StatId, GroupId, Pool, API)

Then in the source file, you need to define these stats with the following, which defines stats that are declared with _EXTERN :

Where:

• CounterName is a text description of the stat

• StatId is a UNIQUE id of the stat

• GroupId is the id of the group that the stat will belong to, the GroupId from DECLARE_STATS_GROUP*

• Pool is a platform-specific memory pool

• API is the *_API of a module, and it can be empty if the stat will only be used in that module

Examples

Custom Memory Stats with Pools

First you need to add a new pool to enum EMemoryCounterRegion , which can be global or platform specific:

enum EMemoryCounterRegion
{
    MCR_Invalid,        // not memory
    MCR_Physical,       // main system memory
    MCR_GPU,            // memory directly a GPU (graphics card)
    MCR_GPUSystem,      // system memory directly accessible by a GPU
    MCR_TexturePool,    // pre-sized texture pools
    MCR_MAX
};

The following is an example that will allow using the pools everywhere (see CORE_API ).

Header File Sample

DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Physical Memory Pool [Physical]"), MCR_Physical, STATGROUP_Memory, FPlatformMemory::MCR_Physical, CORE_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("GPU Memory Pool [GPU]"), MCR_GPU,STATGROUP_Memory, FPlatformMemory::MCR_GPU, CORE_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Texture Memory Pool [Texture]"), MCR_TexturePool, STATGROUP_Memory, FPlatformMemory::MCR_TexturePool,CORE_API);

Source File Sample

DEFINE_STAT(MCR_Physical);
DEFINE_STAT(MCR_GPU);
DEFINE_STAT(MCR_TexturePool);

// This is a pool, so it needs to be initialized - typically in F*PlatformMemory::Init().
SET_MEMORY_STAT(MCR_Physical, PhysicalPoolLimit);
SET_MEMORY_STAT(MCR_GPU, GPUPoolLimit);
SET_MEMORY_STAT(MCR_TexturePool, TexturePoolLimit);

// Now that we have pools, we can set up memory stats for them.

// The following are accessible everywhere.         
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Index buffer memory"), STAT_IndexBufferMemory, STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Vertex buffer memory"), STAT_VertexBufferMemory, STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Structured buffer memory"), STAT_StructuredBufferMemory,STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Pixel buffer memory"), STAT_PixelBufferMemory, STATGROUP_RHI, FPlatformMemory::MCR_GPU, RHI_API);

// The following are only accessible in the module where they were defined. 
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Pool Memory Size"), STAT_TexturePoolSize, STATGROUP_Streaming, FPlatformMemory::MCR_TexturePool, );
DECLARE_MEMORY_STAT_POOL_EXTERN(TEXT("Pool Memory Used"), STAT_TexturePoolAllocatedSize, STATGROUP_Streaming, FPlatformMemory::MCR_TexturePool, );

// And the last thing, we need to update the memory stats.

// Increases the memory stat by the specified value.
INC_MEMORY_STAT_BY(STAT_PixelBufferMemory,NumBytes);
// Decreases the memory stat by the specified value.
DEC_MEMORY_STAT_BY(STAT_PixelBufferMemory,NumBytes);
// Sets the memory stat by the specified value.
SET_MEMORY_STAT(STAT_PixelBufferMemory,NumBytes);

Regular Memory Stats Without Pools

DECLARE_MEMORY_STAT(TEXT("Total Physical"), STAT_TotalPhysical, STATGROUP_MemoryPlatform);
DECLARE_MEMORY_STAT(TEXT("Total Virtual"), STAT_TotalVirtual, STATGROUP_MemoryPlatform);
DECLARE_MEMORY_STAT(TEXT("Page Size"), STAT_PageSize, STATGROUP_MemoryPlatform);
DECLARE_MEMORY_STAT(TEXT("Total Physical GB"), STAT_TotalPhysicalGB, STATGROUP_MemoryPlatform);

Or, if you prefer, you can DECLARE_MEMORY_STAT_EXTERN in the header file and then DEFINE_STAT in the source file.

Performance Data Using Cycle Counters

First, you need to add cycle counters:

DECLARE_CYCLE_STAT(TEXT("Broadcast"), STAT_StatsBroadcast, STATGROUP_StatSystem);
DECLARE_CYCLE_STAT(TEXT("Condense"), STAT_StatsCondense, STATGROUP_StatSystem);

Or, you can DECLARE_CYCLE_STAT_EXTERN in the header file and then DEFINE_STAT in the source file.

Now, you can grab the performance data:

Stats::Broadcast()
{
    SCOPE_CYCLE_COUNTER(STAT_StatsBroadcast);
    // ...
    // a piece of code
    // ...
}

Sometimes, you do not want to grab the stats every time the function is called, so you can use a conditional cycle counter — it is not very common, but it may be useful:

Stats::Broadcast(bool bSomeCondition)
{

    CONDITIONAL_SCOPE_CYCLE_COUNTER(STAT_StatsBroadcast,bSomeCondition);
    // ...
    // a piece of code
    // ...
}

If you want to grab the performance data from one function, you can use the following construction:

Stats::Broadcast(bool bSomeCondition)
{
    DECLARE_SCOPE_CYCLE_COUNTER(TEXT("Broadcast"), STAT_StatsBroadcast, STATGROUP_StatSystem);
    // ...
    // a piece of code
    // ...
}

You can also do the following:

Stats::Broadcast(bool bSomeCondition)
{
    QUICK_SCOPE_CYCLE_COUNTER(TEXT("Stats::Broadcast"));
    // ...
    // a piece of code
    // ...
}

All of the previously mentioned cycle counters are used to generate the hierarchy so that you can get more detailed information about performance data. However, there is also the option of setting a flat cycle counter:

Stats::Broadcast(bool bSomeCondition)
{
    const uint32 BroadcastBeginTime = FPlatformTime::Cycles();
    // ...
    // a piece of code
    // ...
    const uint32 BroadcastEndTime = FPlatformTime::Cycles();
    SET_CYCLE_COUNTER(STAT_StatsBroadcast, BroadcastEndTime-BroadcastBeginTime);
}

Performance Data Using GetStatId

A few tasks implemented in Unreal Engine use a different approach in terms of getting the performance data. They implement method GetStatId() , and if there is no GetStatId() , the code will not compile.

Here is an example:

class FParallelAnimationCompletionTask
{
    // ...
    // a piece of code
    // ...
    FORCEINLINE TStatId GetStatId() const
    {
        RETURN_QUICK_DECLARE_CYCLE_STAT(FParallelAnimationCompletionTask, STATGROUP_TaskGraphTasks);
    }
    // ...
    // a piece of code
    // ...
};

Logging Performance Data

If you just want to log performance data, we provide the following functionality:

Method

The following method captures the time (passed in seconds), and adds delta time to the variable that is passed in:

SCOPE_SECONDS_COUNTER(double& Seconds)

Code Sample

Stats::Broadcast()
{
    double ThisTime = 0;
    {
       SCOPE_SECONDS_COUNTER(ThisTime);
        // ...
        // a piece of code
        // ...
    }
    UE_LOG(LogTemp, Log, TEXT("Stats::Broadcast %.2f"), ThisTime);  
}

Utility Class and Methods

Code Sample

double GMyBroadcastTime = 0.0;
Stats::Broadcast()
{
    SCOPE_LOG_TIME("Stats::Broadcast", &GMyBroadcastTime);
    SCOPE_LOG_TIME_IN_SECONDS("Stats::Broadcast (sec)", &GMyBroadcastTime);
    // ...
    // a piece of code
    // ...
}

Stats::Condense()
{
    SCOPE_LOG_TIME_FUNC(); // The name should be "Stats::Condense()", may differ across compilers
    SCOPE_LOG_TIME_FUNC_WITH_GLOBAL(&GMyBroadcastTime);
    // ...
    // a piece of code
    // ...
}

Generic Data Using FLOAT or DWORD Counters

Generally, the first thing you need to do is add your counters, such as the following:

DECLARE_FLOAT_COUNTER_STAT_EXTERN(STAT_FloatCounter,StatId,STATGROUP_TestGroup, CORE_API);
DECLARE_DWORD_COUNTER_STAT_EXTERN(STAT_DwordCounter,StatId,STATGROUP_TestGroup, CORE_API);
DECLARE_FLOAT_ACCUMULATOR_STAT_EXTERN(STAT_FloatAccumulator,StatId,STATGROUP_TestGroup, CORE_API);
DECLARE_DWORD_ACCUMULATOR_STAT_EXTERN(STAT_DwordAccumulator,StatId,STATGROUP_TestGroup, CORE_API);

Then, to update and manage your counters, you can use the following methods:

Methods to Update Counters

Helper Methods to Manage Counters