diff --git a/docs/platforms/unity/configuration/filtering.mdx b/docs/platforms/unity/configuration/filtering.mdx index 06b922a4b6884..fa011738e01fa 100644 --- a/docs/platforms/unity/configuration/filtering.mdx +++ b/docs/platforms/unity/configuration/filtering.mdx @@ -20,6 +20,12 @@ All Sentry SDKs support the callback + + +The callback runs in C# only. Native crashes are captured by the native SDKs and don't run it. + + + Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/issues/issue-details/breadcrumbs/). ## Filtering Transaction Events diff --git a/docs/platforms/unity/data-management/data-collected.mdx b/docs/platforms/unity/data-management/data-collected.mdx index 8d209e8d7bbce..6dec5530aa7a5 100644 --- a/docs/platforms/unity/data-management/data-collected.mdx +++ b/docs/platforms/unity/data-management/data-collected.mdx @@ -6,79 +6,75 @@ sidebar_order: 1 Sentry takes data privacy very seriously and has default settings in place that prioritize data safety, especially when it comes to personally identifiable information (PII) data. When you add the Sentry SDK to your application, you allow it to collect data and send it to Sentry during the runtime of your application. -The category types and amount of data collected vary, depending on the integrations you've enabled in the Sentry SDK. Here's a list of data categories the Sentry .NET SDK collects: +The data the Sentry Unity SDK collects depends on the options and integrations you enable. Here's a list of data categories it collects: -## HTTP Headers +## Information About the User -By default, the Sentry SDK sends HTTP headers to Sentry but redacts any headers that may contain sensitive data. (See the [list of headers](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/Internal/RedactedHeaders.cs#L7) that are redacted). +The SDK always sends an installation ID as `user.id`. By default, it's a random ID that the SDK stores in a file on the device. On platforms where the SDK can't write files, such as UWP and visionOS, it uses the MAC address of the network adapter or a hash of the machine name instead. On iOS, Android, Nintendo Switch, and macOS with the Cocoa backend, it's the native SDK's installation ID, so C# events and native crashes share the same user. -## Cookies +With Unity as a Library, the game's events carry the user that the host app sets. -By default, the Sentry SDK doesn't send cookies. +To send your own user information, [identify the user](../../enriching-events/identify-user/). -If you want to send cookies, set the option `SendDefaultPii = true` when initializing the Sentry SDK. +## Data Sent With SendDefaultPii -A [data scrubber](/platforms/dotnet/data-management/sensitive-data/) can be used to filter information before sending data to Sentry. +If `SendDefaultPii` is set to `true`, the SDK also sends: -Any [sensitive cookies](https://github.com/getsentry/relay/blob/249971e1702991c64cf0f7f89773fb019ffb4a95/relay-pii/src/convert.rs#L235-L263) that the SDK does send will be stripped by Relay before Sentry stores these. +- The user's IP address. The SDK sets it to `{{auto}}`, and Sentry fills in the IP address the event came from. +- The device unique identifier (`SystemInfo.deviceUniqueIdentifier`). +- The device's name as `device.name`. On desktop, this is the computer name. Native crashes on Windows, Linux, macOS with the Native backend, and game consoles include it only with this option too. Native crashes on Android, iOS, and macOS with the Cocoa backend don't include a device name. +- The operating system's user name as `user.username`, if **Auto Set UserName** (`IsEnvironmentUser`) is also enabled. Learn more in [Options](/platforms/unity/configuration/options/#IsEnvironmentUser). -## Information About Logged-in User +Error events don't include a server name. -By default, the Sentry SDK doesn't send any information about the logged-in user, such as email address, user ID, or username. Even if enabled, the type of logged-in user information you'll be able to send depends on the integrations you enable in Sentry's SDK. Most integrations won't send any user information. Some will only set the user ID, but there are a few that will set the user ID, username, and email address. +You can [prevent Sentry from storing IP Addresses](../../enriching-events/identify-user/#ip_address) either by configuring this in the ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/) settings of your Sentry project or using [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). -To start sending logged-in user information, set the option `SendDefaultPii = true` when initializing the Sentry SDK. +## Failed HTTP Requests -## Users' IP Address +On iOS and macOS with the Cocoa backend, the Cocoa SDK captures failed `NSURLSession` requests as native events, with the URL, query string, method, and sanitized headers. These events don't run the C# callbacks. To turn this off, set [`CaptureFailedRequests`](/platforms/unity/configuration/options/#CaptureFailedRequests) to `false`. -By default, the Sentry SDK doesn't send the user's IP address. +In C#, the SDK only records HTTP requests sent through `SentryHttpMessageHandler`. For these, it adds `http` breadcrumbs with the URL, and captures failed requests as events with the URL and query string. If `SendDefaultPii` is set to `true`, these events also include the full URL, the headers, and the cookies. -To enable sending the user's IP address, set the option `SendDefaultPii = true` when initializing the Sentry SDK. - -Even if enabled, whether you're able to send the user's IP address or not, will depend on the integrations you enable in Sentry's SDK. Most integrations won't set the user's IP address at all. - -You can [prevent Sentry from storing IP Addresses](/platforms/native/enriching-events/identify-user/#ip_address) either by configuring this in the ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/) settings of your Sentry project or using [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). - -## Request URL - -By default, the [HttpRequestUrl](https://learn.microsoft.com/en-us/dotnet/api/System.UriComponents) of outgoing and incoming HTTP requests is **always sent to Sentry**. This includes the Scheme, Host, Port, LocalPath, and Query data. - -If `SendDefaultPii` is set to `true` then the [AbsoluteUri](https://learn.microsoft.com/en-us/dotnet/api/System.UriComponents) of outgoing and incoming HTTP requests will be sent to Sentry (including the Scheme, UserInfo, Host, Port, LocalPath, Query, and Fragment data). - -Depending on your application, this could contain PII data. - -## Request Query String - -The full request query string of outgoing and incoming HTTP requests is **always sent to Sentry**. Depending on your application, this could contain PII data. +## General Device Information -## SQL Queries +The SDK collects information about the app, the operating system, the device, the GPU, the runtime, and Unity, and sends it with every event: -While SQL queries are sent to Sentry, neither the full SQL query (`SELECT * FROM users WHERE email = 'joe@shmoe.com'`), nor the values of its parameters will ever be sent. A parameterized version of the query (`SELECT * FROM users WHERE email = @email`) is sent instead. +- `app`: the product name, the start time, and whether it's a debug or release build. +- `os`: the operating system description. On Xbox and PlayStation, it's the name of the console. +- `device`: the processor count, CPU, time zone, vibration support, device type, model, and system memory. In the Unity Editor, the device is marked as a simulator. +- `gpu`: the GPU's ID, name, vendor name and ID, memory, graphics API and version, maximum texture size, shader level, multithreaded rendering, and support for non-power-of-two textures, instancing, ray tracing, and compute and geometry shaders. +- `unity`: the Editor version, install mode, target frame rate, copy texture support, and rendering threading mode. +- `runtime`: the .NET runtime the game runs on. +- The current culture and UI culture, and the thread pool's thread counts. -## Device Unique Identifier +For events captured on the main thread, the SDK also adds: -The Sentry SDK does not set the `Device Unique Identifier` by default. +- The app's allocated memory (`app.memory`). +- The battery status and level, and the device orientation. +- The connection type, on iOS and Android. +- The name of the active scene, in the Unity Editor and in IL2CPP builds. -If `SendDefaultPii` is set to `true` then the SDK will capture `SystemInfo.deviceUniqueIdentifier` automatically and send this with any event. +Every event also records whether it was captured on the main thread (`unity.is_main_thread`). -## Machine Name +## Breadcrumbs -The Sentry SDK does not send the machine name by default. +The SDK records Unity log messages, scene changes, and app lifecycle events as breadcrumbs, and sends them with events. Log messages can contain PII, depending on what your game logs. Learn more in [Breadcrumbs](../../enriching-events/breadcrumbs/). -If you assign a value to the `ServerName` in the Sentry options then Sentry SDK will send this with any events. +## Logs -Otherwise, if `SendDefaultPii` is set to true then the Sentry SDK will capture the `Environment.MachineName` automatically and send this with any events. +Unity log messages that the SDK forwards to Sentry Logs can contain PII, depending on what your game logs. Each log carries the user from the scope as attributes. If `SendDefaultPii` is set to `true`, each log also carries the machine name as `server.address`. Learn more in [Logs](/platforms/unity/logs/). -## General Device Information +## Screenshots and View Hierarchy -The Sentry SDK collects information about the device, such as the version and build of your operating system, CPU and GPU details etc. This information is sent to Sentry by default. +Screenshots and the view hierarchy are opt-in. Both can contain PII, such as names shown on screen or in the names of GameObjects. Learn more in [Screenshots](../../enriching-events/screenshots/) and [View Hierarchy](../../enriching-events/view-hierarchy/). ## Data captured by Mobile SDKs -On mobile platforms, the Sentry SDK for .NET can also capture data indirectly via the Android and iOS SDKs. You should refer to the documentation for those SDKs for more information on what data is captured. +On mobile platforms, the Sentry SDK for Unity can also capture data through the Android and iOS SDKs. Refer to the documentation for those SDKs for more information on what data they capture. - [Android](/platforms/android/data-management/data-collected/) - [iOS](/platforms/apple/data-management/data-collected/) ## Data captured by the Native SDK -When compiling for Windows, Linux or other platforms that use Sentry Native, you should refer to [data captured by the Native SDK](/platforms/native/data-management/data-collected/) to understand what data is sent with those events. +When compiling for Windows, Linux or other platforms that use Sentry Native, refer to [data captured by the Native SDK](/platforms/native/data-management/data-collected/) to understand what data is sent with those events. diff --git a/docs/platforms/unity/data-management/sensitive-data/index.mdx b/docs/platforms/unity/data-management/sensitive-data/index.mdx index 393cd2b10e6e2..e9574447d29a6 100644 --- a/docs/platforms/unity/data-management/sensitive-data/index.mdx +++ b/docs/platforms/unity/data-management/sensitive-data/index.mdx @@ -23,6 +23,23 @@ We offer the following options depending on your legal and operational needs: - [configuring server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) to ensure Sentry does _not store_ data. Configuration changes are done in the Sentry UI and apply immediately for new events. - [running a local Relay](/product/relay/) on your own server between the SDK and Sentry, so that data is _not sent to_ Sentry while configuration can still be applied without deploying. +## Scrubbing Data in the SDK + +To remove sensitive data before it leaves the device, use these callbacks: + +- [`SetBeforeSend`](/platforms/unity/configuration/options/#SetBeforeSend): edit or drop error events. +- [`SetBeforeBreadcrumb`](/platforms/unity/configuration/options/#SetBeforeBreadcrumb): edit or drop breadcrumbs. +- [`SetBeforeSendTransaction`](/platforms/unity/configuration/options/#SetBeforeSendTransaction): edit or drop transactions. +- `SetBeforeSendLog`: edit or drop logs. Learn more in [Logs](/platforms/unity/logs/#before-log-handler). +- [`SetBeforeCaptureScreenshot`](/platforms/unity/configuration/options/#SetBeforeCaptureScreenshot) and [`SetBeforeSendScreenshot`](/platforms/unity/configuration/options/#SetBeforeSendScreenshot): skip, edit, or drop screenshots. +- [`SetBeforeCaptureViewHierarchy`](/platforms/unity/configuration/options/#SetBeforeCaptureViewHierarchy) and [`SetBeforeSendViewHierarchy`](/platforms/unity/configuration/options/#SetBeforeSendViewHierarchy): skip, edit, or drop the view hierarchy. + + + +These callbacks run in C# only. Native crashes, from C and C++, Java and Kotlin, or Objective-C and Swift code, are captured by the native SDKs and don't run them. Breadcrumbs reach the native SDKs after `SetBeforeBreadcrumb` runs, so breadcrumbs you edit or drop there stay that way in native crashes. To remove other data from native crashes, use [server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/). On iOS, setting `SetBeforeCaptureScreenshot` or `SetBeforeSendScreenshot` turns off screenshots for native crashes. On Windows, native crashes get a screenshot whenever `AttachScreenshot` is on. Learn more in [Screenshots](/platforms/unity/enriching-events/screenshots/#native-errors). + + + Ensure that your team is aware of your company's policy around what can and cannot be sent to Sentry. We recommend determining this policy early in your implementation and communicating it as well as enforcing it via code review. diff --git a/docs/platforms/unity/enriching-events/context/index.mdx b/docs/platforms/unity/enriching-events/context/index.mdx index fa54f28d3fe42..34146673896c4 100644 --- a/docs/platforms/unity/enriching-events/context/index.mdx +++ b/docs/platforms/unity/enriching-events/context/index.mdx @@ -31,6 +31,8 @@ Custom contexts are only added to C# events. Native crashes don't include them. There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. +The SDK sets its own contexts, such as `app`, `os`, `device`, `gpu`, `runtime`, and `unity`. Don't use these names for your own contexts. Setting your own context under one of them replaces the SDK's context. For `app`, `device`, and `unity`, it also stops the SDK from adding its main-thread data, the active scene, and default tags to events. See the [list of data in these contexts](../../data-management/data-collected/#general-device-information). + Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts/). ## Size Limitations diff --git a/docs/platforms/unity/enriching-events/scopes/index.mdx b/docs/platforms/unity/enriching-events/scopes/index.mdx index c70db4f1f633c..5cdcab5fd46c3 100644 --- a/docs/platforms/unity/enriching-events/scopes/index.mdx +++ b/docs/platforms/unity/enriching-events/scopes/index.mdx @@ -1,44 +1,15 @@ --- -title: Scopes and Hubs -description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage." +title: Scopes +description: "Learn what the scope is in the Sentry Unity SDK, and how to attach data to all events or to a single event." --- -When an event is captured and sent to Sentry, SDKs will merge that event data with extra -information from the current scope. SDKs will typically automatically manage the scopes -for you in the framework integrations and you don't need to think about them. However, -you should know what a scope is and how you can use it for your advantage. +When an event is captured and sent to Sentry, the SDK merges that event with the data stored on the scope, such as [tags](../tags/), [contexts](../context/), [breadcrumbs](../breadcrumbs/), and the [user](../identify-user/). -## What's a Scope, What's a Hub +## How the Scope Works -You can think of the hub as the central point that our SDKs use to route an -event to Sentry. When you call `init()` a hub is created and a client and a -blank scope are created on it. That hub is then associated with the current -thread and will internally hold a stack of scopes. +Unity runs in global mode, with one scope shared by every thread. Data you set on the scope stays there and is added to every event until you change or clear it. `PushScope` has no effect. -The scope will hold useful information that should be sent along with the -event. For instance [contexts](../context/) or -[breadcrumbs](../breadcrumbs/) are stored on -the scope. When a scope is pushed, it inherits all data from the parent scope -and when it pops all modifications are reverted. - -The default SDK integrations will push and pop scopes intelligently. For -instance web framework integrations will create and destroy scopes around your -routes or controllers. - -## How the Scope and Hub Work - -As you start using an SDK, a scope and hub are automatically created for you out -of the box. It's unlikely that you'll interact with the hub directly unless you're -writing an integration or you want to create or destroy scopes. Scopes, on the -other hand are more user facing. You can call at any point in -time to modify data stored on the scope. This is useful for doing things like -[modifying the context](../context/). - - - -When you call a global function such as internally Sentry -discovers the current hub and asks it to capture an event. Internally the hub will -then merge the event with the topmost scope's data. +Native crashes include most of this data too. Learn more in Scope Sync. ## Configuring the Scope @@ -52,14 +23,7 @@ You can also apply this configuration when unsetting a user at logout: -To learn what useful information can be associated with scopes see -[the context documentation](../context/). - -## Local Scopes - -We also support pushing and configuring a scope within a single call. This is typically -called , or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if -you only want to send data for one specific event. +## Attaching Data to a Single Event ### Using Scope Callback Parameter diff --git a/docs/platforms/unity/enriching-events/screenshots/index.mdx b/docs/platforms/unity/enriching-events/screenshots/index.mdx index 514fba3fadf24..098976b892ea7 100644 --- a/docs/platforms/unity/enriching-events/screenshots/index.mdx +++ b/docs/platforms/unity/enriching-events/screenshots/index.mdx @@ -16,9 +16,9 @@ Because screenshots may contain attachment. -This feature only applies to SDKs with a user interface, such as the ones for mobile and desktop applications. Capturing the scene and creating the view hierarchy requires the UI thread and in the event of a crash, that might not be available. Another example where the view hierarchy might not be available is when the event happens before the screen starts to load. So inherently, this feature is a best effort solution. +The SDK captures the view hierarchy of the active scene only, and only for events captured on the main thread. Events captured on background threads and native crashes don't get one. It works in the Unity Editor and on WebGL too. ## Enabling View Hierarchy Attachments @@ -17,29 +17,29 @@ View hierarchy debugging is an opt-in feature. You can enable attaching the view ![Options Screenshot Configuration](./img/editor-window.png) -Or, like so, if you're [configuring things programmatically](/platforms/unity/configuration/options/): +Or, like so, if you're [configuring things programmatically](/platforms/unity/configuration/options/programmatic-configuration/): -```csharp {tabTitle:ScriptableOptionsConfiguration} +```csharp options.AttachViewHierarchy = true; ``` -### Customize View Hierarchy Capturing +## Customize View Hierarchy Capturing Because capturing view hierarchy can be a resource-intensive operation as the SDK traverses the scene at the time of an error, there are several controls available to you. - + Allows you to limit the amount of gameobjects to be traversed and included in the view hierarchy. - + Allows you to limit the maximum depth of child-gameobject the SDK will attempt to traverse to include in the view hierarchy. - + Allows you to limit the maximum count of child-gameobjects per individual gameobject the SDK will attempt to include in the view hierarchy. @@ -53,6 +53,33 @@ options.MaxViewHierarchyRootObjects = 100; options.MaxViewHierarchyObjectChildCount = 20; ``` +To decide whether an event gets a view hierarchy, use . Return `false` to skip it: + +```csharp +options.SetBeforeCaptureViewHierarchy(sentryEvent => +{ + // Don't capture the view hierarchy for warnings + return sentryEvent.Level != SentryLevel.Warning; +}); +``` + +## Modifying or Discarding the View Hierarchy + +To edit the view hierarchy before it's sent, or to discard it, use . Return `null` to discard it: + +```csharp +options.SetBeforeSendViewHierarchy((viewHierarchy, sentryEvent) => +{ + // The root node is the scene, and its children are the root GameObjects + foreach (var scene in viewHierarchy.Windows) + { + scene.Children.RemoveAll(node => node.Type == "AccountScreen"); + } + + return viewHierarchy; +}); +``` + ## Viewing View Hierarchy Attachments View hierarchies appear in the "Attachments" tab, where you can view all attachments, as well as associated events. Click the event ID to open the [Issue Details](/product/issues/issue-details/) page of that specific event. @@ -61,12 +88,12 @@ View hierarchies appear in the "Attachments" tab, where you can view all attachm On the **Issue Details** page, you can interact with the view hierarchy attachment in a section called "View Hierarchy". This section represents the state of your scene at the time of an error event. There are two displays: a tree view, and detailed view for a selected node. You can select nodes in the tree to view the properties collected by the SDK. The SDK will report on the following keys for each node in the view: -- `Tag` The gameobject's tag -- `Position` The gameobject's position -- `Rotation` The gameobject's rotation in euler angles -- `Scale` The gameobject's scale -- `Active` Whether the gameobject was active -- `Extra` A list of names of all the attached MonoBehaviours on that gameobject +- `tag` The gameobject's tag +- `position` The gameobject's position +- `rotation` The gameobject's rotation in euler angles +- `scale` The gameobject's local scale +- `active` Whether the gameobject itself was active (`activeSelf`) +- `extras` The type names of all components attached to the gameobject This feature can be used as an exploratory tool to debug reference issues, or gain a better understanding of the relationship between gameobjects. diff --git a/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx b/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx index aad876bd72c0b..4c44214d11f39 100644 --- a/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx +++ b/docs/platforms/unity/usage/sdk-fingerprinting/index.mdx @@ -13,6 +13,12 @@ By default, Sentry will run one of our built-in grouping algorithms to generate In supported SDKs, you can override Sentry's default grouping that passes the fingerprint attribute as an array of strings. The length of a fingerprint's array is not restricted. This works similarly to the [fingerprint rules functionality](/concepts/data-management/event-grouping/fingerprint-rules/), which is always available and can achieve similar results. + + +Fingerprints you set in the SDK only apply to events captured in C#. Native crashes keep the default grouping. To group them, use [Fingerprint Rules](/concepts/data-management/event-grouping/fingerprint-rules/). + + + ## Basic Example In the most basic case, values are passed directly: diff --git a/platform-includes/set-fingerprint/basic/unity.mdx b/platform-includes/set-fingerprint/basic/unity.mdx new file mode 100644 index 0000000000000..90231258145cb --- /dev/null +++ b/platform-includes/set-fingerprint/basic/unity.mdx @@ -0,0 +1,13 @@ +```csharp +// Add this to the SDK initialization callback +options.SetBeforeSend(@event => +{ + // SaveFileCorruptedException is an exception defined by your game + if (@event.Exception is SaveFileCorruptedException) + { + @event.SetFingerprint(new[] { "save-file-corrupted" }); + } + + return @event; +}); +``` diff --git a/platform-includes/set-fingerprint/database-connection/unity.mdx b/platform-includes/set-fingerprint/database-connection/unity.mdx new file mode 100644 index 0000000000000..efe513da58045 --- /dev/null +++ b/platform-includes/set-fingerprint/database-connection/unity.mdx @@ -0,0 +1,13 @@ +```csharp +// Add this to the SDK initialization callback +options.SetBeforeSend(@event => +{ + // BackendConnectionException is an exception defined by your game + if (@event.Exception is BackendConnectionException) + { + @event.SetFingerprint(new[] { "backend-connection-error" }); + } + + return @event; +}); +``` diff --git a/platform-includes/set-fingerprint/rpc/unity.mdx b/platform-includes/set-fingerprint/rpc/unity.mdx new file mode 100644 index 0000000000000..628d077c2d0b7 --- /dev/null +++ b/platform-includes/set-fingerprint/rpc/unity.mdx @@ -0,0 +1,31 @@ +```csharp +using System; +using System.Net; + +public class MyRpcException : Exception +{ + // The name of the RPC function that was called (e.g. "getPlayerInventory") + public string Function { get; set; } + + // For example a HTTP status code returned by the server. + public HttpStatusCode Code { get; set; } +} + +// Add this to the SDK initialization callback +options.SetBeforeSend(@event => +{ + if (@event.Exception is MyRpcException ex) + { + @event.SetFingerprint( + new[] + { + "{{ default }}", + ex.Function, + ex.Code.ToString(), + } + ); + } + + return @event; +}); +```