diff --git a/docs/platforms/godot/configuration/options.mdx b/docs/platforms/godot/configuration/options.mdx index 8c2acb0f7cf9af..d14c421a8ae9bd 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 217d37ce01738d..499aceb73ac182 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 a0ce09d0069f2c..dea82adab6515e 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`.