# Set Up Metrics | Sentry for Godot Engine

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

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

Metrics for Godot Engine are supported in Sentry Godot SDK version `1.4.0` and above.

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

Metrics are enabled by default in the Sentry Godot SDK. No additional setup is required to start sending metrics.

##### Note

Metrics are not supported on Apple platforms (macOS and iOS). Attempting to use metrics on these platforms will result in a warning.

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

To disable metrics, navigate to **Project Settings > Sentry > Experimental** and uncheck the **Enable Metrics** option.

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

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

```GDScript
SentrySDK.init(func(options: SentryOptions) -> void:
	options.experimental.enable_metrics = false
)
```

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

Once metrics are enabled and the SDK is initialized, you can emit metrics using `SentrySDK.metrics`.

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

| Type           | Use For                                       |
| -------------- | --------------------------------------------- |
| `Counter`      | Events (matches started, items purchased)     |
| `Gauge`        | Current values (players online, memory usage) |
| `Distribution` | Value ranges (load times, frame times)        |

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

Track the number of times something happens. Each increment adds to a cumulative total:

```GDScript
# Increment by 1 (default)
SentrySDK.metrics.count("match_started")

# Increment by a specific amount with attributes
SentrySDK.metrics.count("in_app_purchase", 1, {"item": "sword_of_fire"})
```

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

Track current values at a point in time, like a snapshot. Sentry computes aggregates like min, max, avg, sum, and count:

```GDScript
SentrySDK.metrics.gauge("players_online", lobby.get_player_count())

# With a unit
SentrySDK.metrics.gauge("memory_usage", OS.get_static_memory_usage(), SentryUnit.byte)
```

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

Record numeric values to compute statistical aggregates such as p50, p95, avg, min, and max:

```GDScript
SentrySDK.metrics.distribution("level_load_time", load_time, SentryUnit.millisecond)
```

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

Add attributes to filter and group metrics in Sentry:

```GDScript
SentrySDK.metrics.count("enemies_spawned", wave_size, {"level": "castle"})

SentrySDK.metrics.distribution("level_load_time", load_time, SentryUnit.millisecond, {
	"scene": get_tree().current_scene.name
})
```

Attributes support `bool`, `int`, `float`, and `String` data types. Other types will be converted to strings.

### [Units](https://docs.sentry.io/platforms/godot/metrics.md#units)

For gauge and distribution metrics, you can specify a unit to help Sentry display values in a human-readable format. The `SentryUnit` singleton provides predefined constants for common units. See [supported units](https://develop.sentry.dev/sdk/foundations/data-model/attributes/#units) for the full list.

```GDScript
# Duration units
SentrySDK.metrics.distribution("level_load_time", load_time, SentryUnit.millisecond)

# Information units
SentrySDK.metrics.gauge("memory_usage", OS.get_static_memory_usage(), SentryUnit.byte)

# Custom units (as strings)
SentrySDK.metrics.gauge("items_in_inventory", item_count, "item")
```

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

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

| Option                   | Description                                                        | Default |
| ------------------------ | ------------------------------------------------------------------ | ------- |
| **enable\_metrics**      | Toggle for the metrics feature (experimental)                      | `true`  |
| **before\_send\_metric** | Callback to modify or filter metrics before sending (experimental) | None    |

### [before\_send\_metric](https://docs.sentry.io/platforms/godot/metrics.md#before_send_metric)

To filter metrics or modify them before they are sent to Sentry, you can use the `before_send_metric` option:

```GDScript
SentrySDK.init(func(options: SentryOptions) -> void:
	options.experimental.before_send_metric = _before_send_metric
)

func _before_send_metric(metric: SentryMetric) -> SentryMetric:
	# Drop debug-only metrics in release builds.
	if not OS.is_debug_build() and metric.name.begins_with("debug."):
		return null
	# Enrich with runtime context.
	metric.set_attribute("current_scene", get_tree().current_scene.name)
	return metric
```

The `before_send_metric` callback receives a `SentryMetric` object, and should return either the same metric object (with or without modifications) or `null` to discard it.

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

The Godot SDK automatically attaches the following attributes to every metric:

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