Skip to content

Commit 72aa538

Browse files
limbonautbruno-garcia
limbonaut
and
bruno-garcia
authored
feat: Godot Engine SDK docs (#12774)
* Initial commit * Complete options doc * Add configuration examples * Fix code tags * Fix options not showing in the sidebar * Add configuration/environment * Add configuration/releases * Add configuration/sampling * Add configuration/filtering * Add usage and set-level * Add enriching/context * Add enriching master page * Add identify-user * Add enriching/tags * Add enriching/breadcrumbs * Add data-management/sensitive-data * Emphasize stable version * Anchors for configuration script section in options * Link to configuration script section * Deemphasize alert * Convert code example to tabs (default in Godot) * Second pass fixes * Better screenshot * Sync with class reference * Apply suggestions from code review --------- Co-authored-by: Bruno Garcia <[email protected]>
1 parent 23fa3fc commit 72aa538

File tree

36 files changed

+822
-0
lines changed

36 files changed

+822
-0
lines changed

‎docs/platforms/godot/configuration/environments.mdx

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Environments
3+
sidebar_order: 30
4+
description: "Learn how to configure your SDK to tell Sentry about your environments."
5+
---
6+
7+
Environments tell you where an error occurred, whether that's in your production system, your staging server, or elsewhere.
8+
9+
Sentry automatically creates an environment when it receives an event with the `environment` parameter set.
10+
11+
Environments are case-sensitive. The environment name can't contain newlines, spaces or forward slashes, can't be the string "None", or exceed 64 characters. You can't delete environments, but you can [hide](/product/sentry-basics/environments/#hidden-environments) them.
12+
13+
<PlatformContent includePath="set-environment" />
14+
15+
Environments help you better filter issues, releases, and user feedback in the Issue Details page of sentry.io, which you learn more about in our [documentation that covers using environments](/product/sentry-basics/environments/).

‎docs/platforms/godot/configuration/filtering.mdx

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Filtering
3+
description: "Learn more about how to configure your SDK to filter events reported to Sentry."
4+
sidebar_order: 60
5+
---
6+
7+
When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it's the right information, at a reasonable volume.
8+
9+
The Sentry SDKs have several configuration options to help you filter out events.
10+
11+
We also offer [Inbound Filters](/concepts/data-management/filtering/) to filter events in sentry.io. We recommend filtering at the client level though, because it removes the overhead of sending events you don't actually want. Learn more about the [fields available in an event](https://develop.sentry.dev/sdk/data-model/event-payloads/).
12+
13+
## Filtering Error Events
14+
15+
Configure your SDK to filter error events by using the <PlatformIdentifier name="before-send" /> callback method and configuring, enabling, or disabling integrations.
16+
17+
### Using <PlatformIdentifier name="before-send" />
18+
19+
All Sentry SDKs support the <PlatformIdentifier name="before-send" /> callback method. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. <PlatformIdentifier name="before-send" /> receives the event object as a parameter, which you can use to either modify the event’s data or drop it completely by returning `null`, based on custom logic and the data available on the event.
20+
21+
<PlatformContent includePath="configuration/before-send/" />
22+
23+
Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/error-monitoring/breadcrumbs/).

‎docs/platforms/godot/configuration/index.mdx

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Configuration
3+
description: "Additional configuration options for the SDK."
4+
sidebar_order: 5
5+
---
6+
7+
<PageGrid />

