Probes¶

Introduction¶

A probe is a simple construct that allows you to extract data from your game and give it to .Profile. A single .Profile session can having multiple probes into your application. This allows you as a developer a way to keep your game code an your .Profile code separated from one another, imposing a semi strict seperation of concerns.

.Profile ships with a whole bunch of Default Probes that allow you to instantly probe most functionality that Unity provides. These Probes are available out of the box and can be used.

All Probes used by .Profile fall into one of two categories

Continuous probes

These probes continually probe your application at a specified interval, these probes can be useful for data that changes over time, such as framerate or memory usage
One shot probes

One shot probes will probe your app once and once only, these probes can be useful for data that won’t change at runtime, such as hardware stats.

Provided Probes¶

.Profiles Default Probes are split fairly evenly between continuous and one shot probes. Out of the box, .Profile provides probes for the following data.

Name	Probe Type	Tracks
Defaults.Continuous	Continuous	CPU load and framerate
Defaults.ContinuousMemory	Continuous	Memory usage across many systems
Defaults.ContinuousObjectMemory	Continuous	Memory in use by various GameObjects
Defaults.Graphics	One Shot	The current graphics settings
Defaults.GraphicsParticles	One Shot	The current graphics settings for particles
Defaults.GraphicsShadow	One Shot	The current graphics settings for shadows
Defaults.GraphicsTexture	One Shot	The current graphics settings for textures
Defaults.Hardware	One Shot	The current hardware settings
Defaults.Time	One Shot	The current time settings

To use one of these Default Probes, simply

Add the required using

using WellFired.Profile.ProfileProcessor;

Tell your session to track the data you require.

// Track Continuous memory usage
session.Track(Defaults.ContinuousMemory);

Custom Probes¶

.Profile provides a simple API for users who want to provide custom probes, allowing users to track any custom data in their application.

Building custom probes is as simple as implementing the IProbe interface.

consider the following simple custom probe that doesn’t do anything other than return the float 60.

public class CustomProbe : IProbe
{
    /// <summary>
    /// Return a value
    /// </summary>
    /// <returns>Always returns 60</returns>
    public object Probe()
    {
        return 60.0f;
    }
}

The IProbe interface requires you implement the Probe method. From this method you are required to return your custom tracked data, this can be anything you want it to be, it doesn’t even have to be performance related (maybe a custom in-game currency spent over time).

Further to this simple example, you can also implement the IFormattedName interface, this gives you a method for naming your probe, but is entirely optional.

consider the following extensions:

public class CustomProbe : IProbe, IFormattedName
{
    /// <summary>
    /// Return a value
    /// </summary>
    /// <returns>Always returns 60</returns>
    public object Probe()
    {
        return 60.0f;
    }

    /// <summary>
    /// The IFormattedName is optional
    /// </summary>
    public string Name { get { return "Custom Probe"; } }
}

Now that you have your custom probe, the last step is to tell your .Profile session to track it.

session.Track(new CustomProbe(), RecordMode.Continous, 100);

When Tracking a custom probe, you are required to tell your session if it should be probed continuously or only once and at what interval. This corresponds to the second and third parameter respectively.

A single session can have any number of probes.

Next up¶

Now we’ve covered tracking data using built in probes and writing custom probes to track custom application logic and data, we’ll cover reporting that data.