diff --git a/docs/platforms/unity/configuration/options/index.mdx b/docs/platforms/unity/configuration/options/index.mdx index 80b3edf5fde7c..5c50c888563f3 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. 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. -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. +## Data Enrichment & Attachments -By default the SDK will read from `Application.productName` and `Application.version` to create the release in the format `$"{Application.productName}@{Application.version}".` - - - - + -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 game ("in application") from stack frames that come from other packages such as the standard library, third party plugins, or other dependencies. The game's code that is part of the 'Assembly-CSharp' 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. - + -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. +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. + +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. 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. @@ -136,68 +96,70 @@ 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. +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. - + -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. + - +The quality of the attached screenshot. It can be set to `full`, `high`, `medium` or `low`. -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/). + - +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`. - + -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. +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. - - -A list of string prefixes of module names that belong to the app. This option takes precedence over `in-app-exclude`. + -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. + -This option can be overridden using . +Defaults to `true`. Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. - + -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. @@ -243,7 +205,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 +215,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 +254,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/docs/platforms/unity/usage/automatic-error-capture/index.mdx b/docs/platforms/unity/usage/automatic-error-capture/index.mdx new file mode 100644 index 0000000000000..dbc498672121d --- /dev/null +++ b/docs/platforms/unity/usage/automatic-error-capture/index.mdx @@ -0,0 +1,29 @@ +--- +title: Automatic Error Capture +sidebar_order: 10 +description: "Learn more about how the SDK automatically captures errors and sends them to Sentry." +--- + +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 + +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 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. + + +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 + +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). diff --git a/docs/platforms/unity/usage/index.mdx b/docs/platforms/unity/usage/index.mdx index 59f7bda69588c..42009ac234ae0 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/automatic-error-capture/). + +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. + + + +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). + + 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. 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