Set Up Metrics

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

Requirements

Metrics for Unreal Engine are supported in Sentry Unreal Engine SDK version 1.7.0 and above.

Setup

To enable metrics in your Unreal Engine project, you need to configure the Sentry SDK with metrics enabled.

Project Settings Configuration

1. Open your project settings: Project Settings > Plugins > Sentry
2. Check the Enable Metrics option

Programmatic Configuration

Alternatively, you can enable metrics programmatically when initializing the SDK:

#include "SentrySubsystem.h"

void ConfigureSentryWithMetrics()
{
    USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

    SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
    {
        Settings->EnableMetrics = true;
    }));
}

Usage

Once metrics are enabled, you can emit metrics using the Sentry subsystem.

Metric Types

Counters

Track the number of times something happens:

#include "SentrySubsystem.h"

USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

SentrySubsystem->AddCount(TEXT("api.requests"), 1);

Gauges

Track current values that can go up or down:

SentrySubsystem->AddGauge(TEXT("active_connections"), 42, USentryUnitHelper::MakeSentryUnit(ESentryUnit::None));

Distributions

Track a range of values (e.g., response times):

SentrySubsystem->AddDistribution(TEXT("response.time"), 150.5f, USentryUnitHelper::MakeSentryUnit(ESentryUnit::Millisecond));

Custom Attributes

Add attributes to filter and group metrics in Sentry:

TMap<FString, FSentryVariant> Attributes;
Attributes.Add(TEXT("endpoint"), FSentryVariant(TEXT("/api/orders")));
Attributes.Add(TEXT("region"), FSentryVariant(TEXT("us-west")));

SentrySubsystem->AddCountWithAttributes(TEXT("api.calls"), 1, Attributes);

All metric methods have a WithAttributes variant:

• AddCountWithAttributes()
• AddDistributionWithAttributes()
• AddGaugeWithAttributes()

Units

For gauge and distribution metrics, specify a unit to help Sentry display values in a human-readable format. The SDK provides the ESentryUnit enum with predefined units for duration, information, and fraction categories:

// Using predefined units
SentrySubsystem->AddGauge(TEXT("memory.usage"), 1024.0f, USentryUnitHelper::MakeSentryUnit(ESentryUnit::Byte));
SentrySubsystem->AddDistribution(TEXT("latency"), 42.5f, USentryUnitHelper::MakeSentryUnit(ESentryUnit::Millisecond));

// Using a custom unit
SentrySubsystem->AddDistribution(TEXT("frame.rate"), 60.0f, USentryUnitHelper::MakeSentryCustomUnit(TEXT("fps")));

Blueprint Support

You can also emit metrics from Blueprints by calling the Add Count, Add Distribution, or Add Gauge nodes on the Sentry subsystem. Use the Make Sentry Unit node to specify measurement units.

Options

The following configuration options are available for Sentry Metrics in Unreal Engine:

Before-Metric Handler

To filter metrics or modify them before they are sent to Sentry, create a custom before-metric handler class:

UCLASS()
class UCustomMetricFilter : public USentryBeforeMetricHandler
{
    GENERATED_BODY()
public:
    virtual USentryMetric* HandleBeforeMetric_Implementation(USentryMetric* Metric) override
    {
        // Drop metrics with specific names
        if (Metric->GetName().Contains(TEXT("debug")))
        {
            return nullptr; // Return null to prevent sending
        }

        // Modify metric attributes
        Metric->SetAttribute(TEXT("build"), FSentryVariant(TEXT("production")));

        return Metric; // Return the metric to send it
    }
};

Configure the handler in project settings under Hooks > Custom beforeMetric event handler, or set it programmatically:

SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
{
    Settings->EnableMetrics = true;
    Settings->BeforeMetricHandler = UCustomMetricFilter::StaticClass();
}));

Default Attributes

The Unreal Engine SDK automatically attaches the following attributes to every metric:

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.

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.