‎docs/platforms/godot/configuration/options.mdx

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: Options
3+
sidebar_order: 1
4+
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."
5+
---
6+
7+
<PlatformContent includePath="configuration/config-intro" />
8+
9+
## Core Options
10+
11+
Options that can be read from an environment variable (`SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`) are read automatically.
12+
13+
<ConfigKey name="dsn">
14+
15+
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.
16+
17+
In runtimes without a process environment (such as the browser) that fallback does not apply.
18+
19+
Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization).
20+
21+
</ConfigKey>
22+
23+
<ConfigKey name="debug">
24+
25+
Turns debug mode on or off. If `debug` is enabled, the SDK will print useful debugging information to standard output. These messages do not appear in the Godot console or log file but can be seen when launching Godot application from a terminal. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns.
26+
27+
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.
28+
29+
</ConfigKey>
30+
31+
<ConfigKey name="release">
32+
33+
Release version of the application. This value must be unique across all projects in your organization. By default, 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}"`. Alternatively, you can set `release` to a custom value, optionally using the `{app_name}` and `{app_version}` placeholders in a [configuration script](#configuration-script).
34+
35+
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](/product/releases/) or the <SandboxLink scenario="releases">sandbox</SandboxLink>.
36+
37+
</ConfigKey>
38+
39+
<ConfigKey name="dist">
40+
41+
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.
42+
43+
</ConfigKey>
44+
45+
<ConfigKey name="environment">
46+
47+
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).
48+
49+
The SDK automatically detects Godot-specific environments, such as `headless_server` and `export_release`, but you can also set it to your own value in a [configuration script](#configuration-script).
50+
51+
</ConfigKey>
52+
53+
<ConfigKey name="sample-rate">
54+
55+
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.
56+
57+
</ConfigKey>
58+
59+
<ConfigKey name="max-breadcrumbs">
60+
61+
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.
62+
63+
</ConfigKey>
64+
65+
<ConfigKey name="send-default-pii">
66+
67+
If enabled, the SDK will include PII (Personally Identifiable Information) with the events.
68+
69+
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_](../../data-management/sensitive-data/).
70+
71+
</ConfigKey>
72+
73+
<ConfigKey name="enabled">
74+
75+
If `false`, the SDK will not initialize. This is useful for temporarily disabling the SDK in the Project Settings, or in a [configuration script](#configuration-script).
76+
77+
</ConfigKey>
78+
79+
<ConfigKey name="disabled-in-editor">
80+
81+
If `true`, the SDK will not initialize in the Godot editor.
82+
83+
</ConfigKey>
84+
85+
<ConfigKey name="attach-log">
86+
87+
If enabled, the SDK will attach the Godot log file to the event.
88+
89+
</ConfigKey>
90+
91+
## Error Logger Options
92+
93+
<ConfigKey name="error-logger-enabled">
94+
95+
If `true`, the SDK will capture logged errors as events and/or breadcrumbs, as defined by `error_logger_event_mask` and `error_logger_breadcrumb_mask` options. Crashes are always captured.
96+
97+
</ConfigKey>
98+
99+
<ConfigKey name="error-logger-breadcrumb-mask">
100+
101+
Specifies the types of errors captured as breadcrumbs. Accepts a single value or a bitwise combination of `GodotErrorMask` masks.
102+
103+
`GodotErrorMask` values:
104+
- `MASK_NONE`: No logger errors will be captured.
105+
- `MASK_ERROR`: Native errors will be captured. These are typically C++ errors, which may also originate from a script.
106+
- `MASK_WARNING`: Warnings will be captured.
107+
- `MASK_SCRIPT`: Script errors will be captured.
108+
- `MASK_SHADER`: Shader errors will be captured.
109+
110+
```gdscript
111+
var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT
112+
options.error_logger_breadcrumb_mask = mask
113+
```
114+
115+
</ConfigKey>
116+
117+
<ConfigKey name="error-logger-event-mask">
118+
119+
Specifies the types of errors captured as events. Accepts a single value or a bitwise combination of `GodotErrorMask` masks.
120+
121+
```gdscript
122+
var mask = SentryOptions.MASK_ERROR | SentryOptions.MASK_SCRIPT
123+
options.error_logger_event_mask = mask
124+
```
125+
126+
</ConfigKey>
127+
128+
<ConfigKey name="error-logger-include-source">
129+
130+
If `true`, the SDK will include the surrounding source code of logged errors, if available in the exported project.
131+
132+
</ConfigKey>
133+
134+
<ConfigKey name="error-logger-limits">
135+
136+
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.
137+
138+
This option contains multiple properties that govern the behavior of throttling. The following paragraphs explain each of those properties in detail.
139+
140+
`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.
141+
142+
`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 will be captured until the next interval.
143+
144+
`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.
145+
146+
`throttle_window_ms` specifies the time window in milliseconds for `throttle_events`.
147+
148+
</ConfigKey>
149+
150+
## Hooks
151+
152+
These options can be used to hook the SDK in various ways to customize the reporting of events.
153+
154+
The callbacks you set as hooks will be called on the thread where the event happened. So you can only use
155+
thread-safe APIs and only use Godot-specific APIs after you've checked that you're on the main thread.
156+
157+
<ConfigKey name="before-send">
158+
159+
If assigned, this callback runs before a message or error event is sent to Sentry. It takes `SentryEvent` as a parameter and returns either the same event object, with or without modifications, or `null` to skip reporting the event. You can assign it in a [configuration script](#configuration-script). This can be used, for instance, for stripping PII before sending.
160+
161+
```gdscript
162+
func _before_send(event: SentryEvent) -> SentryEvent:
163+
if event.environment.contains("editor"):
164+
# Discard event if running from the editor.
165+
return null
166+
if event.message.contains("Bruno"):
167+
# Remove sensitive information from the event.
168+
event.message = event.message.replace("Bruno", "REDACTED")
169+
return event
170+
```
171+
172+
</ConfigKey>
173+
174+
<ConfigKey name="on-crash">
175+
176+
If assigned, this callback runs before a crash event is sent to Sentry. In contrast to `before_send`, it is only called when a crash occurred. It takes `SentryEvent` as a parameter and returns either the same event object, with or without modifications, or `null` to skip reporting the event. You can assign it in a [configuration script](#configuration-script).
177+
178+
```gdscript
179+
func _on_crash(event: SentryEvent) -> SentryEvent:
180+
if event.environment.contains("editor"):
181+
# Discard event if running from the editor.
182+
return null
183+
if event.message.contains("Bruno"):
184+
# Remove sensitive information from the event.
185+
event.message = event.message.replace("Bruno", "REDACTED")
186+
return event
187+
```
188+
189+
</ConfigKey>

‎docs/platforms/godot/configuration/releases.mdx

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Releases & Health
3+
sidebar_order: 40
4+
description: "Learn how to configure your SDK to tell Sentry about your releases."
5+
---
6+
7+
<Alert>
8+
9+
The Crash Free Session Rate requires [native support](/platforms/unity/native-support/). On platforms that don't yet have native support, the SDK reports sessions that did not end gracefully as _Abnormal_, which leads to 100% crash free sessions being recorded. If you're building on a platform that doesn't have native support yet, you should monitor your app's _Abnormal_ rate.
10+
11+
</Alert>
12+
13+
A release is a version of your code that is deployed to an <PlatformLink to="/configuration/environments/">environment</PlatformLink>. When you give Sentry information about your releases, you can:
14+
15+
- Determine issues and regressions introduced in a new release
16+
- Predict which commit caused an issue and who is likely responsible
17+
- Resolve issues by including the issue number in your commit message
18+
- Receive email notifications when your code gets deployed
19+
20+
## Bind the Version
21+
22+
Include a release ID (often called a "version") when you initialize the SDK.
23+
24+
The release name cannot:
25+
26+
- contain newlines, tabulator characters, forward slashes(`/`) or back slashes(`\`)
27+
- be (in their entirety) period (`.`), double period (`..`), or space ( )
28+
- exceed 200 characters
29+
30+
The value can be arbitrary, but we recommend either of these naming strategies:
31+
32+
- **Semantic Versioning**: `package@version` or `package@version+build` (for example, `[email protected]+1234`)
33+
- `package` is the unique identifier of the project/app (`CFBundleIdentifier` on iOS, `packageName` on Android)
34+
- `version` is the semver-like structure `<major>.<minor?>.<patch?>.<revision?>-<prerelease?>` (`CFBundleShortVersionString` on iOS, `versionName` on Android)
35+
- `build` is the number that identifies an iteration of your app (`CFBundleVersion` on iOS, `versionCode` on Android)
36+
- **Commit SHA**: If you use a version control system like Git, we recommend using the identifying hash (for example, the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let Sentry CLI automatically determine this hash for supported version control systems. Learn more in our [Sentry CLI](/cli/releases/#creating-releases) documentation.
37+
38+
<Alert>
39+
40+
Releases are global per organization; prefix them with something project-specific for easy differentiation.
41+
42+
</Alert>
43+
44+
The behavior of a few features depends on whether a project is using semantic or time-based versioning.
45+
46+
- Regression detection
47+
- `release:latest`
48+
49+
We automatically detect whether a project is using semantic or time-based versioning based on:
50+
51+
- If ≤ 2 releases total: we look at most recent release.
52+
- If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver.
53+
- If 10 or more releases: if any of the most recent 3 releases is semver, and 3 out of the most recent 10 releases is semver, then the project is semver.
54+
55+
## Setting a Release
56+
57+
<PlatformContent includePath="set-release" notateUnsupported />
58+
59+
How you make the release name (or version) available to your code is up to you. For example, you could use an environment variable that is set during the build process or during initial start-up.
60+
61+
Setting the release name tags each event with that release name. We recommend that you tell Sentry about a new release before sending events with that release name, as this will unlock a few more features. Learn more in our [Releases](/product/releases/) documentation.
62+
63+
If you don't tell Sentry about a new release, Sentry will automatically create a release entity in the system the first time it sees an event with that release ID.
64+
65+
After configuring your SDK, you can install a repository integration or manually supply Sentry with your own commit metadata. Read our documentation about [setting up releases](/product/releases/setup/) for further information about integrations, associating commits, and telling Sentry when deploying releases.
66+
67+
## Release Health
68+
69+
Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crash), and [session data](/product/releases/health/#session). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters.
70+
71+
<Alert>
72+
73+
Crash reporting and app hang detection are not available for watchOS.
74+
75+
</Alert>
76+
77+
In order to monitor release health, the SDK sends session data.
78+
79+
### Sessions
80+
81+
A session represents the interaction between the user and the application. Sessions contain a timestamp, a status (if the session was OK or if it crashed), and are always linked to a release. Most Sentry SDKs can manage sessions automatically.
82+
83+
<PlatformContent includePath="configuration/auto-session-tracking" />
84+
85+
<Alert>
86+
87+
Release health support for .NET is currently limited to single-instance **client** applications only. This means it can be used with WPF, Xamarin, WinForms and similar app models.
88+
Support for server frameworks such as ASP.NET is planned.
89+
90+
</Alert>

‎docs/platforms/godot/configuration/sampling.mdx

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Sampling
3+
description: "Learn how to configure the volume of error and transaction events sent to Sentry."
4+
sidebar_order: 50
5+
---
6+
7+
Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume.
8+
9+
## Sampling Error Events
10+
11+
To send a representative sample of your errors to Sentry, set the <PlatformIdentifier name="sample-rate" /> option in your SDK configuration to a number between `0` (0% of errors sent) and `1` (100% of errors sent). This is a static rate, which will apply equally to all errors. For example, to sample 25% of your errors:
12+
13+
<PlatformContent includePath="configuration/sample-rate" />
14+
15+
The error sample rate defaults to `1`, meaning all errors are sent to Sentry.
16+
17+
<Alert>
18+
19+
Changing the error sample rate requires re-deployment. In addition, setting an SDK sample rate limits visibility into the source of events. Setting a rate limit for your project (which only drops events when volume is high) may better suit your needs.
20+
21+
</Alert>

‎docs/platforms/godot/data-management/index.mdx

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Data Management
3+
description: Manage your events by pre-filtering, scrubbing sensitive information, and forwarding them to other systems.
4+
sidebar_order: 2500
5+
---
6+
7+
<PageGrid />

0 commit comments

Comments
 (0)