Table of Contents

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 a game. To use it, simply enclose your code in a using (var profile = Profiler.Begin(...)) block:

// Keys can also be created without a parent
public static readonly ProfilingKey GameInitialization = new ProfilingKey(ParentKey, "Initialization");

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

    // You can log 'Mark' profiling event to indicate a specific part of code was executed
    profile.Mark("CriticalPart");
} // here's where the code stops being profiled and information is collected

Here are the most important things to keep in mind:

  • Profiler - collects information from all profiles
  • Profile - collects information for a specific chunk of code
  • Key - represents a profile using a unique identifier

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 collect any data.

To enable a particular profile (before using Begin(ProfilingKey) method), use:

Profiler.Enable(GameInitialization);

To enable all profiles, use:

Profiler.EnableAll();

When a profile has ProfilingKeyFlags.Log set in its key, its events will get logged using the standard Logger infrastructure while it's enabled. Note also that it is possible to pass up to 4 additional values along with a message when beginning, ending or marking a profile.

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)

Appends the provided time to the end of the string using a standardized format. See remarks for more details.

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

Parameters

builder StringBuilder

The string builder to append time.

accumulatedTicks long

Tick amount that represents time.

tickFrequency long

The tick frequency that was used when measuring time. If it's set to 0, Frequency will be used instead.

Remarks

Depending on the length of measured time, the text will use minutes, seconds or milliseconds. For example: 001.331ms for under 1 second time span, 002.566s for under 1 minute and 013.457m for above 1 minute.

AppendTime(StringBuilder, TimeSpan)

Appends the provided time to the end of the string using a standardized format. See remarks for more details.

public static void AppendTime(StringBuilder builder, TimeSpan accumulatedTimeSpan)

Parameters

builder StringBuilder

The string builder to append time.

accumulatedTimeSpan TimeSpan

The amount of time to append.

Remarks

Depending on the length of measured time, the text will use minutes, seconds or milliseconds. For example: 001.331ms for under 1 second time span, 002.566s for under 1 minute and 013.457m for above 1 minute.

Begin(ProfilingKey)

Starts profiling with the provided 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 (var profile = Profiler.Begin(...)) {...} or using var profile = Profiler.Begin(...); in order to make sure that the Dispose() method will be called on the returned ProfilingState.

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

Starts profiling with the provided 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 optional value to pass with the Begin event (can be int, float, long or double).

value1 ProfilingCustomValue?

Second optional value to pass with the Begin event (can be int, float, long or double).

value2 ProfilingCustomValue?

Third optional value to pass with the Begin event (can be int, float, long or double).

value3 ProfilingCustomValue?

Fourth optional value to pass with the Begin event (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.Begin(...)) {...} or using var profile = Profiler.Begin(...); in order to make sure that the Dispose() method will be called on the returned ProfilingState.

Disable(ProfilingKey)

Disables the specified profile.

public static void Disable(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

Key of the profile to disable.

DisableAll()

Disables all profiles.

public static void DisableAll()

Enable(ProfilingKey)

Enables the specified profile.

public static void Enable(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

Key of the profile to enable.

EnableAll()

Enables all profiles.

public static void EnableAll()

IsEnabled(ProfilingKey)

Checks if the profile is enabled.

public static bool IsEnabled(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

The profile key.

Returns

bool

Returns true if the profile is enabled, otherwise false.

Remarks

This method not only checks if Stride.Core.Diagnostics.ProfilingKey.Enabled is set to true, but also if all profiles are globally enabled in the profiler.

New(ProfilingKey)

Creates a new profile state for the provided key, that can be used for code profiling. The created instance needs to be started and disposed manually. See remarks.

public static ProfilingState New(ProfilingKey profilingKey)

Parameters

profilingKey ProfilingKey

Key of the profile.

Returns

ProfilingState

A profile state that hasn't been started yet.

Examples

public static readonly ProfilingKey MyProfilingKey = new ProfilingKey("MyProfilingKey");

var state = Profiler.New(MyProfilingKey);
state.Begin();

// Execute performance heavy code here

// Make sure to stop profiling
state.End();

Remarks

The created instance needs to be started using Begin() and stopped using End() or Dispose().

It's recommended to instead use <code>using (var profile = Profiler.Begin(...)) {...}</code> or <code>using var
profile = Profiler.Begin(...);</code> to ensure that the profile state gets properly disposed.

ProcessEvent(ref ProfilingEvent, ProfilingEventType)

Processes a profiling event. This method is called by ProfilingState to relay data back to the profiler.

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

Parameters

profilingEvent ProfilingEvent

Information of the event.

eventType ProfilingEventType

The type of event.

Reset()

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

public static void Reset()

Subscribe()

Creates a reader and subscribes it to profiling events.

public static ChannelReader<ProfilingEvent> Subscribe()

Returns

ChannelReader<ProfilingEvent>

The ChannelReader<T> which will receive the events.

Unsubscribe(ChannelReader<ProfilingEvent>)

Unsubscribes a reader from receiving profiling events.

public static void Unsubscribe(ChannelReader<ProfilingEvent> eventReader)

Parameters

eventReader ChannelReader<ProfilingEvent>

The reader previously returned by Subscribe().