From 321a1dcb909511accaa454baa6656715f77789f8 Mon Sep 17 00:00:00 2001 From: Serhii Snitsaruk Date: Mon, 8 Jun 2026 16:12:37 +0200 Subject: [PATCH 1/3] docs(godot): Update logging options and add 2.0.0 migration guide Refresh the Godot logger options to match the 2.0.0 SDK: enable_logs now defaults to true, the GodotErrorMask enum is renamed to GodotLoggerEventMask, and a new logger_log_mask option (with the MASK_MESSAGE flag) controls which Godot logger events are captured as Sentry Logs. Mark logger_messages_as_breadcrumbs as deprecated. Auto-capturing Godot log output as Sentry Logs is now opt-in, so the Logs page's Godot Logging Integration section now explains logger_log_mask instead of claiming automatic capture. Add a "Migrating to 2.0.0" section covering the logging changes and the Android ANR detection split. Refs getsentry/sentry-godot#680 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../platforms/godot/configuration/options.mdx | 42 ++++++++++++------- docs/platforms/godot/migration/index.mdx | 32 +++++++++++++- platform-includes/logs/usage/godot.mdx | 13 ++++-- 3 files changed, 69 insertions(+), 18 deletions(-) diff --git a/docs/platforms/godot/configuration/options.mdx b/docs/platforms/godot/configuration/options.mdx index 8c2acb0f7cf9a..d14c421a8ae9b 100644 --- a/docs/platforms/godot/configuration/options.mdx +++ b/docs/platforms/godot/configuration/options.mdx @@ -171,14 +171,14 @@ This option is turned off by default. ## Logging Options - + -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. +If `true`, enables Sentry structured logs functionality, allowing you to use the dedicated logging APIs through +`SentrySDK.logger`. Godot logger events listed in `logger_log_mask` are also automatically captured as [Sentry Logs](/product/explore/logs/); +`logger_log_mask` is empty by default, so no events are auto-captured. Use `logger_enabled` and the other `logger_*` +options to control how Godot's error messages and log output (including `print()` statements) are captured. -This option is turned off by default. +This option is turned on by default. @@ -192,16 +192,18 @@ This option is turned on by default. - + -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`). +Specifies the Godot logger events captured as breadcrumbs. Accepts a single value or a bitwise combination of `GodotLoggerEventMask` masks. The default value captures native errors, warnings, script and shader errors, and log messages (`MASK_ERROR | MASK_WARNING | MASK_SCRIPT | MASK_SHADER | MASK_MESSAGE`). -`GodotErrorMask` values: -- `MASK_NONE`: No logger errors will be captured. +`GodotLoggerEventMask` values: + +- `MASK_NONE`: No logger events 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. +- `MASK_MESSAGE`: Log messages, such as `print()` statements, will be captured. ```GDScript var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT @@ -210,9 +212,11 @@ options.logger_breadcrumb_mask = mask - + + +Specifies the Godot logger events captured as events. Accepts a single value or a bitwise combination of `GodotLoggerEventMask` masks. The default value captures native, script and shader errors (`MASK_ERROR | MASK_SCRIPT | MASK_SHADER`). -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`). +`MASK_MESSAGE` has no effect here. To capture log messages, set it in `logger_log_mask` and/or `logger_breadcrumb_mask` instead. ```GDScript var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT @@ -221,6 +225,16 @@ options.logger_event_mask = mask + + +Specifies the Godot logger events captured as [Sentry Logs](/product/explore/logs/). Accepts a single value or a bitwise combination of `GodotLoggerEventMask` masks. Empty by default, so no Godot logger events are captured as logs. Requires `enable_logs` to be turned on. + +```GDScript +options.logger_log_mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT | SentryOptions.MASK_SHADER +``` + + + If `true`, the SDK will include the surrounding source code of logged errors, if available in the exported project. @@ -245,9 +259,9 @@ Enabling this option may impact performance, especially for applications with fr -If `true`, the SDK will capture log messages (such as `print()` statements) as breadcrumbs along with events. +**Deprecated since 2.0.0.** Set the `MASK_MESSAGE` flag in `logger_breadcrumb_mask` instead — it's included in the default mask. -This option is turned on by default. +If `true`, the SDK will capture log messages (such as `print()` statements) as breadcrumbs along with events. diff --git a/docs/platforms/godot/migration/index.mdx b/docs/platforms/godot/migration/index.mdx index 217d37ce01738..499aceb73ac18 100644 --- a/docs/platforms/godot/migration/index.mdx +++ b/docs/platforms/godot/migration/index.mdx @@ -4,6 +4,34 @@ description: "Learn more about migrating to the current version." sidebar_order: 8000 --- +## Migrating to 2.0.0 + +### Breaking changes + +`enable_logs` now defaults to `true`, and the Godot logger integration no longer captures Godot's log output as Sentry Logs automatically. See [Changes to logging](#changes-to-logging) below. + +On Android, ANR (Application Not Responding) detection replaces App Hang Tracking and is now enabled by default. See [Android ANR detection](#android-anr-detection) below. + +### Changes to logging + +The Godot logger integration no longer auto-captures Godot's log output as Sentry Logs. To opt back in, set `logger_log_mask` to the events you want captured as logs: + +```gdscript +SentrySDK.init(func(options: SentryOptions) -> void: + options.logger_log_mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT | SentryOptions.MASK_SHADER +) +``` + +The `GodotErrorMask` enum was renamed to `GodotLoggerEventMask`, and a new `MASK_MESSAGE` flag captures log messages such as `print()` statements. Update the enum name if you reference these masks in code. + +`logger_messages_as_breadcrumbs` is deprecated. Set the `MASK_MESSAGE` flag in `logger_breadcrumb_mask` instead — it's included in the default mask. + +### Android ANR detection + +ANR (Application Not Responding) detection is now enabled by default on Android and is configured through Android-specific options under `SentryOptions.android`, or in the **Project Settings** under **Sentry > Android > Application Not Responding**. Set `SentryOptions.android.enable_anr_detection` to `false` to opt out. + +The App Hang Tracking options (`app_hang_tracking`, `app_hang_timeout_sec`) now apply to Apple platforms only. See the [configuration options](/platforms/godot/configuration/options/) for the available `options.android` settings. + ## Migrating to 1.0.0 ### Breaking changes @@ -18,7 +46,6 @@ The `attach_screenshot` and `screenshot_level` options have moved to the experim `enabled` and `disabled_in_editor_play` project settings were renamed to `auto_init` and `skip_auto_init_on_editor_play` for clarity. - ### Changes to breadcrumbs API Previously, `add_breadcrumb()` method accepted 5 parameters (3 of which were strings), making it confusing to use. The new approach uses a dedicated `SentryBreadcrumb` class: @@ -31,6 +58,7 @@ SentrySDK.add_breadcrumb(crumb) ``` For simple breadcrumbs, you can use a one-liner: + ```gdscript SentrySDK.add_breadcrumb(SentryBreadcrumb.create("Something happened")) ``` @@ -41,6 +69,7 @@ Configuration scripts and the `SentryConfiguration` class have been removed. To 1. Disable **Auto Init** in Godot's **Project Settings** window under **Sentry** category. 2. Create a main loop script with a `class_name` attribute, and init Sentry inside `_initialize()` method. + ```gdscript class_name MyMainLoop extends SceneTree @@ -60,4 +89,5 @@ func _before_send(ev: SentryEvent) -> SentryEvent: # Return the event (with or without modifications) or null to skip reporting. return ev ``` + 3. Assign your main loop type in Godot's **Project Settings** under **Application > Run > Main Loop Type** ("MyMainLoop" in the example code). diff --git a/platform-includes/logs/usage/godot.mdx b/platform-includes/logs/usage/godot.mdx index a0ce09d0069f2..dea82adab6515 100644 --- a/platform-includes/logs/usage/godot.mdx +++ b/platform-includes/logs/usage/godot.mdx @@ -60,6 +60,13 @@ SentrySDK.remove_attribute("level") ### Godot Logging Integration -When the feature is enabled, the SDK automatically captures Godot messages, warnings, and errors as logs. You can use -`print()`, `push_warning()`, and `push_error()` as usual. These show up as `info`, `warning`, and `error` logs. The SDK -also turns runtime errors and warnings into events based on your configuration. +By default, Godot's own log output isn't captured as [Sentry Logs](/product/explore/logs/). To capture Godot logger events as logs — engine errors, GDScript errors, shader errors, warnings, and log messages such as `print()` output — set the `logger_log_mask` option to the events you want: + +```GDScript +SentrySDK.init(func(options: SentryOptions) -> void: + options.logger_log_mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT | SentryOptions.MASK_SHADER +) +``` + +These appear as `error`, `warning`, and `info` logs in Sentry. The SDK can also capture the same logger events as +events and breadcrumbs — see `logger_event_mask` and `logger_breadcrumb_mask`. From eb5903d589e1aa6de6792cf9ef2eeb0262a20b83 Mon Sep 17 00:00:00 2001 From: Serhii Snitsaruk Date: Mon, 8 Jun 2026 16:19:45 +0200 Subject: [PATCH 2/3] docs(godot): Clarify GodotLoggerEventMask bit values Show the integer value of each mask flag and explain that bits 16/32/64 are reserved, so MASK_MESSAGE is 128 and the default breadcrumb mask is 143. Prevents confusion when computing bitwise combinations. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/platforms/godot/configuration/options.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/platforms/godot/configuration/options.mdx b/docs/platforms/godot/configuration/options.mdx index d14c421a8ae9b..95c82653eef63 100644 --- a/docs/platforms/godot/configuration/options.mdx +++ b/docs/platforms/godot/configuration/options.mdx @@ -198,12 +198,14 @@ Specifies the Godot logger events captured as breadcrumbs. Accepts a single valu `GodotLoggerEventMask` values: -- `MASK_NONE`: No logger events 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. -- `MASK_MESSAGE`: Log messages, such as `print()` statements, will be captured. +- `MASK_NONE` (`0`): No logger events will be captured. +- `MASK_ERROR` (`1`): Native errors will be captured. These are typically C++ errors, which may also originate from a script. +- `MASK_WARNING` (`2`): Warnings will be captured. +- `MASK_SCRIPT` (`4`): Script errors will be captured. +- `MASK_SHADER` (`8`): Shader errors will be captured. +- `MASK_MESSAGE` (`128`): Log messages, such as `print()` statements, will be captured. + +The values `16`, `32`, and `64` are reserved for future event types, which is why `MASK_MESSAGE` is `128` rather than `16`. The default `143` is the sum of all the flags above (`1 + 2 + 4 + 8 + 128`). Combine flags with the bitwise OR operator (`|`) rather than computing the integer by hand. ```GDScript var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT From 54ff5722ffd49fc282cc3ade86f0d88afee10e76 Mon Sep 17 00:00:00 2001 From: Serhii Snitsaruk Date: Mon, 8 Jun 2026 16:32:44 +0200 Subject: [PATCH 3/3] Undo changes --- docs/platforms/godot/configuration/options.mdx | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/platforms/godot/configuration/options.mdx b/docs/platforms/godot/configuration/options.mdx index 95c82653eef63..d14c421a8ae9b 100644 --- a/docs/platforms/godot/configuration/options.mdx +++ b/docs/platforms/godot/configuration/options.mdx @@ -198,14 +198,12 @@ Specifies the Godot logger events captured as breadcrumbs. Accepts a single valu `GodotLoggerEventMask` values: -- `MASK_NONE` (`0`): No logger events will be captured. -- `MASK_ERROR` (`1`): Native errors will be captured. These are typically C++ errors, which may also originate from a script. -- `MASK_WARNING` (`2`): Warnings will be captured. -- `MASK_SCRIPT` (`4`): Script errors will be captured. -- `MASK_SHADER` (`8`): Shader errors will be captured. -- `MASK_MESSAGE` (`128`): Log messages, such as `print()` statements, will be captured. - -The values `16`, `32`, and `64` are reserved for future event types, which is why `MASK_MESSAGE` is `128` rather than `16`. The default `143` is the sum of all the flags above (`1 + 2 + 4 + 8 + 128`). Combine flags with the bitwise OR operator (`|`) rather than computing the integer by hand. +- `MASK_NONE`: No logger events 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. +- `MASK_MESSAGE`: Log messages, such as `print()` statements, will be captured. ```GDScript var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT