Set Up Metrics

Requirements

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

Setup

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

Project Settings Configuration

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

Programmatic Configuration

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

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

Usage

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

Metric Types

Counters

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

# 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

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

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

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

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

Custom Attributes

Add attributes to filter and group metrics in Sentry:

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.

Global Attributes

You can set global attributes that are automatically included in all metrics and logs. This is useful for attaching contextual information that should appear on every metric entry.

# Set global attributes that apply to all metrics and logs
SentrySDK.set_attribute("level", "castle")
SentrySDK.set_attribute("difficulty", "hard")

# All subsequent metrics will include these attributes
SentrySDK.metrics.count("enemy_defeated")

# Clear when returning to the main menu
SentrySDK.remove_attribute("level")

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 for the full list.

# 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

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

before_send_metric

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

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

The Godot 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.