---
title: "Options"
description: "Learn more about how the SDK can be configured via options. These are being passed to the init function and therefore set when the SDK is first initialized."
url: https://docs.sentry.io/platforms/godot/configuration/options/
---

# Options | Sentry for Godot Engine

Options control how the SDK is initialized and behaves at runtime. You can configure them in the **Project Settings** under the **Sentry** category, or override them programmatically when initializing the SDK in code.

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

If **Auto Init** is enabled in **Project Settings**, the SDK initializes automatically when the game starts. However, if you need finer control — for example, to define callbacks like [`before_send`](https://docs.sentry.io/platforms/godot/configuration/options.md#before_send)— you can disable **Auto Init** and manually initialize the SDK from code.

The earliest point to configure and initialize the SDK is `MainLoop._initialize()`.

To do this:

1. Disable **Auto Init** in **Project Settings -> Sentry -> Options**.
2. Create a new script that extends `SceneTree` and add a `class_name`.
3. Assign that `class_name` as your main loop type in **Project Settings → Application → Run → Main Loop Type**.
4. Define `_initialize()` method in your script and call `SentrySDK.init()` there.

Here’s a complete example:

```gdscript
class_name ProjectMainLoop
extends SceneTree
## Tip: Set "ProjectMainLoop" as your main loop type in the project settings
##      under `application/run/main_loop_type`.

func _initialize() -> void:
	SentrySDK.init(func(options: SentryOptions) -> void:
		if OS.is_debug_build():
			options.environment = "debug"
			options.debug = true
		options.release = "mygame@1.0.0"
		options.before_send = _before_send
	)

func _before_send(event: SentryEvent) -> SentryEvent:
	if event.environment.contains("editor"):
		# Discard event if running from the editor.
		return null
	var error_message: String = event.get_exception_value(0)
	if error_message.contains("Bruno"):
		# Remove sensitive information from the event.
		var redacted_message := error_message.replace("Bruno", "REDACTED")
		event.set_exception_value(0, redacted_message)
	return event
```

Prefer automatic initialization when possible — it runs before your code and helps ensure no startup events are missed. Use manual initialization only for cases that require runtime customization (custom [`before_send`](https://docs.sentry.io/platforms/godot/configuration/options.md#before_send)handler, dynamic release values, programmatic sampling, etc.).

## [Available Options](https://docs.sentry.io/platforms/godot/configuration/options.md#available-options)



## [Core Options](https://docs.sentry.io/platforms/godot/configuration/options.md#core-options)

Options that can be read from an environment variable (`SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`) are read automatically.

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

| Type | `string` |
| ---- | -------- |

The DSN tells the SDK where to send the events. If this value is not provided, the SDK will try to read it from the `SENTRY_DSN` environment variable. If that variable also does not exist, the SDK will just not send any events.

In runtimes without a process environment (such as the browser) that fallback does not apply.

Learn more about [DSN utilization](https://docs.sentry.io/product/sentry-basics/dsn-explainer.md#dsn-utilization).

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

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Turns debug mode on or off. If `debug` is enabled, the SDK will print useful debugging information. You can see it in the Output panel of the Godot editor. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns.

In the Project Settings, this option appears as `Debug Printing` and defaults to `Auto`. When set to `Auto`, the `debug` is enabled in debug builds (such as the editor and debug exports), and disabled in release export.

You can control the verbosity using the `diagnostic_level` option.

### [diagnostic\_level](https://docs.sentry.io/platforms/godot/configuration/options.md#diagnostic_level)

| Type    | `SentrySDK.Level` |
| ------- | ----------------- |
| Default | `LEVEL_DEBUG`     |

Specifies the minimum level of messages to be printed if `debug` is turned on. Possible values are: `LEVEL_DEBUG`, `LEVEL_INFO`, `LEVEL_WARNING`, `LEVEL_ERROR`, and `LEVEL_FATAL`.

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

| Type | `string` |
| ---- | -------- |

Release version of the application. This value must be unique across all projects in your organization. If not set explicitly, the SDK will try to read this value from the `SENTRY_RELEASE` environment variable. Otherwise, the SDK reads from the `application/config/name` and `application/config/version` project settings to generate the release identifier in the format `"{app_name}@{app_version}"`. You can also set `release` to a custom value [programmatically](https://docs.sentry.io/platforms/godot/configuration/options.md#programmatic-configuration), optionally using the `{app_name}` and `{app_version}` placeholders.

Release names are strings, but some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in [the releases documentation](https://docs.sentry.io/product/releases.md) or the [sandbox](https://sandbox.sentry.io/?scenario=releases\&source=docs).

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

| Type | `string` |
| ---- | -------- |

Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. The dist has a max length of 64 characters.

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

| Type    | `string` |
| ------- | -------- |
| Default | `{auto}` |

Sets the environment. Environments indicate where an error occurred, such as in a release export, headless server, QA build, or another deployment. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `production` or similar).

If not set explicitly, the SDK will try to read this value from the `SENTRY_ENVIRONMENT` environment variable. Otherwise, this option defaults to `{auto}`, which automatically detects the environment based on the current runtime context and sets it to one of the following values: `editor_dev`, `editor_dev_run`, `export_debug`, `export_release`, or `dedicated_server`.

### [sample\_rate](https://docs.sentry.io/platforms/godot/configuration/options.md#sample_rate)

| Type    | `float` |
| ------- | ------- |
| Default | `1.0`   |

Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly.

### [max\_breadcrumbs](https://docs.sentry.io/platforms/godot/configuration/options.md#max_breadcrumbs)

| Type    | `int` |
| ------- | ----- |
| Default | `100` |

This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped.

### [shutdown\_timeout\_ms](https://docs.sentry.io/platforms/godot/configuration/options.md#shutdown_timeout_ms)

| Available since | `1.4.0` |
| --------------- | ------- |
| Type            | `int`   |
| Default         | `2000`  |

The maximum time in milliseconds the SDK will wait for pending events to be sent when `SentrySDK.close()` is called. If the timeout expires, the SDK will perform a forced shutdown and any unsent events may be lost.

### [send\_default\_pii](https://docs.sentry.io/platforms/godot/configuration/options.md#send_default_pii)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

If enabled, the SDK will include PII (Personally Identifiable Information) with the events.

This option is disabled by default. If you enable this option, be sure to manually remove what you don't want to send using our features for managing [*Sensitive Data*](https://docs.sentry.io/platforms/godot/data-management/sensitive-data.md).

### [attach\_log](https://docs.sentry.io/platforms/godot/configuration/options.md#attach_log)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

If enabled, the SDK will attach the Godot log file to the event.

### [attach\_screenshot](https://docs.sentry.io/platforms/godot/configuration/options.md#attach_screenshot)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

If enabled, the SDK will try to take a screenshot and attach it to the event.

This option is turned off by default.

##### Important

This feature is experimental and may impact performance when capturing screenshots. We recommend testing before enabling in production.

### [screenshot\_level](https://docs.sentry.io/platforms/godot/configuration/options.md#screenshot_level)

| Type    | `SentrySDK.Level` |
| ------- | ----------------- |
| Default | `LEVEL_FATAL`     |

Specifies the minimum level of events for which screenshots will be captured. Possible values are: `LEVEL_DEBUG`, `LEVEL_INFO`, `LEVEL_WARNING`, `LEVEL_ERROR`, and `LEVEL_FATAL`.

##### Note

Changing this option may impact performance in the frames the screenshots are taken.

### [attach\_scene\_tree](https://docs.sentry.io/platforms/godot/configuration/options.md#attach_scene_tree)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

If enabled, the SDK will capture and attach scene tree information to events. The scene tree data is attached as a `view-hierarchy.json` file, and you can explore it in the "Scene Tree" section of each issue that includes this attachment. This provides valuable context about your game's scene tree at the time of the error. See [Scene Tree](https://docs.sentry.io/platforms/godot/enriching-events/view-hierarchy.md) for more details.

This option is turned off by default.

### [app\_hang\_tracking](https://docs.sentry.io/platforms/godot/configuration/options.md#app_hang_tracking)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

If `true`, enables automatic detection and reporting of application hangs. The SDK will monitor the main thread and report hang events when it becomes unresponsive for longer than the duration specified in `app_hang_timeout_sec`. This helps identify performance issues where the application becomes frozen or unresponsive.

##### Note

This feature is only supported on Android, iOS, and macOS platforms.

### [app\_hang\_timeout\_sec](https://docs.sentry.io/platforms/godot/configuration/options.md#app_hang_timeout_sec)

| Type    | `float` |
| ------- | ------- |
| Default | `5.0`   |

Specifies the timeout duration in seconds after which the application is considered to have hanged. When `app_hang_tracking` is enabled, if the main thread is blocked for longer than this duration, it will be reported as an application hang event to Sentry.

## [GUI-only Options](https://docs.sentry.io/platforms/godot/configuration/options.md#gui-only-options)

These options are only available in the **Project Settings** window.

### [auto\_init](https://docs.sentry.io/platforms/godot/configuration/options.md#auto_init)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Enables automatic SDK initialization when the game starts. The SDK initializes as early as possible in the lifecycle — before scenes are loaded or any scripts are executed.

This option is turned on by default.

### [skip\_auto\_init\_on\_editor\_play](https://docs.sentry.io/platforms/godot/configuration/options.md#skip_auto_init_on_editor_play)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Prevents automatic initialization when running the game from the editor (for example, by pressing the play button or **F5**). This setting only applies if **Auto Init** is enabled.

This option is turned off by default.

## [Logging Options](https://docs.sentry.io/platforms/godot/configuration/options.md#logging-options)

### [enable\_logs](https://docs.sentry.io/platforms/godot/configuration/options.md#enable_logs)

| Available since | `1.2.0` |
| --------------- | ------- |
| Type            | `bool`  |
| Default         | `false` |

If `true`, enables Sentry structured logs functionality, allowing you to use dedicated logging APIs through `SentrySDK.logger`, and Godot's built-in log messages are automatically captured and sent to Sentry Logs. Use `logger_enabled` and other `logger_*` options to control how Godot's error messages and log output (including `print()` statements) are captured and processed by Sentry.

This option is turned off by default.

## [Godot Logger Options](https://docs.sentry.io/platforms/godot/configuration/options.md#godot-logger-options)

### [logger\_enabled](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_enabled)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

If `true`, the SDK will capture logged errors as events, logs and/or breadcrumbs, as defined by `logger_event_mask` and `logger_breadcrumb_mask` options. Crashes are always captured. See also `enable_logs` option.

This option is turned on by default.

### [logger\_breadcrumb\_mask](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_breadcrumb_mask)

| Type    | `int`      |
| ------- | ---------- |
| Default | `15 (All)` |

Specifies the types of errors captured as breadcrumbs. Accepts a single value or a bitwise combination of `GodotErrorMask` masks. The default value captures native errors, warnings, script and shader errors (`MASK_ERROR | MASK_WARNING | MASK_SCRIPT | MASK_SHADER`).

`GodotErrorMask` values:

* `MASK_NONE`: No logger errors will be captured.
* `MASK_ERROR`: Native errors will be captured. These are typically C++ errors, which may also originate from a script.
* `MASK_WARNING`: Warnings will be captured.
* `MASK_SCRIPT`: Script errors will be captured.
* `MASK_SHADER`: Shader errors will be captured.

```GDScript
var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT
options.logger_breadcrumb_mask = mask
```

### [logger\_event\_mask](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_event_mask)

| Type    | `int`                      |
| ------- | -------------------------- |
| Default | `13 (All except warnings)` |

Specifies the types of errors captured as events. Accepts a single value or a bitwise combination of `GodotErrorMask` masks. The default value captures native, script and shader errors (`MASK_ERROR | MASK_SCRIPT` | `MASK_SHADER`).

```GDScript
var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT
options.logger_event_mask = mask
```

### [logger\_include\_source](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_include_source)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

If `true`, the SDK will include the surrounding source code of logged errors, if available in the exported project.

This option is turned on by default.

### [logger\_include\_variables](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_include_variables)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

If `true`, the SDK will include local variables from stack traces when capturing script errors. This allows showing the values of variables at each frame in the call stack. Requires enabling **Debug -> Settings -> GDScript -> Always Track Local Variables** in the **Project Settings**.

This option is turned off by default.

##### Note

Enabling this option may impact performance, especially for applications with frequent errors or deep call stacks.

### [logger\_messages\_as\_breadcrumbs](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_messages_as_breadcrumbs)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

If `true`, the SDK will capture log messages (such as `print()` statements) as breadcrumbs along with events.

This option is turned on by default.

### [logger\_limits](https://docs.sentry.io/platforms/godot/configuration/options.md#logger_limits)

| Type | `object` |
| ---- | -------- |

Defines throttling limits for the error logger. These limits are used to prevent the SDK from sending too many non-critical and repeating error events.

This option contains multiple properties that govern the behavior of throttling. The following paragraphs explain each of those properties in detail.

`events_per_frame` specifies the maximum number of error events to send per processed frame. If exceeded, no further errors will be captured until the next frame. This serves as a safety measure to prevent the SDK from overloading a single frame. Default: `5`.

`repeated_error_window_ms` specifies the minimum time interval in milliseconds between two identical errors. If exceeded, no further errors from the same line of code with the identical message will be captured until the next interval. Set it to `0` to disable this limit. Default: `1000`.

`throttle_events` specifies the maximum number of events allowed within a sliding time window of `throttle_window_ms` milliseconds. If exceeded, errors will be captured as breadcrumbs only until capacity is freed. Default: `20`.

`throttle_window_ms` specifies the time window in milliseconds for `throttle_events`. Set it to `0` to disable this limit. Default: `10000`.

## [Hooks](https://docs.sentry.io/platforms/godot/configuration/options.md#hooks)

These options can be used to hook the SDK in various ways to customize the reporting of events.

The callbacks you set as hooks will be called on the thread where the event happened. So you can only use thread-safe APIs and only use Godot-specific APIs after you've checked that you're on the main thread.

### [before\_send](https://docs.sentry.io/platforms/godot/configuration/options.md#before_send)

| Type | `Callable` |
| ---- | ---------- |

If assigned, this callback runs before an event is sent to Sentry. You can only set it [programmatically](https://docs.sentry.io/platforms/godot/configuration/options.md#programmatic-configuration). It takes `SentryEvent` as a parameter and returns either the same event object, with or without modifications, or `null` to skip reporting the event. This can be used, for instance, for stripping PII before sending.

```GDScript
func _before_send(event: SentryEvent) -> SentryEvent:
	if event.environment.contains("editor"):
		# Discard event if running from the editor.
		return null
	var error_message: String = event.get_exception_value(0)
	if error_message.contains("Bruno"):
		# Remove sensitive information from the event.
		var redacted_message := error_message.replace("Bruno", "REDACTED")
		event.set_exception_value(0, redacted_message)
	return event
```

### [before\_capture\_screenshot](https://docs.sentry.io/platforms/godot/configuration/options.md#before_capture_screenshot)

| Type | `Callable` |
| ---- | ---------- |

If assigned, this callback runs before a screenshot is captured. You can only set it [programmatically](https://docs.sentry.io/platforms/godot/configuration/options.md#programmatic-configuration). It takes `SentryEvent` as a parameter and returns `false` to skip capturing the screenshot, or `true` to capture the screenshot.

```GDScript
func _before_capture_screenshot(event: SentryEvent) -> bool:
	if is_showing_sensitive_info():
		return false # Don't capture screenshot!
	return true
```

### [before\_send\_log](https://docs.sentry.io/platforms/godot/configuration/options.md#before_send_log)

| Available since | `1.2.0`    |
| --------------- | ---------- |
| Type            | `Callable` |

If assigned, this callback will be called before sending a log message to Sentry. It can be used to modify the log message or prevent it from being sent.

```GDScript
func _before_send_log(log_entry: SentryLog) -> SentryLog:
	# Filter junk.
	if log_entry.body == "Junk message":
		return null
	# Remove sensitive information from log messages.
	log_entry.body = log_entry.body.replace("Bruno", "REDACTED")
	# Add custom attributes.
	log_entry.set_attribute("current_scene", current_scene.name)
	return log_entry
```