---
title: "Metrics"
description: "Metrics allow you to send, view and query counters, gauges and distributions from your Unreal Engine game to track application health and drill down into related traces, logs, and errors."
url: https://docs.sentry.io/platforms/unreal/metrics/
---

# Set Up Metrics | Sentry for Unreal Engine

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.

This feature is currently in open beta. Features in beta are still in progress and may have bugs.

## [Requirements](https://docs.sentry.io/platforms/unreal/metrics.md#requirements)

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

## [Setup](https://docs.sentry.io/platforms/unreal/metrics.md#setup)

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

### [Project Settings Configuration](https://docs.sentry.io/platforms/unreal/metrics.md#project-settings-configuration)

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

### [Programmatic Configuration](https://docs.sentry.io/platforms/unreal/metrics.md#programmatic-configuration)

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

```cpp
#include "SentrySubsystem.h"

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

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

## [Usage](https://docs.sentry.io/platforms/unreal/metrics.md#usage)

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

### [Metric Types](https://docs.sentry.io/platforms/unreal/metrics.md#metric-types)

| Type           | Use For                                      |
| -------------- | -------------------------------------------- |
| `Counter`      | Events (orders, clicks, API calls)           |
| `Gauge`        | Current values (queue depth, connections)    |
| `Distribution` | Value ranges (response times, payload sizes) |

### [Counters](https://docs.sentry.io/platforms/unreal/metrics.md#counters)

Track the number of times something happens:

```cpp
#include "SentrySubsystem.h"

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

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

### [Gauges](https://docs.sentry.io/platforms/unreal/metrics.md#gauges)

Track current values that can go up or down:

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

### [Distributions](https://docs.sentry.io/platforms/unreal/metrics.md#distributions)

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

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

### [Custom Attributes](https://docs.sentry.io/platforms/unreal/metrics.md#custom-attributes)

Add attributes to filter and group metrics in Sentry:

```cpp
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](https://docs.sentry.io/platforms/unreal/metrics.md#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:

```cpp
// 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](https://docs.sentry.io/platforms/unreal/metrics.md#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](https://docs.sentry.io/platforms/unreal/metrics.md#automatic-metrics)

Automatic metrics are experimental and may change in future releases.

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:

| Attribute        | Description                  |
| ---------------- | ---------------------------- |
| `gpu.name`       | GPU model name               |
| `cpu.cores`      | Number of physical CPU cores |
| `ram.gb`         | Total physical RAM in GB     |
| `res.x`, `res.y` | Screen resolution            |
| `map`            | Current game map/level name  |

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

### [Frame Time](https://docs.sentry.io/platforms/unreal/metrics.md#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:

| Metric                    | Type              | Description                 |
| ------------------------- | ----------------- | --------------------------- |
| `game.perf.frame_time`    | Distribution (ms) | Total frame time            |
| `game.perf.game_thread`   | Distribution (ms) | Game thread work time       |
| `game.perf.render_thread` | Distribution (ms) | Render thread work time     |
| `game.perf.gpu`           | Distribution (ms) | GPU frame time              |
| `game.perf.fps`           | Gauge             | Engine-smoothed average FPS |

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.

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

### [GC Pauses](https://docs.sentry.io/platforms/unreal/metrics.md#gc-pauses)

GC pause metrics require Unreal Engine 5.5 or later. On older engine versions, this setting has no effect.

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.

| Metric              | Type              | Description                       |
| ------------------- | ----------------- | --------------------------------- |
| `game.perf.gc_time` | Distribution (ms) | Duration of the blocking GC pause |

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.

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

### [Game Stats](https://docs.sentry.io/platforms/unreal/metrics.md#game-stats)

Tracking of active UObjects number requires Unreal Engine 5.3 or later.

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.

| Metric                    | Type          | Description                         |
| ------------------------- | ------------- | ----------------------------------- |
| `game.perf.used_memory`   | Gauge (bytes) | Physical memory used by the process |
| `game.perf.uobject_count` | Gauge         | Number of active UObjects           |

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.

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

### [Network](https://docs.sentry.io/platforms/unreal/metrics.md#network)

Network metrics require Unreal Engine 5.7 or later. On older engine versions, this setting has no effect.

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:

```ini
[SystemSettings]
net.EnableNetStats=1
```

| Metric                              | Type              | Description                                                   |
| ----------------------------------- | ----------------- | ------------------------------------------------------------- |
| `game.perf.net.in_rate`             | Gauge (bytes/sec) | Incoming bandwidth                                            |
| `game.perf.net.out_rate`            | Gauge (bytes/sec) | Outgoing bandwidth                                            |
| `game.perf.net.in_packets`          | Gauge             | Incoming packets per second                                   |
| `game.perf.net.out_packets`         | Gauge             | Outgoing packets per second                                   |
| `game.perf.net.in_packets_lost`     | Gauge             | Incoming packets lost                                         |
| `game.perf.net.out_packets_lost`    | Gauge             | Outgoing packets lost                                         |
| `game.perf.net.ping`                | Gauge (ms)        | Client ping to server                                         |
| `game.perf.net.jitter`              | Gauge (ms)        | Client connection jitter (latency variation)                  |
| `game.perf.net.num_clients`         | Gauge             | Number of connected clients (server only)                     |
| `game.perf.net.ping_client_avg`     | Gauge (ms)        | Average ping across all clients (server only)                 |
| `game.perf.net.ping_client_max`     | Gauge (ms)        | Maximum ping across all clients (server only)                 |
| `game.perf.net.in_rate_client_avg`  | Gauge (bytes/sec) | Average incoming bandwidth per client (server only)           |
| `game.perf.net.out_rate_client_avg` | Gauge (bytes/sec) | Average outgoing bandwidth per client (server only)           |
| `game.perf.net.sat_connections`     | Gauge             | Connections skipped due to bandwidth saturation (server only) |

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.

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

## [Options](https://docs.sentry.io/platforms/unreal/metrics.md#options)

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

| Option                                   | Description                                                                            | Default |
| ---------------------------------------- | -------------------------------------------------------------------------------------- | ------- |
| **Enable Metrics**                       | Master toggle for the metrics feature                                                  | `false` |
| **Collect frame time metrics**           | Automatically emit frame time and per-thread performance metrics.                      | `false` |
| **Frame time sample interval (frames)**  | Emit performance metrics every Nth frame.                                              | `30`    |
| **Collect GC pause metrics**             | Emit a metric for each garbage collection pause duration.                              | `false` |
| **Collect game stats metrics**           | Periodically collect game stats such as process memory usage and active UObject count. | `false` |
| **Game stats sample interval (seconds)** | How often to sample game stats metrics.                                                | `60`    |
| **Before Metric Handler**                | Handler to modify or filter metrics before sending                                     | None    |

### [Before-Metric Handler](https://docs.sentry.io/platforms/unreal/metrics.md#before-metric-handler)

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

```cpp
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:

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

## [Default Attributes](https://docs.sentry.io/platforms/unreal/metrics.md#default-attributes)

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

### [Core Attributes](https://docs.sentry.io/platforms/unreal/metrics.md#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](https://docs.sentry.io/platforms/unreal/metrics.md#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.