# 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.

## [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` |
| **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.