From 136f9e12a3b966498fbd85313e2f8e8b6299a7af Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Mon, 3 Mar 2025 19:50:35 +0100 Subject: [PATCH 1/7] updated the core options, removed metrics, updated verify snippet, and added explainer on how the SDK captures errors --- .../unity/configuration/error-capture.mdx | 19 ++ .../unity/configuration/options/index.mdx | 177 +++++++++--------- .../getting-started-verify/unity.mdx | 2 +- 3 files changed, 108 insertions(+), 90 deletions(-) create mode 100644 docs/platforms/unity/configuration/error-capture.mdx diff --git a/docs/platforms/unity/configuration/error-capture.mdx b/docs/platforms/unity/configuration/error-capture.mdx new file mode 100644 index 0000000000000..051bdf4e7f32d --- /dev/null +++ b/docs/platforms/unity/configuration/error-capture.mdx @@ -0,0 +1,19 @@ +--- +title: Error Capture +sidebar_order: 60 +description: "Learn more about how to configure your SDK to automatically send events to Sentry." +--- + +The SDK relies on two integrations to capture errors: `UnityLogHandlerIntegration` and the `UnityApplicationLoggingIntegration`. While they sound similar, they serve different purposes. + +## UnityLogHandlerIntegration + +The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging system. From there it receives all log messages that are logged via the `Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` methods. These log messages are also added as breadcrumbs to future events. By default, the SDK will automatically capture messages logged via `Debug.LogError` as error events. This can be disabled by unchecking the automatic capture of `Debug.LogError` on the `Enrichment` tab, or by setting the `CaptureLogErrorEvents` option to `false`. + +https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html + +If configured, the SDK receives the stacktrace as part of the logging messages in a raw string format. The SDK is able to parse this format and display it in the Sentry UI. Unfortunately, to provide line numbers, the SDK needs to have an actual thrown exception object to fetch the required information for symbolication. Read more about the IL2CPP error symbolication works [here](/platforms/unity/configuration/il2cpp). If you're using Unity 6 or newer, you can enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stacktrace and will be parsed by the SDK. + +## UnityApplicationLoggingIntegration + +The SDK uses the `UnityApplicationLoggingIntegration` to add its own log handler right before Unity's logging system and passes the logs back to Unity. This allows the SDK to capture errors from the `Application.logMessageReceived` method. All handled exceptions (i.e., those captured via `Log.LogException` calls) and unhandled exceptions are captured by the SDK. These messages contain the actual exception object, which allows the SDK to fetch the required information for symbolication. diff --git a/docs/platforms/unity/configuration/options/index.mdx b/docs/platforms/unity/configuration/options/index.mdx index 80b3edf5fde7c..4340e253b9795 100644 --- a/docs/platforms/unity/configuration/options/index.mdx +++ b/docs/platforms/unity/configuration/options/index.mdx @@ -22,59 +22,29 @@ Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-uti - - -- Original - Default .NET stack trace format. -- Enhanced - Include `async`, return type, arguments, and more. - -Before version 3.0.0 of the Sentry SDK for .NET, there was no special treatment for the stack trace. Sentry reported what .NET made available at runtime. -This behavior now called `StackTraceMode.Original`. With the introduction of 3.0, a new default mode is `Enhanced`. - - + -Changing this value will affect issue grouping. Since the frame significantly changes shape. +Sets the environment. This string is freeform and set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). - +By default, the SDK reports `editor` when running inside the Unity Editor. Otherwise, the default environment is `production`. - - -Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. - -Example scenarios where it should be explicitly set to true: - -- Universal Windows platform (UWP) applications -- WinForms applications -- Windows Presentation Foundation (WPF) applications -- Single user console applications - -Defaults to `false`, unless in Blazor WASM, MAUI, Unity, or Xamarin where the default is `true`. - - + - +Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it to guarantee that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. -Allows you to specify a path to the local event- and crash-database of the Native SDK. This path will default to `.sentry-native` relative to the current working directory (`CWD`). While this is a convenient setting for development, we strongly urge you to provide an explicit database path for our production deployments. In many deployment scenarios, the path relative to the `CWD` will not be writable. For this reason, you should store the database in your application's user-specific data/cache directory (e.g., under `%AppData%\Local` on Windows, `~/Library/Application Support` on macOS, or `XDG_CACHE_HOME` on Linux). +By default the SDK will read from `Application.productName` and `Application.version` to create the release in the format `$"{Application.productName}@{Application.version}".` - + Turns debug mode on or off. If debug is enabled SDK will attempt to print out useful debugging information if something goes wrong with sending the event. The default is always `false`. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns. - - -If enabled, the SDK prints out debug information about if something went wrong while sending events. -It isn't recommended to use this in production. - - - - - - + Enabling `debug` mode makes the SDK generate as much diagnostic data as possible. However, if you'd prefer to lower the verbosity of the Sentry SDK diagnostics logs, configure this option to set the appropriate level: @@ -84,35 +54,25 @@ Enabling `debug` mode makes the SDK generate as much diagnostic data as possible - `error`: Only SDK internal errors are printed - `fatal`: Only critical errors are printed - - For app models that don't have a console to print to, you can customize the SDK's diagnostic logger to write to a file or to Visual Studio's debug window. - - -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. - - - -Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it to guarantee that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. - -By default the SDK will read from `Application.productName` and `Application.version` to create the release in the format `$"{Application.productName}@{Application.version}".` - - +## Data Enrichment & Attachments - + -Sets the environment. This string is freeform and set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). +A list of string prefixes of module names that belong to the app. This option takes precedence over `in-app-exclude`. -By default, the SDK reports `editor` when running inside the Unity Editor. Otherwise, the default environment is `production`. +Sentry differentiates stack frames that are directly related to your application ("in application") from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The application package is automatically marked as `inApp`. The difference is visible in [sentry.io](https://sentry.io), where only the "in application" frames are displayed by default. - + + +A list of string prefixes of module names that do not belong to the app, but rather to third-party packages. Modules considered not part of the app will be hidden from stack traces by default. -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. +This option can be overridden using . @@ -122,9 +82,9 @@ This variable controls the total amount of breadcrumbs that should be captured. - + -The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/envelopes/) to keep in cache. The SDKs use envelopes to send data, such as events, attachments, user feedback, and sessions to sentry.io. An envelope can contain multiple items, such as an event with a session and two attachments. Depending on the usage of the SDK, the size of an envelope can differ. If the number of envelopes in the local cache exceeds `max-cache-items`, the SDK deletes the oldest envelope and migrates the sessions to the next envelope to maintain the integrity of your release health stats. The default is `30`. +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. @@ -136,68 +96,97 @@ Grouping in Sentry is different for events with stack traces and without. As a r - + -If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent. +- Original - Default .NET stack trace format. +- Enhanced - Include `async`, return type, arguments, and more. + +Before version 3.0.0 of the Sentry SDK for .NET, there was no special treatment for the stack trace. Sentry reported what .NET made available at runtime. +This behavior now called `StackTraceMode.Original`. With the introduction of 3.0, a new default mode is `Enhanced`. -If you are using Sentry in your mobile app, read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) to assist with Apple App Store and Google Play app privacy details. +Changing this value will affect issue grouping. Since the frame significantly changes shape. -This option is turned off 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/). + + +Takes a screenshot of the application when an error happens and includes it as an attachment. +Learn more about enriching events with screenshots in our Screenshots documentation. - + -This option can be used to supply a server name. When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server. +The quality of the attached screenshot. It can be set to `full`, `high`, `medium` or `low`. -For ASP.NET and ASP.NET Core applications, the value will default to the server's name. For other application types, the value will default to the computer's name only when the `SendDefaultPii` is set to `true`, because the computer's name can be considered personally identifiable information (PII) in the case of a desktop or mobile application. + + + + +Captures the currently active scene's hierarchy and creates a `ViewHierarchy` when an error happens and includes it as an attachment. The creation is influenced by `MaxViewHierarchyRootObjects`, `MaxViewHierarchyDepth`, and `MaxViewHierarchyObjectChildCount`. - + -A list of string prefixes of module names that belong to the app. This option takes precedence over `in-app-exclude`. +Set this boolean to `false` to disable sending of client reports. Client reports are a protocol feature that let clients send status reports about themselves to Sentry. They are currently mainly used to emit outcomes for events that were never sent. -Sentry differentiates stack frames that are directly related to your application ("in application") from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The application package is automatically marked as `inApp`. The difference is visible in [sentry.io](https://sentry.io), where only the "in application" frames are displayed by default. + + + + +Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry. - + -A list of string prefixes of module names that do not belong to the app, but rather to third-party packages. Modules considered not part of the app will be hidden from stack traces by default. +Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. -This option can be overridden using . +Example scenarios where it should be explicitly set to true: + +- Universal Windows platform (UWP) applications +- WinForms applications +- Windows Presentation Foundation (WPF) applications +- Single user console applications + +Defaults to `false`, unless in Blazor WASM, MAUI, Unity, or Xamarin where the default is `true`. - + -Takes a screenshot of the application when an error happens and includes it as an attachment. -Learn more about enriching events with screenshots in our Screenshots documentation. +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. - +## Privacy & PII -The quality of the attached screenshot. It can be set to `full`, `high`, `medium` or `low`. + - +If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent. - + -Set this boolean to `false` to disable sending of client reports. Client reports are a protocol feature that let clients send status reports about themselves to Sentry. They are currently mainly used to emit outcomes for events that were never sent. +If you are using Sentry in your mobile app, read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) to assist with Apple App Store and Google Play app privacy details. + + + +This option is turned off 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/). - + -Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry. +This option can be used to supply a server name. When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server. + +For ASP.NET and ASP.NET Core applications, the value will default to the server's name. For other application types, the value will default to the computer's name only when the `SendDefaultPii` is set to `true`, because the computer's name can be considered personally identifiable information (PII) in the case of a desktop or mobile application. @@ -243,7 +232,7 @@ A callback function that controls view hierarchy capture behavior. Return `false -## Transport Options +## Transport & Network Options Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments. @@ -253,20 +242,18 @@ Switches out the transport used to send events. How this works depends on the SD - + -When set, a proxy can be configured that should be used for outbound requests. This is also used for HTTPS requests unless a separate `https-proxy` is configured. However, not all SDKs support a separate HTTPS proxy. SDKs will attempt to default to the system-wide configured proxy, if possible. For instance, on Unix systems, the `http_proxy` environment variable will be picked up. +The maximum number of [envelopes](https://develop.sentry.dev/sdk/data-model/envelopes/) to keep in cache. The SDKs use envelopes to send data, such as events, attachments, user feedback, and sessions to sentry.io. An envelope can contain multiple items, such as an event with a session and two attachments. Depending on the usage of the SDK, the size of an envelope can differ. If the number of envelopes in the local cache exceeds `max-cache-items`, the SDK deletes the oldest envelope and migrates the sessions to the next envelope to maintain the integrity of your release health stats. The default is `30`. - + -Specifies a local directory used for caching payloads. When this option is enabled (that is, when the directory is set), the Sentry SDK will persist envelopes locally before sending to Sentry. This configuration option is particularly useful if you expect your application to run in environments where internet connectivity is limited. +When set, a proxy can be configured that should be used for outbound requests. This is also used for HTTPS requests unless a separate `https-proxy` is configured. However, not all SDKs support a separate HTTPS proxy. SDKs will attempt to default to the system-wide configured proxy, if possible. For instance, on Unix systems, the `http_proxy` environment variable will be picked up. -The default value is `Application.persistentDataPath`. You can disable offline caching by setting it to `null`. - When caching is enabled (that is, is set), this option controls the timeout that limits how long the SDK will attempt to flush existing cache during initialization. Note that flushing the cache involves sending the payload to Sentry in a blocking operation. Setting this option to zero means that Sentry will **not** attempt to flush the cache during initialization, but instead will do so when the next payload is queued up. @@ -294,3 +281,15 @@ A number between `0` and `1`, controlling the percentage chance a given transact A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or must be defined to enable tracing. + + + +Controls whether the SDK will automatically trace the app's startup. + + + + + +Controls whether the SDK will automatically trace when loading scenes. + + diff --git a/platform-includes/getting-started-verify/unity.mdx b/platform-includes/getting-started-verify/unity.mdx index 57d3207165919..848db3f6b328c 100644 --- a/platform-includes/getting-started-verify/unity.mdx +++ b/platform-includes/getting-started-verify/unity.mdx @@ -9,7 +9,7 @@ public class TestMonoBehaviour : MonoBehaviour { Debug.Log("Captured Log"); // Breadcrumb Debug.LogWarning("Captured Warning"); // Breadcrumb - Debug.LogError("Captured Error"); // Captured Error + Debug.LogError("Captured Error"); // Captured Error by default // This will throw an unhandled Null Reference Exception testObject.GetComponent(); // Captured error From 3353c3946a4e5e21daed6d7c332d055e02f2bc80 Mon Sep 17 00:00:00 2001 From: Stefan Jandl Date: Tue, 4 Mar 2025 10:40:14 +0100 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Alex Krawiec --- docs/platforms/unity/configuration/error-capture.mdx | 4 ++-- docs/platforms/unity/configuration/options/index.mdx | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/platforms/unity/configuration/error-capture.mdx b/docs/platforms/unity/configuration/error-capture.mdx index 051bdf4e7f32d..eba6e2d772aba 100644 --- a/docs/platforms/unity/configuration/error-capture.mdx +++ b/docs/platforms/unity/configuration/error-capture.mdx @@ -4,7 +4,7 @@ sidebar_order: 60 description: "Learn more about how to configure your SDK to automatically send events to Sentry." --- -The SDK relies on two integrations to capture errors: `UnityLogHandlerIntegration` and the `UnityApplicationLoggingIntegration`. While they sound similar, they serve different purposes. +The Unity SDK relies on two integrations to capture errors: `UnityLogHandlerIntegration` and `UnityApplicationLoggingIntegration`. While they sound similar, they serve different purposes. ## UnityLogHandlerIntegration @@ -16,4 +16,4 @@ If configured, the SDK receives the stacktrace as part of the logging messages i ## UnityApplicationLoggingIntegration -The SDK uses the `UnityApplicationLoggingIntegration` to add its own log handler right before Unity's logging system and passes the logs back to Unity. This allows the SDK to capture errors from the `Application.logMessageReceived` method. All handled exceptions (i.e., those captured via `Log.LogException` calls) and unhandled exceptions are captured by the SDK. These messages contain the actual exception object, which allows the SDK to fetch the required information for symbolication. +The SDK uses the `UnityApplicationLoggingIntegration` to add its own log handler right before Unity's logging system and passes the logs back to Unity. This allows the SDK to capture errors from the `Application.logMessageReceived` method. All handled exceptions (such as those captured via `Log.LogException` calls) and unhandled exceptions are captured by the SDK. These messages contain the actual exception object, which allows the SDK to fetch the required information for symbolication. diff --git a/docs/platforms/unity/configuration/options/index.mdx b/docs/platforms/unity/configuration/options/index.mdx index 4340e253b9795..c81a5f64b7876 100644 --- a/docs/platforms/unity/configuration/options/index.mdx +++ b/docs/platforms/unity/configuration/options/index.mdx @@ -32,7 +32,7 @@ By default, the SDK reports `editor` when running inside the Unity Editor. Other -Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it to guarantee that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. +Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it, guaranteeing that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. By default the SDK will read from `Application.productName` and `Application.version` to create the release in the format `$"{Application.productName}@{Application.version}".` @@ -84,7 +84,7 @@ This variable controls the total amount of breadcrumbs that should be captured. -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. +This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. Just 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. @@ -102,11 +102,11 @@ Grouping in Sentry is different for events with stack traces and without. As a r - Enhanced - Include `async`, return type, arguments, and more. Before version 3.0.0 of the Sentry SDK for .NET, there was no special treatment for the stack trace. Sentry reported what .NET made available at runtime. -This behavior now called `StackTraceMode.Original`. With the introduction of 3.0, a new default mode is `Enhanced`. +This behavior now called `StackTraceMode.Original`. With the introduction of 3.0, the new default mode is `Enhanced`. -Changing this value will affect issue grouping. Since the frame significantly changes shape. +Changing this value will affect issue grouping since the frame significantly changes shape. From f59cd883235679151a5a1243e16b1c6c4004a37a Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 4 Mar 2025 13:14:49 +0100 Subject: [PATCH 3/7] reworked the error capture explainer --- .../unity/configuration/error-capture.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/platforms/unity/configuration/error-capture.mdx b/docs/platforms/unity/configuration/error-capture.mdx index eba6e2d772aba..c1576aa7fac51 100644 --- a/docs/platforms/unity/configuration/error-capture.mdx +++ b/docs/platforms/unity/configuration/error-capture.mdx @@ -8,12 +8,18 @@ The Unity SDK relies on two integrations to capture errors: `UnityLogHandlerInte ## UnityLogHandlerIntegration -The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging system. From there it receives all log messages that are logged via the `Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` methods. These log messages are also added as breadcrumbs to future events. By default, the SDK will automatically capture messages logged via `Debug.LogError` as error events. This can be disabled by unchecking the automatic capture of `Debug.LogError` on the `Enrichment` tab, or by setting the `CaptureLogErrorEvents` option to `false`. +The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging system. From there it receives all log messages that are logged via the `Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` methods and those log messages are added as breadcrumbs to future events. By default, the SDK will also automatically capture messages logged via `Debug.LogError` as error events and send them to Sentry. This behaviour can be disabled by unchecking the automatic capture of `Debug.LogError` on the `Enrichment` tab, or programmatically, by setting the `CaptureLogErrorEvents` option to `false` in the [configure callback](/platforms/unity/configuration/options/programmatic-configuration). -https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html +### Stacktrace Support & Line Numbers -If configured, the SDK receives the stacktrace as part of the logging messages in a raw string format. The SDK is able to parse this format and display it in the Sentry UI. Unfortunately, to provide line numbers, the SDK needs to have an actual thrown exception object to fetch the required information for symbolication. Read more about the IL2CPP error symbolication works [here](/platforms/unity/configuration/il2cpp). If you're using Unity 6 or newer, you can enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stacktrace and will be parsed by the SDK. +If [configured](https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html), Unity will include the stacktraces with the log messages as raw strings. The SDK is able to parse and display this stacktrace in the issues details. + +If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stacktrace and will be parsed by the SDK. Unfortunately, since there is no native exception at the time of logging, the SDK is not be able to provide line numbers. + + +If you're using a version older than Unity 6, the SDK is unable to provide line numbers for events captured through `Debug.LogError`. Line numbers are not part of the logging information provided by Unity. + ## UnityApplicationLoggingIntegration -The SDK uses the `UnityApplicationLoggingIntegration` to add its own log handler right before Unity's logging system and passes the logs back to Unity. This allows the SDK to capture errors from the `Application.logMessageReceived` method. All handled exceptions (such as those captured via `Log.LogException` calls) and unhandled exceptions are captured by the SDK. These messages contain the actual exception object, which allows the SDK to fetch the required information for symbolication. +The SDK uses the `UnityApplicationLoggingIntegration` to add its own log handler right before Unity's logging system. It then passes the logs back to Unity. This allows the SDK to capture errors through the `Application.logMessageReceived` method. All handled exceptions - such as those captured via `Log.LogException` calls - and unhandled exceptions end up on that call and are captured by the SDK. These messages contain the actual exception object. This allows the SDK to call into the IL2CPP backend and connect this managed exception to the native exception, allowing for server side symbolication. You can read more about the IL2CPP error integration works [here](/platforms/unity/configuration/il2cpp). From c502c4b1bbf7d2cd33017d10f29a69e2b7854bbf Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 4 Mar 2025 14:12:51 +0100 Subject: [PATCH 4/7] stack trace --- docs/platforms/unity/configuration/error-capture.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/unity/configuration/error-capture.mdx b/docs/platforms/unity/configuration/error-capture.mdx index c1576aa7fac51..2a546d014174d 100644 --- a/docs/platforms/unity/configuration/error-capture.mdx +++ b/docs/platforms/unity/configuration/error-capture.mdx @@ -10,11 +10,11 @@ The Unity SDK relies on two integrations to capture errors: `UnityLogHandlerInte The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging system. From there it receives all log messages that are logged via the `Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` methods and those log messages are added as breadcrumbs to future events. By default, the SDK will also automatically capture messages logged via `Debug.LogError` as error events and send them to Sentry. This behaviour can be disabled by unchecking the automatic capture of `Debug.LogError` on the `Enrichment` tab, or programmatically, by setting the `CaptureLogErrorEvents` option to `false` in the [configure callback](/platforms/unity/configuration/options/programmatic-configuration). -### Stacktrace Support & Line Numbers +### Stack Trace Support & Line Numbers -If [configured](https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html), Unity will include the stacktraces with the log messages as raw strings. The SDK is able to parse and display this stacktrace in the issues details. +If [configured](https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html), Unity will include the stack traces with the log messages as raw strings. The SDK is able to parse and display this stack trace in the issues details. -If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stacktrace and will be parsed by the SDK. Unfortunately, since there is no native exception at the time of logging, the SDK is not be able to provide line numbers. +If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stack trace and will be parsed by the SDK. Unfortunately, since there is no native exception at the time of logging, the SDK is not be able to provide line numbers. If you're using a version older than Unity 6, the SDK is unable to provide line numbers for events captured through `Debug.LogError`. Line numbers are not part of the logging information provided by Unity. From a505f2ab659ed1461509f4e024d3173150e7a3b9 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Tue, 4 Mar 2025 14:33:16 +0100 Subject: [PATCH 5/7] updated the place --- .../automatic-error-capture/index.mdx} | 18 +++++++++++------- docs/platforms/unity/usage/index.mdx | 12 +++++++++++- docs/platforms/unity/usage/set-level/index.mdx | 2 +- 3 files changed, 23 insertions(+), 9 deletions(-) rename docs/platforms/unity/{configuration/error-capture.mdx => usage/automatic-error-capture/index.mdx} (75%) diff --git a/docs/platforms/unity/configuration/error-capture.mdx b/docs/platforms/unity/usage/automatic-error-capture/index.mdx similarity index 75% rename from docs/platforms/unity/configuration/error-capture.mdx rename to docs/platforms/unity/usage/automatic-error-capture/index.mdx index 2a546d014174d..56c47727c4d9d 100644 --- a/docs/platforms/unity/configuration/error-capture.mdx +++ b/docs/platforms/unity/usage/automatic-error-capture/index.mdx @@ -1,10 +1,14 @@ --- -title: Error Capture -sidebar_order: 60 -description: "Learn more about how to configure your SDK to automatically send events to Sentry." +title: Automatic Error Capture +sidebar_order: 10 +description: "Learn more about how the SDK automatically captures errors and sends them to Sentry." --- -The Unity SDK relies on two integrations to capture errors: `UnityLogHandlerIntegration` and `UnityApplicationLoggingIntegration`. While they sound similar, they serve different purposes. +The Sentry SDK for Unity provides both automatic and manual error capturing capabilities. This page focuses on the **automatic error capture** through Unity's logging system integrations. For information on manually capturing errors and messages, see the [Usage documentation](/platforms/unity/usage/). + +## Automatic Error Capture + +The Unity SDK relies on two integrations to automatically capture errors: `UnityLogHandlerIntegration` and `UnityApplicationLoggingIntegration`. While they sound similar, they serve different purposes. ## UnityLogHandlerIntegration @@ -14,11 +18,11 @@ The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging syste If [configured](https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html), Unity will include the stack traces with the log messages as raw strings. The SDK is able to parse and display this stack trace in the issues details. -If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stack trace and will be parsed by the SDK. Unfortunately, since there is no native exception at the time of logging, the SDK is not be able to provide line numbers. +If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stack trace and will be parsed by the SDK. Unfortunately, since there is no native exception at the time of logging, the SDK is not be able to provide line numbers otherwise. - + If you're using a version older than Unity 6, the SDK is unable to provide line numbers for events captured through `Debug.LogError`. Line numbers are not part of the logging information provided by Unity. - + ## UnityApplicationLoggingIntegration diff --git a/docs/platforms/unity/usage/index.mdx b/docs/platforms/unity/usage/index.mdx index 59f7bda69588c..4c22d9a4b64c0 100644 --- a/docs/platforms/unity/usage/index.mdx +++ b/docs/platforms/unity/usage/index.mdx @@ -13,10 +13,14 @@ Key terms: - An _event_ is one instance of sending data to Sentry. Generally, this data is an error or exception. - An _issue_ is a grouping of similar events. - The reporting of an event is called _capturing_. - When an event is captured, it’s sent to Sentry. + When an event is captured, it's sent to Sentry. +By default, the Sentry Unity SDK automatically captures errors through Unity's logging system. For details on this automatic error capture, see the [Automatic Error Capture documentation](/platforms/unity/usage/logging-integration/). + +In addition to automatic capture, you can manually capture errors, exceptions, and messages as described below. + The most common form of capturing is to capture errors. What can be captured as an error varies by platform. In general, if you have something that looks like an exception, it can be captured. For some SDKs, you can also omit the argument to and Sentry will attempt to capture the current exception. It is also useful for manual reporting of errors or messages to Sentry. While capturing an event, you can also record the breadcrumbs that lead up to that event. Breadcrumbs are different from events: they will not create an event in Sentry, but will be buffered until the next event is sent. Learn more about breadcrumbs in our Breadcrumbs documentation. @@ -32,3 +36,9 @@ Another common operation is to capture a bare message. A message is textual info Messages show up as issues on your issue stream, with the message as the issue name. + + + +The Unity SDK does not provide stack traces for messages. + + diff --git a/docs/platforms/unity/usage/set-level/index.mdx b/docs/platforms/unity/usage/set-level/index.mdx index b84aa4001e095..5202aec1b9961 100644 --- a/docs/platforms/unity/usage/set-level/index.mdx +++ b/docs/platforms/unity/usage/set-level/index.mdx @@ -1,7 +1,7 @@ --- title: Set the Level description: "The level - similar to logging levels - is generally added by default based on the integration. You can also override it within an event." -sidebar_order: 5 +sidebar_order: 20 --- The level - similar to logging levels - is generally added by default based on the integration. You can also override it within an event. From 4e32aa423077d13c33eccaa489ad0cfb14c08bb8 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Thu, 24 Apr 2025 19:34:12 +0200 Subject: [PATCH 6/7] review comments --- .../unity/configuration/options/index.mdx | 33 ++----------------- .../usage/automatic-error-capture/index.mdx | 8 ++--- docs/platforms/unity/usage/index.mdx | 2 +- 3 files changed, 8 insertions(+), 35 deletions(-) diff --git a/docs/platforms/unity/configuration/options/index.mdx b/docs/platforms/unity/configuration/options/index.mdx index c81a5f64b7876..5c50c888563f3 100644 --- a/docs/platforms/unity/configuration/options/index.mdx +++ b/docs/platforms/unity/configuration/options/index.mdx @@ -32,7 +32,7 @@ By default, the SDK reports `editor` when running inside the Unity Editor. Other -Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it, guaranteeing that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. +Sets the release. The SDKk will try to automatically configure a release out of the box. 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 sandbox. By default the SDK will read from `Application.productName` and `Application.version` to create the release in the format `$"{Application.productName}@{Application.version}".` @@ -64,7 +64,7 @@ For app models that don't have a console to print to, you can @@ -96,22 +96,6 @@ Grouping in Sentry is different for events with stack traces and without. As a r - - -- Original - Default .NET stack trace format. -- Enhanced - Include `async`, return type, arguments, and more. - -Before version 3.0.0 of the Sentry SDK for .NET, there was no special treatment for the stack trace. Sentry reported what .NET made available at runtime. -This behavior now called `StackTraceMode.Original`. With the introduction of 3.0, the new default mode is `Enhanced`. - - - -Changing this value will affect issue grouping since the frame significantly changes shape. - - - - - Takes a screenshot of the application when an error happens and includes it as an attachment. @@ -145,16 +129,7 @@ Once enabled, this feature automatically captures HTTP client errors, like bad r -Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. - -Example scenarios where it should be explicitly set to true: - -- Universal Windows platform (UWP) applications -- WinForms applications -- Windows Presentation Foundation (WPF) applications -- Single user console applications - -Defaults to `false`, unless in Blazor WASM, MAUI, Unity, or Xamarin where the default is `true`. +Defaults to `true`. Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. @@ -186,8 +161,6 @@ If you enable this option, be sure to manually remove what you don't want to sen This option can be used to supply a server name. When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server. -For ASP.NET and ASP.NET Core applications, the value will default to the server's name. For other application types, the value will default to the computer's name only when the `SendDefaultPii` is set to `true`, because the computer's name can be considered personally identifiable information (PII) in the case of a desktop or mobile application. - ## Hooks diff --git a/docs/platforms/unity/usage/automatic-error-capture/index.mdx b/docs/platforms/unity/usage/automatic-error-capture/index.mdx index 56c47727c4d9d..dbc498672121d 100644 --- a/docs/platforms/unity/usage/automatic-error-capture/index.mdx +++ b/docs/platforms/unity/usage/automatic-error-capture/index.mdx @@ -12,16 +12,16 @@ The Unity SDK relies on two integrations to automatically capture errors: `Unity ## UnityLogHandlerIntegration -The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging system. From there it receives all log messages that are logged via the `Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` methods and those log messages are added as breadcrumbs to future events. By default, the SDK will also automatically capture messages logged via `Debug.LogError` as error events and send them to Sentry. This behaviour can be disabled by unchecking the automatic capture of `Debug.LogError` on the `Enrichment` tab, or programmatically, by setting the `CaptureLogErrorEvents` option to `false` in the [configure callback](/platforms/unity/configuration/options/programmatic-configuration). +The SDK uses the `UnityLogHandlerIntegration` to hook into Unity's logging system. From there it receives all log messages that are logged via the `Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` methods. By default, the SDK adds these log messages as breadcrumbs to future events. The SDK will also automatically capture messages logged via `Debug.LogError` as error events and send them to Sentry. This behaviour can be disabled by unchecking the automatic capture of `Debug.LogError` on the `Logging` tab in the editor (Tools->Sentry), or programmatically, by setting the `CaptureLogErrorEvents` option to `false` in the [configure callback](/platforms/unity/configuration/options/programmatic-configuration). ### Stack Trace Support & Line Numbers -If [configured](https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html), Unity will include the stack traces with the log messages as raw strings. The SDK is able to parse and display this stack trace in the issues details. +If [configured](https://docs.unity3d.com/6000.0/Documentation/Manual/stack-trace.html), Unity will include the stack traces with the log messages as raw strings. The SDK is able to parse and display this stack trace in the issue details page. -If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stack trace and will be parsed by the SDK. Unfortunately, since there is no native exception at the time of logging, the SDK is not be able to provide line numbers otherwise. +If you're using Unity 6 or newer, you have the option to to enable the source code line numbers in the [player settings](https://docs.unity3d.com/6000.0/Documentation/Manual/il2cpp-managed-stack-traces.html). These line numbers are then part of the stringified stack trace and will be parsed by the SDK. -If you're using a version older than Unity 6, the SDK is unable to provide line numbers for events captured through `Debug.LogError`. Line numbers are not part of the logging information provided by Unity. +Known Limitation: In versions older than Unity 6, the SDK is unable to provide line numbers for events captured through `Debug.LogError`. The SDK has only the strigified stack trace provided by Unity to work with and since there is no native exception available at the time of logging, Sentry can't symbolicate the stack trace on the server side either. ## UnityApplicationLoggingIntegration diff --git a/docs/platforms/unity/usage/index.mdx b/docs/platforms/unity/usage/index.mdx index 4c22d9a4b64c0..3b4c671d81aa0 100644 --- a/docs/platforms/unity/usage/index.mdx +++ b/docs/platforms/unity/usage/index.mdx @@ -39,6 +39,6 @@ Messages show up as issues on your issue stream, with the message as the issue n -The Unity SDK does not provide stack traces for messages. +By default, the SDK only provides a stack trace for captured exceptions. To provide a stack trace in message events, captured either through `SentrySdk.CaptureMessage` or `Debug.LogError`, you need to set `AttachStacktrace` to `true` in the `Logging` tab in the editor (Tools->Sentry). From 197a1ae77fd42acaa51ff4ef5562fe1948c3c869 Mon Sep 17 00:00:00 2001 From: bitsandfoxes Date: Fri, 25 Apr 2025 12:22:35 +0200 Subject: [PATCH 7/7] fixed 404 --- docs/platforms/unity/usage/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/unity/usage/index.mdx b/docs/platforms/unity/usage/index.mdx index 3b4c671d81aa0..42009ac234ae0 100644 --- a/docs/platforms/unity/usage/index.mdx +++ b/docs/platforms/unity/usage/index.mdx @@ -17,7 +17,7 @@ Key terms: -By default, the Sentry Unity SDK automatically captures errors through Unity's logging system. For details on this automatic error capture, see the [Automatic Error Capture documentation](/platforms/unity/usage/logging-integration/). +By default, the Sentry Unity SDK automatically captures errors through Unity's logging system. For details on this automatic error capture, see the [Automatic Error Capture documentation](/platforms/unity/usage/automatic-error-capture/). In addition to automatic capture, you can manually capture errors, exceptions, and messages as described below.