Class Profiler
- Namespace
- Stride.Core.Diagnostics
- Assembly
- Stride.Core.dll
High level CPU Profiler. For usage see remarks.
public static class Profiler
- Inheritance
-
objectProfiler
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
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
builderStringBuilderThe string builder to append time.
accumulatedTickslongTick amount that represents time.
tickFrequencylongThe 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
builderStringBuilderThe string builder to append time.
accumulatedTimeSpanTimeSpanThe 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
profilingKeyProfilingKeyThe 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
profilingKeyProfilingKeyThe profile key.
textFormatstringThe text to format.
value0ProfilingCustomValue?First optional value to pass with the Begin event (can be int, float, long or double).
value1ProfilingCustomValue?Second optional value to pass with the Begin event (can be int, float, long or double).
value2ProfilingCustomValue?Third optional value to pass with the Begin event (can be int, float, long or double).
value3ProfilingCustomValue?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
profilingKeyProfilingKeyKey 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
profilingKeyProfilingKeyKey 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
profilingKeyProfilingKeyThe 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
profilingKeyProfilingKeyKey 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
profilingEventProfilingEventInformation of the event.
eventTypeProfilingEventTypeThe 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
eventReaderChannelReader<ProfilingEvent>The reader previously returned by Subscribe().