Profiler Extensibility

Unity Engine
, ,
1

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.

7199914--864502--Tanks - Runtime Stats.jpg
7199914--864502--Tanks - Runtime Stats.jpg1443Ă—786 197 KB

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.

7199914--864505--Tank Effects Profiler Module (Detailed).png
7199914--864505--Tank Effects Profiler Module (Detailed).png804Ă—538 63.9 KB

Resources
For more information, please see the following resources:

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!

12 Likes
2

Awesome feature set!

I’m super happy about it both as developer and Asset Store publisher, going to use some of this black magic at Advanced FPS Counter and probably other my assets.

Thank you for this opportunity ^^

P.S. will get back with a feedback on how it goes for me when I’ll reach that point!

3 Likes
3

Very cool looking feature!

One question, though. You say that it’s only available for Unity 2021.2, but the Profiling Core documentation (at the time I’m writing this) says that 2020.1 are supported. Has this feature been backported to 2020, or is it just that the package is compatible with 2020, but the Extensibility is only available in 2021.2+?

1 Like
4

Glad you like it :slight_smile:

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.

5

Exactly what I was looking for to assign some stats to the editor. You can use this to assign definite numbers to profiler frames, instead of going off the method call count.

6

Hey @AndyBarnard ,

Just to leave some feedback on the new extensibility features: I’ve checked custom Profiler Counters (and Markers) from the Profiling Core package and it did work perfectly fine for me!

One thing I found a bit of annoying is the requirement to enter Play Mode and trigger newly added counters and markers to appear in the Profiler Module Editor (and in the ProfilerRecorderHandle.GetAvailable()), but I’m pretty sure it can’t be avoided, so, it’s not that scary trade off to access those counters, we can live with this =)

P.S. tried it with my ongoing AFPSCounter update, and it worked well too (here are two custom counters and one marker on the screenshot)

2 Likes
7

@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!

1 Like
8

@AndyBarnard thank you for the kind words!

Yes! It allows adding any Markers or Counters from what the ProfilerRecorderHandle.GetAvailable returns and rendering them at runtime with easy appearance setup.

This is going to be released with upcoming update and I have more plans for the future versions, like make it easier to share different Profiler Counters presets between projects, integrate with Profiler Modules in order to create Profiler Counters from the Modules and vice versa and other stuff ^^

1 Like
9

https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/manual/profilermarker-guide.html

Whats the difference between this new ProfilerMarker and good old Profiler.Begin/End sample?

10

How would i be able to communicate more complex data in between the editor and player? The current counters allow me to send ints and doubles, but i’d like to show a hierarchy/treeview like the CPU profiler does.

ProfilerUtility.GetProfilerMarkerDataType hints towards support for strings, but i cant make a Counter of that type.

Would it be possible to read out a ProfilerMarker in a custom view?
*Edit: That is possible, so you make a marker, record some string data and read it out like this:

            using (var frameData = ProfilerDriver.GetRawFrameDataView((int)selectedFrameIndex, 0))
            {
                List<FrameDataView.MarkerInfo> markerInfoList = new List<FrameDataView.MarkerInfo>();
                frameData.GetMarkers(markerInfoList);
                var id = frameData.GetMarkerId(MARKER-NAME);

                for (int i = 0; i < frameData.sampleCount; i++)
                {
                    if (id != frameData.GetSampleMarkerId(i)) continue;
                    Debug.Log(frameData.GetSampleMetadataAsString(i, 0));
                }
            }
11

Is it possible to change the behaviour that when you click in the graphs the game pauses?

12

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

The Profiling.Core package adds the ProfilerMarker 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?

  • 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.

  • 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.)

  • 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.

  • If you install the Profiling.Core package, you can also supply metadata to your Profiler markers via their generic variants, ProfilerMarker, 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.

1 Like
13

Then it must be me who’s old! Thanks for the extra explanations. Hope you dont mind i keep adding a few things im noticing here.

EmitFrameMetaData sounds much better than the hacky workaround i was doing. However it would be very convenient if i could pass in an array length, from what i can see the API should be able to support this? For now i might try using a NativeArray as a workaround, so i can still re-use the same buffer.

I’m making a network profiler, and pausing the editor causes a disconnect. Is there any way i can not pause the editor when scrubbing through the graph, in my custom view?