Articles in this section

Unity: Stability Metrics Configuration

  • Updated

As of backtrace-unity version 3.6.0, the SDK will by default capture events used to calculate 2 stability metrics, Crash Free Users and Crash Free Application Launches. By default, these stability metrics can be grouped and filtered by the attributes application.version and uname.sysname.

This document will teach you how to further configure your Unity SDK so you get more value out of  the custom details you wish to track for your project’s stability metrics. This includes:

  • Attribute Configuration: Ensure your stability metrics respond to additional attribute filters / queries in the Web Console
  • Custom Metric Groups: Track more than just crash free users and crash free application launches - Create custom metric groups to track stability by the metrics that matter to your game. A common example is crashes per minutes played. 
  • Metric Event Control: An advanced control to adjust the frequency of metric events for more granular data

Note: For a high level overview of stability metrics, see here.

Attribute Configuration

For stability metrics to respond to queries / filters in the Web Console, users must...

  1. Ensure the SDK sends relevant attributes on events for the metric group in question
  2. Create the metric group and associate relevant attributes in the Web Console’s “Stability Monitoring” project setting

By default, the Unity SDK sends events which make up the "Application Launches" metric group.  This metric group is used to calculate Crash free sessions and Crash free users in the Overview dashboard.  For the purposes of this document, I will be referring to this metric group as an example throughout this configuration process.

SDK Event Attributes

Stability metrics like Crash free users / sessions are calculated using events sent from the Unity SDK.  In order for stability metrics to respond to queries / filters in the Web Console (for example, the widgets on the Overview page), the attribute you want to use to filter must be included on the events that the SDK sends.  See below for a list of attributes sent on events from the Unity SDK by default.

To add new attributes to be sent for a given metric group’s event, use the AddSummedEvent method (IBacktraceMetrics).

For example, this code adds an event to the “levels_played” metric group, linking the attributes “application.version” and “score” to the events.  So any metrics calculated using the levels played metric group would respond to queries involving application.version and/or score attributes!

BacktraceClient.Instance.Metrics.AddSummedEvent("levels_played", new Dictionary<string, string>() {
  {"application.version", BacktraceClient.Instance["application.version"]},
  {"score", "" + score}
 }
);

Default Event Attributes - Unity SDK

Metric Group:  Application Launches Attributes

All of these attributes are sent as a part of the Application Launch metric group.  By default, this event is sent on startup, on game end, and every 30 mins.  Because of this relative infrequency, there are a lot of attributes sent by default.  If you ramp up the frequency of these events, it may be worth reducing the amount of data sent on each event.

Guid
Graphic.id
graphic.nameM
Graphic.type
Graphic.vendor
Graphic.vendor.id
Graphic.driver.version
Graphic.memory
Graphic.multithreaded
Graphic.shader
graphic.topUv
Uname.sysname
Uname.version
Uname.fullname
Uname.family
Cpu.count
Cpu.frequency
Cpu.brand
Audio.supported
Cpu.boottime
Hostname
Vm.rss.size
Backtrace.version
Api.compatibility
Scripting.backend
Application
Application.version
Application.url
Application.company.name
Application.data_path
Application.id
Application.installer.name
Application.internet_reachability
Application.editor
Application.focused
Application.mobile
Application.playing
application.background
application.sandboxType
application.system.language
application.unity.version
application.session

Web Console Metric Group / Attribute Linking

See this documentation for how to set up a metric group and link attributes to it in the Web Console.  

NOTE! When you create a new project or submission token, it may take 15 minutes for your new submission token to be recognized. When the token isn't recognized, the events will be rejected which will show up in your Unity log. Once your token is recognized, the messages sent automatically by the SDK will trigger the auto creation of the metric groups. This may take up to 30 minutes and while this is being provisioned, no metrics will be captured yet!

By default, the "Application Launches" metric group is auto-created when Crash Free Metrics are enabled in your game. It links uname.sysname and application.version. Because the Unity SDK will by default send all of the attributes above, you can try linking one (or more) of the attributes from the list above to try this out! 

 

Creating New Metric Groups Via Unity SDK

This section covers how to configure your Unity game to send custom metric groups via our SDK’s public APIs.  For information on how to upload metric groups from external data sources, see the Importing Metrics documentation. 

"Minutes Played" Configuration

For the sake of walking through an example to help illustrate the setup process, let’s assume that you want to analyze your crashes / errors against how many minutes a user has played your game.  

This would allow you to use Backtrace to calculate metrics like…

  • How many minutes on average are the users of my game able to play without a crash?
  • How long does the average user play my game?
  • What is the average session length of my game?
    • ... by platform?
    • … by release version? 

Step 1: To set this up, first you need to add the new metric group to your Backtrace Project via the Web Console >> Project Settings >> Stability Monitoring.

AttributeLinking.PNG

In the above example, you can see I created a new metric group called “MinutesPlayed” and linked application.version and uname.sysname attributes to it.  

Note: the Metrics section under Attributes. should never be filled out for Unity. This only applies if external metrics are being imported.

Step 2: Configure the Unity SDK to send this metric group and the desired attributes.

Next, use the AddSummedEvent method to add events for the new metric group.  In this example, I want to add an event every minute because we are tracking “MinutesPlayed”!

private void Update()
{
    timeElapsedSeconds += Time.deltaTime;

    // Every second, add an event for this metric group
    if (timeElapsedSeconds >= 60)
    {
      timeElapsedSeconds = 0;

      // Generate your attribute values for the attributes you want linked
      Dictionary<string,string> attributes = new Dictionary<string, string>()
      {
        { "application.version", BacktraceClient.Instance["application.version"] },
        { "uname.sysname", BacktraceClient.Instance["uname.sysname"] },
        { "custom.field", "custom.value" },
      };

      // Add the summed event using the metric group name and attributes
      BacktraceClient.Instance.Metrics.AddSummedEvent("MinutesPlayed", attributes);
    }
}

Metric Event Control

Note that the above example will add an event for this metric group to a queue which will be sent out automatically based on the interval you have set on your BacktraceConfiguration scriptable object (default every 30 mins).  

You can adjust the frequency of that send process to suit your needs and/or manually send the events by calling BacktraceClient.Instance.Metrics.Send().

Try to avoid adding too many events with many linked attributes or sending too frequently as this can affect the performance of your game and contribute a lot of data towards your Backtrace data storage limits.

 

Related articles