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.Attributes.Add("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 doesn't measure anything and doesn't produce any KPI.

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

Profiler.Enable(GameInitialization);

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

When the profiler is enabled, it is logged using the logging system through the standard Logger infrastructure, if ProfilingKeyFlags.Log is set for the ProfilingKey. 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 Attributes to attach a property value to a ProfilingState.

To register your own system to receive ProfilingEvents use the Subscribe() and Unsubscribe(ChannelReader<ProfilingEvent>) methods.

Properties

MinimumProfileDuration

The minimum duration of events that will be captured. Defaults to 1 µs.

public static TimeSpan MinimumProfileDuration { get; set; }

Property Value

TimeSpan

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

AppendTime(StringBuilder, TimeSpan)

public static void AppendTime(StringBuilder builder, TimeSpan accumulatedTimeSpan)

Parameters

builder StringBuilder

accumulatedTimeSpan TimeSpan

Begin(ProfilingKey)

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)

Parameters

profilingKey ProfilingKey

The profile key.

Returns

ProfilingState

A profiler state.

Remarks

It is recommended to call this method with using (Profiler.Begin(...)) {...} or using var _ = Profiler.Begin(...); 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 = null, 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 (Profiler.Begin(...)) {...} or using var _ = Profiler.Begin(...); 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()

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 (Profiler.Begin(...)) {...} or using var _ = Profiler.Begin(...); 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()

Subscribe()

Subscribes to the generated ProfilingEvents.

public static ChannelReader<ProfilingEvent> Subscribe()

Returns

ChannelReader<ProfilingEvent>

The ChannelReader<T> which will receive the events.

Unsubscribe(ChannelReader<ProfilingEvent>)

Unsubscribes from receiving ProfilingEvents.

public static void Unsubscribe(ChannelReader<ProfilingEvent> eventReader)

Parameters

eventReader ChannelReader<ProfilingEvent>

The reader previously returned by Subscribe()