Profiler
SwiftlyS2's profiler service measures execution time in plugin code and records custom duration metrics.
Access it through Core.Profiler (APIISwiftlyCore.Profiler, type APIIContextedProfilerService).
Measuring Code Blocks
Pair APIIContextedProfilerService.StartRecording/APIIContextedProfilerService.StopRecording around the code, wrapped in try/finally so an exception doesn't leave a recording open.
Both take the recording name as a string, so pass the same name to StopRecording that you passed to StartRecording:
Core.Profiler.StartRecording("Database.PlayerStats.Load");
try
{
LoadPlayerStats();
}
finally
{
Core.Profiler.StopRecording("Database.PlayerStats.Load");
}Neither method returns anything - StartRecording gives you no scope, handle or token, so the name is the only thing tying a start call to its stop call.
Recording Precomputed Durations
Use APIIContextedProfilerService.RecordTime for a duration you already measured - the second parameter is a double:
var stopwatch = System.Diagnostics.Stopwatch.StartNew();
BuildLargeMenu();
stopwatch.Stop();
double durationUs = stopwatch.ElapsedTicks * (1_000_000.0 / System.Diagnostics.Stopwatch.Frequency);
Core.Profiler.RecordTime("Menu.Build", durationUs);The interface doesn't state a unit for duration, and the example above
records microseconds. Pick one unit and use it consistently so profiler
entries stay comparable across the codebase.
Profiling Sub-Operations
Nest start/stop pairs to profile major flow steps separately and find hot spots faster. Give each nested recording its own name, since there is no scope object that would separate two recordings sharing one:
Core.Profiler.StartRecording("PlayerData.Process");
try
{
Core.Profiler.StartRecording("PlayerData.Load");
try { LoadPlayerData(player.SteamID); } finally { Core.Profiler.StopRecording("PlayerData.Load"); }
Core.Profiler.StartRecording("PlayerData.Apply");
try { ApplyPlayerData(player); } finally { Core.Profiler.StopRecording("PlayerData.Apply"); }
}
finally { Core.Profiler.StopRecording("PlayerData.Process"); }Naming Strategy
Use clear, hierarchical names so related entries group together:
category.operation.detailExamples: Database.Players.Load, Database.Players.Save, Menu.Main.Build, Menu.Main.Open, Commands.Teleport.Execute, Events.PlayerSpawn.Process.
Avoid generic names like Operation or Process - they make hot spots hard to trace back to real code.
Reading Results
The service only writes. APIIContextedProfilerService has no member that returns a recording, a duration, a snapshot of the collected metrics or any current state - all three members return void - so a plugin can't read back what it recorded through this API. Recording names are therefore write-only keys: keep them in a consistent naming scheme and consume the results outside the plugin API.
Members
APIIContextedProfilerService members, in the SwiftlyS2.Shared.Profiler namespace:
| Member | Signature | Description |
|---|---|---|
| APIIContextedProfilerService.StartRecording | void StartRecording(string name) | Starts a recording under name |
| APIIContextedProfilerService.StopRecording | void StopRecording(string name) | Stops the recording started under name |
| APIIContextedProfilerService.RecordTime | void RecordTime(string name, double duration) | Records duration for name without a start/stop pair |
services.AddSwiftly(Core) registers Core.Profiler as a singleton, so
IContextedProfilerService can be constructor-injected - see Dependency
Injection.
Reference
See APIISwiftlyCore for the full service list, and Swiftly Core for the other core services.