Profiling

Rokas Kupstys edited this page Jul 6, 2017 · 4 revisions

Atomic features realtime performance and memory metrics on desktop and mobile devices. Profiling can be selected from the Atomic Editor Tools menu, enabled in code, or specified on the command line.

Once enabled in the Atomic Editor, you will see profiling data for the editor itself. While profiling is on, player sessions will also display profiling data by default.

Performance Profiling

Profiling performance gives a hierarchical breakdown of individual engine methods

Hierarchical application performance profiling of a basic 3d scene

Atomic is using easy_profiler (documentation). You can see not only how long application spends executing certain code blocks, but also exact times when code was executed. This is very convenient for pinpointing less obvious performance issues like microstuttering.

Building with profiler support

In order to build profiler you need to install Qt5.

Linux

Use package manager to install packages providing Qt5. Package names may vary by distribution.

MacOS

Use homebrew to install latest available Qt. For example: brew install qt@5.7. Then set CMAKE_PREFIX_PATH to the root folder of Qt installation, for example ./CMake_makefile.sh -DCMAKE_PREFIX_PATH=/opt/Qt5.7.

Windows

Download Qt from official website and install SDK. Pay attention to runtime Qt links against. For example if you are building project using Visual Studio 2017 make sure you get Qt that links against msvc2017 runtime. Then set CMAKE_PREFIX_PATH to the root folder of Qt installation, for example CMake_VS2017.bat -DCMAKE_PREFIX_PATH=C:/Qt/Qt5.9.1/msvc2017_64.

Profiler usage

In order to profile your own code you have to wrap portions of the code as profiler blocks. Then you should start your application and profiler GUI tool. Tool is built to AtomicGameEngine/Artifacts/Build/Profiler folder. Press Connect button in profiler application toolbar to connect to application. You may need to change address and port should you set custom port in application when calling Profiler::StartListen(<your_port>) or if you would like to profile application running on other device (like mobile phone).

In order to display block hierarchy in lower panel hold Shift and right-click-select blocks in upper panel.

If you would like to profile blocks on other threads than main one consider naming your threads by adding ATOMIC_PROFILE_THREAD(ThreadName) statement before any profiled blocks.

Examples how to mark sections of code for profiling:

C++

void Application::Start()
{
    GetSubsystem<Profiler>()->StartListen();
}

void Function()
{
    ATOMIC_PROFILE(MyBlock)
    // Your code named "MyBlock"
    ATOMIC_PROFILE_END()

    // Code that will not show up as profiler block

    ATOMIC_PROFILE(MyOtherBlock)
    // Your code named as "MyOtherBlock"
}

In c++ it is not necessary to terminate blocks with ATOMIC_PROFILE_END() as it will be done automatically when execution leaves current scope.

C#

void Start()
{
    GetSubsystem<Profiler>().StartListen();
}

void SomeMethod()
{
    Profiler.Block("SomeBlock", () => {
        // Code named "SomeBlock".
    });

    // Unprofiled code.

    Profiler.BeginBlock("OtherBlock");
    // Code named "OtherBlock".
    Profiler.EndBlock();
}

In C# every block started with Profiler.BeginBlock() must be terminated with Profiler.EndBlock(), otherwise application will crash.

Memory Metrics

Atomic has robust object tracking to help catch object leaks and related memory issues. The Metrics subsystem also tracks whether native, C#, or JavaScript/TypeScript code instantiated objects. Metrics tracking is selected in the Atomic Editor Tools menu in the Profiler submenu.

Object Tracking

When memory metrics are enabled, objects are tracked and instance counts can be displayed

Enabling metrics from code

Example C# to enable metrics subsystem

// Objects instances created from this point will be tracked
GetSubsystem<Metrics>().Enable();

// Show the hud
var ui = GetSubsystem<UI>();
ui.ShowDebugHud(true);
ui.SetDebugHudProfileMode(DebugHudProfileMode.DEBUG_HUD_PROFILE_METRICS);

Autometrics and Player Metrics (Advanced)

The --autometrics command line option can be specified for both the Atomic Editor and player applications. This will automatically enable the Metrics subsystem and begin tracking objects starting with the Engine subsystem. When running the Atomic Editor with autometrics enabled, player sessions will also have autometrics enabled.

The --playermetrics command line option can be specified for player applications. This will automatically enable the Metrics subsystem and begin tracking objects starting at the beginning of application code (after the engine subsystems are created).

When autometrics are enabled, object tracking begins with the Engine subsystem for deep tracking of core objects

Example C# of setting autometrics from code

public class Program
{
    public static void Main(string[] args)
    {
        // Capture all metrics, including engine subsystems, etc
        // Autometrics must be set before the Application instance is created
        Application.SetAutoMetrics(true);

        Application.Run<AtomicMain>(args);
    }
}

Metrics command line options also work when launching from Visual Studio

Example of adding --autometrics to Visual Studio C# command line options to track all engine objects

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.