Set Up Metrics

With Sentry Metrics, you can send counters, gauges, and distributions from your Unity game to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.

Requirements

Metrics for Unity are supported in Sentry SDK version 4.1.0 and above.

Setup

To enable metrics in your Unity game, you need to configure the Sentry SDK with metrics enabled.

Project Settings Configuration

1. Inside the editor open: Tools > Sentry > Advanced
2. Under the Metrics section, check the Enable Metrics option

Programmatic Configuration

Alternatively, you can enable metrics programmatically through the configure callback:

public override void Configure(SentryUnityOptions options)
{
    options.Experimental.EnableMetrics = true;
}

or if you're manually initializing the SDK:

SentrySdk.Init(options =>
{
    options.Dsn = "___PUBLIC_DSN___";

    // Enable metrics to be sent to Sentry
    options.Experimental.EnableMetrics = true;
});

Usage

Metrics are enabled by default. Once you initialize the SDK, you can send metrics using the SentrySdk.Experimental.Metrics APIs.

The SentryMetricEmitter type exposes three method groups that you can use to capture different types of metric information: Counter, Gauge, and Distribution.

All methods are generic, where the provided type argument defines the numeric value type that the metric is emitted with. The supported numeric types are byte, short, int, long, float, and double.

Emit a Counter

Counters are one of the more basic types of metrics and can be used to count certain event occurrences.

To emit a counter, do the following:

// Record five total player interactions
SentrySdk.Experimental.Metrics.EmitCounter("player_interaction", 5,
    new[] { new KeyValuePair<string, object>("scene", "MainMenu"), new KeyValuePair<string, object>("app_version", "1.0.0") });

Emit a Distribution

Distributions help you get the most insights from your data by allowing you to obtain aggregations such as p90, min, max, and avg.

To emit a distribution, do the following:

// Add '15.0' to a distribution used for tracking the loading times per scene.
SentrySdk.Experimental.Metrics.EmitDistribution("scene_load", 15.0, MeasurementUnit.Duration.Millisecond,
    new[] { new KeyValuePair<string, object>("scene", "Level1") });

Emit a Gauge

Gauges let you obtain aggregates like min, max, avg, sum, and count. They can be represented in a more space-efficient way than distributions, but they can't be used to get percentiles. If percentiles aren't important to you, we recommend using gauges.

To emit a gauge, do the following:

// Add '15.0' to a gauge used for tracking the loading times for a scene.
SentrySdk.Experimental.Metrics.EmitGauge("scene_load", 15.0, MeasurementUnit.Duration.Millisecond,
    new[] { new KeyValuePair<string, object>("scene", "Level1") });

Options

EnableMetrics

Set to false in order to disable the SentrySdk.Experimental.Metrics APIs.

SetBeforeSendMetric

To filter metrics, or update them before they are sent to Sentry, you can use the SetBeforeSendMetric(Func<SentryMetric, SentryMetric?>) option. If the callback returns null, the metric is not emitted. Attributes can also be updated in the callback delegate.

public override void Configure(SentryUnityOptions options)
{
    options.Experimental.SetBeforeSendMetric(static metric =>
    {
        if (metric.Name == "removed-metric")
        {
            return null;
        }

        metric.SetAttribute("extra", "foo");

        return metric;
    });
}

or if you're manually initializing the SDK:

SentrySdk.Init(options =>
{
    options.Dsn = "___PUBLIC_DSN___";
    options.Experimental.SetBeforeSendMetric(static metric =>
    {
        if (metric.Name == "removed-metric")
        {
            return null;
        }

        metric.SetAttribute("extra", "foo");

        return metric;
    });
});

The beforeSendMetric delegate receives a metric object, and should return the metric object if you want it to be sent to Sentry, or null if you want to discard it.

The metric object of type SentryMetric has the following members:

The numeric value of SentryMetric has the same numeric type that the metric was emitted with. The supported numeric types are byte, short, int, long, float, and double.

Default Attributes

The Sentry SDK for Unity automatically sets several default attributes on all metrics to provide context and improve debugging:

Core Attributes

• environment: The environment set in the SDK if defined. This is sent from the SDK as sentry.environment.
• release: The release set in the SDK if defined. This is sent from the SDK as sentry.release.
• sdk.name: The name of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.name.
• sdk.version: The version of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.version.

Server Attributes

• server.address: The address of the server that sent the metric. Equivalent to server_name that gets attached to Sentry errors.

User Attributes

If user information is available in the current scope, the following attributes are added to the metric:

• user.id: The user ID.
• user.name: The username.
• user.email: The email address.