Profiler Class
Namespace: Stride.Core.DiagnosticsAssembly: Stride.Core.dll
High level CPU Profiler. For usage see remarks.
public static class 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
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 Stride.Core.Diagnostics.Profiler.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.
Name | Description | |
---|---|---|
Fields | ||
GpuTimestampFrequencyRatio | ||
Methods | ||
AppendTime(StringBuilder, Int64, Int64) | Append the provided time properly formated at the end of the string.
|
|
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. |
|
Begin(ProfilingKey, String, ProfilingCustomValue, Nullable<ProfilingCustomValue>, Nullable<ProfilingCustomValue>, Nullable<ProfilingCustomValue>) | Creates a profiler with the specified key. The returned object must be disposed at the end of the section being profiled. See remarks. |
|
Begin(ProfilingKey, String, Object[]) | Creates a profiler with the specified key. The returned object must be disposed at the end of the section being profiled. See remarks. |
|
Disable(ProfilingKey) | Disables the specified profiler. |
|
DisableAll() | Disable all profilers. |
|
Enable(ProfilingKey) | Enables the specified profiler. |
|
EnableAll() | Enables all profilers. |
|
GetEvents(ProfilingEventType, Boolean) | Retrieve the selected type of events and returns the number of elapsed frames. |
|
IsEnabled(ProfilingKey) | Enables the specified profiler. |
|
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. |
|
ProcessEvent(ref ProfilingEvent, ProfilingEventType) | ||
Reset() | Resets the id counter to zero and disable all registered profiles. |
Fields
GpuTimestampFrequencyRatio
public static double GpuTimestampFrequencyRatio
Field Value
Type | Description |
---|---|
System.Double |
Methods
AppendTime(StringBuilder, Int64, Int64)
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 System.Diagnostics.Stopwatch.Frequency is used to perform the calculation.
public static void AppendTime(StringBuilder builder, long accumulatedTicks, long tickFrequency = 0L)
Parameters
Type | Name | Description |
---|---|---|
System.Text.StringBuilder | builder | |
System.Int64 | accumulatedTicks | |
System.Int64 | tickFrequency |
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
Type | Name | Description |
---|---|---|
ProfilingKey | profilingKey | The profile key. |
System.String | text | The text to log with the profile. |
Returns
Type | Description |
---|---|
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, Nullable<ProfilingCustomValue>, Nullable<ProfilingCustomValue>, Nullable<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
Type | Name | Description |
---|---|---|
ProfilingKey | profilingKey | The profile key. |
System.String | textFormat | The text to format. |
ProfilingCustomValue | value0 | First value (can be int, float, long or double). |
System.Nullable<ProfilingCustomValue> | value1 | Second value (can be int, float, long or double). |
System.Nullable<ProfilingCustomValue> | value2 | Third value (can be int, float, long or double). |
System.Nullable<ProfilingCustomValue> | value3 | Fourth value (can be int, float, long or double). |
Returns
Type | Description |
---|---|
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, 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
Type | Name | Description |
---|---|---|
ProfilingKey | profilingKey | The profile key. |
System.String | textFormat | The text to format. |
System.Object[] | textFormatArguments | The text format arguments. |
Returns
Type | Description |
---|---|
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
Type | Name | Description |
---|---|---|
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
Type | Name | Description |
---|---|---|
ProfilingKey | profilingKey | The profile key. |
EnableAll()
Enables all profilers.
public static void EnableAll()
GetEvents(ProfilingEventType, Boolean)
Retrieve the selected type of events and returns the number of elapsed frames.
public static FastList<ProfilingEvent> GetEvents(ProfilingEventType eventType, bool clearOtherEventTypes = true)
Parameters
Type | Name | Description |
---|---|---|
ProfilingEventType | eventType | The type of events to retrieve |
System.Boolean | clearOtherEventTypes | if true, also clears the event types to avoid event over-accumulation. |
Returns
Type | Description |
---|---|
FastList<ProfilingEvent> | The profiling events. |
IsEnabled(ProfilingKey)
Enables the specified profiler.
public static bool IsEnabled(ProfilingKey profilingKey)
Parameters
Type | Name | Description |
---|---|---|
ProfilingKey | profilingKey | The profile key. |
Returns
Type | Description |
---|---|
System.Boolean |
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
Type | Name | Description |
---|---|---|
ProfilingKey | profilingKey | The profile key. |
Returns
Type | Description |
---|---|
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
Type | Name | Description |
---|---|---|
ProfilingEvent | profilingEvent | |
ProfilingEventType | eventType |
Reset()
Resets the id counter to zero and disable all registered profiles.
public static void Reset()