Official Profiler Extensibility

Welcome to the Profiler Extensibility discussion thread. You can use this thread to ask for help, share feedback, and have discussions about the Profiler Extensibility feature.

Introduction
Profiler Extensibility refers to the ability for developers to extend the Unity Profiler with custom data and visualisation in order to better measure, monitor, and convey the performance characteristics of their applications and systems.

In Unity 2021.2 we are releasing two new features to aid developers in this goal, Profiler counters and custom Profiler modules.

Profiler Counters
Profiler counters allow you to track the key metrics of your application and make them visible in the Unity Profiler or in other code. This is particularly useful if you want to track performance changes in your application, and it speeds up the investigation of performance issues because you can use the information from your Profiler counters in conjunction with Unity’s built-in counters and instrumentation data.

If you are an Asset Store package developer, you can add Profiler counters to your code to help other developers understand important performance characteristics of your system, and they can use this information for optimization or budgeting tooling.

Profiler counters can be monitored in release (non-development) builds without the Unity Profiler attached via the Profiler Recorder API. This enables you to selectively track metrics in release builds and capture runtime performance characteristics closer to real-world usage.

Profiler Counters are available in the Unity Profiling Core package, which is currently in the Release Candidate phase of its development cycle and on track to be Released for Unity 2021.2.



Custom Profiler Modules
In Unity 2021.2, the Profiler Window can now be extended with custom Profiler Modules in order to visualise your own metrics alongside other Profiler data. In combination with Profiler Counters, this enables you to visualise the performance story of your own systems directly in the Profiler window.

Custom Profiler modules can be defined from both a Unity project, as well as from a Unity package. This enables package authors, such as Asset Store developers, to ship custom Profiler modules in their package to convey relevant performance metrics to their users.

Custom Profiler modules also support rendering a custom UI in the module’s Details View, which is displayed below the list of charts when the module is selected. This is useful for showing additional details relevant to your module or presenting a bespoke visualization of your performance data to the user. The example below demonstrates adding more context to some performance data, in this case by visualising how several counters contribute to a total budget.



Resources
For more information, please see the following resources:

• Extensibility Manual Documentation
• Unity Profiling Core Package
• Profiler Counters API Guide
• Custom Profiler Module API Documentation
• Capturing profiler stats at runtime | Unite Now 2020

Feedback
Please feel free to post any feedback in this thread.

How to report bugs
Please report bugs through Unity’s built-in bug reporter tool, located in “Help > Report a Bug…”. Once you have submitted a bug report through the bug reporter, please feel free to start a discussion about it in this thread or by posting a new thread in this forum using the profiling tag.

Thank you for your interest, we're looking forward to your feedback!

 

Glad you like it

The later is correct, i.e. the extensibility of the Editor UI is available as of 2021.2, the packaged and with that the Profiler Counters are compatible with 2020.3 and their output to the profiler data stream can there only be used via the Profiler Module Editor, but not with this new extensibility API.

 

@codestage Thanks for the feedback. Yep you're exactly right; there is currently no easy, performant way for the Profiler to learn of counters before they've been emitted to the data stream.

Advanced FPS counter is looking awesome . So is this update adding the ability to add any available Profiler Counters for display? I couldn't see this functionality in the existing tool on the Asset Store but might have missed it. Very cool!

 

Firstly, ProfilerMarker itself isn't that new, although much newer than those ancient Unity APIs that go back to at least Unity 3.0 . ProfilerMarker has been available since Unity 2018 I believe.

The Profiling.Core package adds the ProfilerMarker<T> generic variants for providing integer/floating point/string metadata. And this is available since Unity 2020 and verified in Unity 2021.

So what's the difference with the static API?

1. You can query markers at runtime (in development builds) if you use ProfilerMarker with the ProfilerRecorder API. You can't do this with the static functions.
   
2. With ProfilerMarker, we don't need to do a string copy of the sample name every time the marker is begun because the API is ensuring, by design, that its name does not change. Conversely, as BeginSample makes no such guarantee, we need to do an extra string copy each time. (This used to create the sample/marker every time but was optimised at some point to reduce it to one string copy.)
   
3. Profiler.Begin API makes it very easy to be dynamically creating strings every time you call it. For example, BeginSample($"MyMarker {value}"), would be allocating every time the marker is reached. Experienced developers will know not to do this, but it's nice to try to encourage the user into best practices through the API's design. The ProfilerMarker API does a better job of this in the common case, in my opinion.
4. If you install the Profiling.Core package, you can also supply metadata to your Profiler markers via their generic variants, ProfilerMarker<T>, which is also displayed in the Profiler's Timeline and Hierarchy views inside the marker.

You can use the Profiler.EmitFrameMetaData and FrameDataView.GetFrameMetaData APIs to send additional per-frame data to the Profiler.

Yes you can read it from the frame data.