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.

Automatic Metrics

The SDK can automatically collect performance metrics from the engine without any manual instrumentation. All automatic metrics are configured under Project Settings > Plugins > Sentry > Metrics > Experimental and require Enable Metrics to be checked.

All automatic metrics include the following attributes for filtering and grouping in Sentry dashboards:

These attributes make it possible to segment performance data by hardware tier, resolution, or game level.

Frame Time

When Collect frame time metrics is enabled, the SDK registers a performance consumer with Unreal Engine's built-in performance tracking system and emits the following metrics:

To avoid flooding the metrics pipeline, the SDK only emits metrics every Nth frame, controlled by the Frame time sample interval setting. The default value of 30 produces approximately 2 samples per second at 60 FPS, which is sufficient for accurate percentile computation while keeping overhead minimal.

SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
{
    Settings->EnableMetrics = true;
    Settings->EnableAutoFrameTimeMetrics = true;
    Settings->FrameTimeSampleInterval = 30; // Emit every 30th frame (default)
}));

GC Pauses

When Collect GC pause metrics is enabled, the SDK measures the blocking garbage collection pause and emits it as a metric after each collection cycle.

GC pauses are a common source of hitches in Unreal Engine games — a single GC pass can freeze the game thread for 10–50ms or more, causing visible stutters. The metric captures the interval between the GC lock being acquired and released. By default, the engine runs GC approximately every 60 seconds, so this metric has negligible impact on metric volume.

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

Game Stats

When Collect game stats metrics is enabled, the SDK periodically samples system-level statistics and emits them as gauge metrics. Unlike frame time metrics which are collected per-frame, game stats are sampled on a fixed time interval to avoid unnecessary overhead — these values change slowly and don't need per-frame resolution.

The Game stats sample interval setting controls how often game stats are collected. The default value of 60 seconds provides a good balance between visibility and overhead. Memory usage is read from FPlatformMemory::GetStats() and UObject count from the engine's global object array.

SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
{
    Settings->EnableMetrics = true;
    Settings->EnableAutoGameStatsMetrics = true;
    Settings->GameStatsSampleIntervalSeconds = 60; // Sample every 60 seconds (default)
}));

Network

When Collect network metrics is enabled, the SDK periodically polls Unreal Engine's network metrics database (UNetworkMetricsDatabase) and emits gauge metrics for the active network session. These metrics are only collected when a UNetDriver is present — that is, during multiplayer sessions (client connected to a server, or a server with connected clients). In singleplayer games without networking, no metrics are emitted.

The engine only populates the network metrics database when the net.EnableNetStats console variable is set to true. Add the following to your DefaultEngine.ini to enable it:

[SystemSettings]
net.EnableNetStats=1

Not all metrics are available in every context — client-specific metrics (ping, jitter) are only populated on clients, while server-specific metrics (num_clients, per-client stats, saturation) are only populated on servers. Listen servers report both sets.

The Network metrics sample interval setting controls how often network stats are polled. The default value of 10 seconds provides good visibility into network health without excessive overhead.

SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
{
    Settings->EnableMetrics = true;
    Settings->EnableAutoNetworkMetrics = true;
    Settings->NetworkMetricsSampleInterval = 10; // Poll every 10 seconds (default)
}));

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.