Adding profiler counters to your code

To add a profilerA window that helps you to optimize your game. It shows how much time is spent in the various areas of your game. For example, it can report the percentage of time spent rendering, animating, or in your game logic. More info
See in Glossary counter, create scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary to do the following:

Create and define a new counter.
Update the counter’s value.

The code examples in these sections add a Profiler counterPlaced in code with the ProfilerCounter API to track metrics, such as the number of enemies spawned in your game. More info
See in Glossary to track the total number of particles that Unity created for every instance of a GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary’s trail effects. In these examples, the GameObject’s name is “Tank”.

Prerequisites

Some examples use the Profiling Core package, which you must install before you start. The Unity Profiling Core package isn’t discoverable in the Package Manager UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary because it’s a core package. To install the package do either of the following:

Add it by its name, which is com.unity.profiling.core.
Install it via this link.

Creating and defining a counter

To create a new counter:

Write a script that defines the value type of the new counter.
Assign a name and a unit to this type.

Important: When you create a counter you must specify which Profiler categoryIdentifies the workload data for a Unity subsystem (for example, Rendering, Scripting and Animation categories). Unity applies color-coding to categories to visually distinguish between the types of data in the Profiler window.
See in Glossary your new counter belongs to. To do this, use an existing Unity category from the ProfilerCategory class. The script in the following example uses the existing ProfilerCategory.Scripts category.

The Profiler counters API supports push and pull operations. You can push the value of the counter to the Profiler, or the Profiler can pull the value at the end of the frame.

If your data changes infrequently, for example once per frame, use the ProfilerCounter API to push the counter data to the Profiler. If your data changes multiple times per frame, use the ProfilerCounterValue API. This makes the Profiler automatically pick up the last value at the end of the frame.

The following example script defines the ProfilerCounterValue TankTrailParticleCount, with the name “Tank Trail Particles” and a unit of ProfilerMarkerDataUnit.Count:

public static class GameStats
{
   public static readonly ProfilerCategory TanksCategory = ProfilerCategory.Scripts;

   public const string TankTrailParticleCountName = "Tank Trail Particles";
   public static readonly ProfilerCounterValue<int> TankTrailParticleCount =
       new ProfilerCounterValue<int>(TanksCategory, TankTrailParticleCountName, ProfilerMarkerDataUnit.Count,
           ProfilerCounterOptions.FlushOnEndOfFrame | ProfilerCounterOptions.ResetToZeroOnFlush);
}

The options FlushOnEndOfFrame and ResetToZeroOnFlush automatically send the counter to the Profiler data stream and reset the Count value to zero at the end of the frame.

Updating a counter’s value

To update the value of a counter, create a MonoBehaviour script that sets the value of a counter you have defined.

The following MonoBehaviour script counts the number of trail particles that belong to an assigned GameObject every frame in the Update function. To do this, it uses the counter called TankTrailParticleCount.

The following example script also creates a public property called Trail Particle SystemA component that simulates fluid entities such as liquids, clouds and flames by generating and animating large numbers of small 2D images in the scene. More info
See in Glossary (m_TrailParticleSystem) in the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary:

 using UnityEngine;

 class TankMovement : MonoBehaviour
 {
    public ParticleSystem m_TrailParticleSystem;

    void Update()
    {
        GameStats.TankTrailParticleCount.Value += m_TrailParticleSystem.particleCount;
    }
 }

Adding Profiler counters to a custom Profiler module

To display a Profiler counter in a custom Profiler module via code, you must create a new ProfilerModule script and define the module’s properties including the counters it displays, its name, and its icon. For information on how to do this refer to Creating Profiler modules in code.

Additional resources

Adding profiler markers to your code

Visualizing profiler counters