Class Profiler

Namespace

Stride.Core.Diagnostics

Assembly

Stride.Core.dll

High level CPU Profiler. For usage see remarks.

public static class Profiler

Inheritance

object

Profiler

Remarks

This class is a lightweight profiler that can log detailed KPI (Key Performance Indicators) of an application. To use it, simply enclose in a using code the section of code you want to profile:

public static readonly ProfilingKey GameInitialization = new ProfilingKey("Game", "Initialization");

// This will log a 'Begin' profiling event.
using (var profile = Profiler.Begin(GameInitialization))
{
    // Long running code here...


    // You can log 'Mark' profiling event
    profile.Mark("CriticalPart");

    // Adds an attribute that will be logged in End event
    profile.SetAttribute("ModelCount", modelCount);
} // here a 'End' profiling event will be issued.

By default, the profiler is not enabled, so there is a minimum performance impact leaving it in the code (it has the costs of a lock and a dictionary lookup). It doesn't measure anything and doesn't produce any KPI.

To enable a particular profiler (before using Begin(ProfilingKey, string) method):

Profiler.Enable(GameInitialization);

To enable all profilers, use Profiler.Enable() method.

When the profiler is enabled, it is logged using the logging system through the standard Logger infrastructure. The logger module name used is "Profile." concatenates with the name of the profile.

Note also that when profiling, it is possible to attach some property values (counters, indicators...etc.) to a profiler state. This property values will be displayed along the standard profiler state. You can use SetAttribute(string, object) to attach a property value to a ProfilingState.

Fields

GpuTimestampFrequencyRatio

public static double GpuTimestampFrequencyRatio

Field Value

double

Methods

AppendTime(StringBuilder, long, long)

Append the provided time properly formated at the end of the string. tickFrequency is used to convert the ticks into time. If tickFrequency is 0 then Frequency is used to perform the calculation.

public static void AppendTime(StringBuilder builder, long accumulatedTicks, long tickFrequency = 0)

Parameters

builder StringBuilder

accumulatedTicks long

tickFrequency long

Begin(ProfilingKey, string)

Creates a profiler with the specified key. The returned object must be disposed at the end of the section being profiled. See remarks.

public static ProfilingState Begin(ProfilingKey profilingKey, string text = null)

Parameters

profilingKey ProfilingKey

The profile key.

text string

The text to log with the profile.

Returns

ProfilingState

A profiler state.

Remarks

It is recommended to call this method with using (var profile = Profiler.Profile(...)) in order to make sure that the Dispose() method will be called on the ProfilingState returned object.

Begin(ProfilingKey, string, ProfilingCustomValue, ProfilingCustomValue?, ProfilingCustomValue?, ProfilingCustomValue?)

Creates a profiler with the specified key. The returned object must be disposed at the end of the section being profiled. See remarks.

public static ProfilingState Begin(ProfilingKey profilingKey, string textFormat, ProfilingCustomValue value0, ProfilingCustomValue? value1 = null, ProfilingCustomValue? value2 = null, ProfilingCustomValue? value3 = null)

Parameters

profilingKey ProfilingKey

The profile key.

textFormat string

The text to format.

value0 ProfilingCustomValue

First value (can be int, float, long or double).

value1 ProfilingCustomValue?

Second value (can be int, float, long or double).

value2 ProfilingCustomValue?

Third value (can be int, float, long or double).

value3 ProfilingCustomValue?

Fourth value (can be int, float, long or double).

Returns

ProfilingState

A profiler state.

Remarks

It is recommended to call this method with using (var profile = Profiler.Profile(...)) in order to make sure that the Dispose() method will be called on the ProfilingState returned object.

Begin(ProfilingKey, string, params object[])

Creates a profiler with the specified key. The returned object must be disposed at the end of the section being profiled. See remarks.

public static ProfilingState Begin(ProfilingKey profilingKey, string textFormat, params object[] textFormatArguments)

Parameters

profilingKey ProfilingKey

The profile key.

textFormat string

The text to format.

textFormatArguments object[]

The text format arguments.

Returns

ProfilingState

A profiler state.

Remarks

It is recommended to call this method with using (var profile = Profiler.Profile(...)) in order to make sure that the Dispose() method will be called on the ProfilingState returned object.

Disable(ProfilingKey)

Disables the specified profiler.

public static void Disable(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

The profile key.

DisableAll()

Disable all profilers.

public static void DisableAll()

Enable(ProfilingKey)

Enables the specified profiler.

public static void Enable(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

The profile key.

EnableAll()

Enables all profilers.

public static void EnableAll()

GetEvents(ProfilingEventType, bool)

Retrieve the selected type of events and returns the number of elapsed frames.

public static FastList<ProfilingEvent> GetEvents(ProfilingEventType eventType, bool clearOtherEventTypes = true)

Parameters

eventType ProfilingEventType

The type of events to retrieve

clearOtherEventTypes bool

if true, also clears the event types to avoid event over-accumulation.

Returns

FastList<ProfilingEvent>

The profiling events.

IsEnabled(ProfilingKey)

Enables the specified profiler.

public static bool IsEnabled(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

The profile key.

Returns

bool

New(ProfilingKey)

Creates a profiler with the specified name. The returned object must be disposed at the end of the section being profiled. See remarks.

public static ProfilingState New(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

The profile key.

Returns

ProfilingState

A profiler state.

Remarks

It is recommended to call this method with using (var profile = Profiler.Profile(...)) in order to make sure that the Dispose() method will be called on the ProfilingState returned object.

ProcessEvent(ref ProfilingEvent, ProfilingEventType)

public static void ProcessEvent(ref ProfilingEvent profilingEvent, ProfilingEventType eventType)

Parameters

profilingEvent ProfilingEvent

eventType ProfilingEventType

Reset()

Resets the id counter to zero and disable all registered profiles.

public static void Reset()