feat(Unity): Structured Logging

docs/platforms/unity/index.mdx

@@ -29,6 +29,7 @@ Our Unity SDK builds on top of the [.NET SDK](/platforms/dotnet/) and extends it
 - [ViewHierarchy attachments](/platforms/unity/enriching-events/view-hierarchy/) for errors
 - [Offline Caching](/platforms/unity/configuration/options/#InitCacheFlushTimeout) stores event data to disk in case the device is not online
 - [Release Health](/platforms/unity/configuration/releases/) to keep track of crash-free users and sessions
+- [Structured Logging](/platforms/unity/logs/) to capture and send log messages with additional context
 - [Automatically adding breadcrumbs](/platforms/unity/enriching-events/breadcrumbs/#automatic-breadcrumbs) for
   - Unity's `Debug.Log` and `Debug.LogWarning`
   - Scene load, unload, active change

docs/platforms/unity/logs/index.mdx

@@ -0,0 +1,35 @@
+---
+title: Set Up Logs
+sidebar_title: Logs
+description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry."
+sidebar_order: 5600
+---
+
+With Sentry Structured Logs, you can send text-based log information from your Unity game to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.
+
+## Requirements
+
+<PlatformContent includePath="logs/requirements" />
+
+## Setup
+
+<PlatformContent includePath="logs/setup" />
+
+## Usage
+
+<PlatformContent includePath="logs/usage" />
+
+## Options
+
+<PlatformContent includePath="logs/options" />
+
+## Default Attributes
+
+<PlatformContent includePath="logs/default-attributes" />
+
+## Performance Considerations
+
+- Logs are sent asynchronously to avoid impacting game performance
+- Consider disabling Debug level logs in production to avoid excessive log volume
+- Each severity level can be individually controlled to fine-tune what gets sent to Sentry
+- Before-log handlers are executed synchronously, so keep processing lightweight

docs/product/explore/logs/getting-started/index.mdx

@@ -297,16 +297,21 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s
 
 ### Gaming
 
-- <LinkWithPlatformIcon
-    platform="unreal"
-    label="Unreal Engine"
-    url="/platforms/unreal/logs/"
-  />
 - <LinkWithPlatformIcon
     platform="godot"
     label="Godot Engine"
     url="/platforms/godot/logs/"
   />
+- <LinkWithPlatformIcon
+    platform="unity"
+    label="Unity"
+    url="/platforms/unity/logs/"
+  />
+- <LinkWithPlatformIcon
+    platform="unreal"
+    label="Unreal Engine"
+    url="/platforms/unreal/logs/"
+  />
 
 ## Upcoming SDKs
 
@@ -317,11 +322,6 @@ We're actively working on adding Log functionality to additional SDKs. Check out
     label="Elixir"
     url="https://github.com/getsentry/sentry-elixir/issues/886"
   />
-- <LinkWithPlatformIcon
-    platform="unity"
-    label="Unity"
-    url="https://github.com/getsentry/sentry-unity/issues/2172"
-  />
 
 If you don't see your platform listed above, please reach out to us on [GitHub](https://github.com/getsentry/sentry/discussions/86804) or [Discord](https://discord.gg/sentry), we'll get it prioritized!
 

platform-includes/logs/default-attributes/unity.mdx

@@ -0,0 +1,11 @@
+The Sentry SDK for Unity automatically sets several default attributes on all log entries to provide context and improve debugging:
+
+<Include name="logs/default-attributes/core" />
+
+<Include name="logs/default-attributes/message-template" />
+
+<Include name="logs/default-attributes/server" />
+
+<Include name="logs/default-attributes/user" />
+
+<Include name="logs/default-attributes/integration" />

platform-includes/logs/options/unity.mdx

@@ -0,0 +1,12 @@
+The following configuration options are available for Sentry Logs in Unity:
+
+| Option | Description | Default |
+|--------|-------------|------------|
+| **Enable Structured Logging** | Master toggle for the structured logging feature | `false` |
+| **CaptureStructuredLogsForLogType[`LogType.Log`]** | Forward `Debug.Log` calls to Sentry | `false` |
+| **CaptureStructuredLogsForLogType[`LogType.Warning`]** | Forward `Debug.Warning` calls to Sentry | `true` |
+| **CaptureStructuredLogsForLogType[`LogType.Assert`]** | Forward `Debug.Assert` calls to Sentry | `true` |
+| **CaptureStructuredLogsForLogType[`LogType.Error`]** | Forward `Debug.Error` calls to Sentry | `true` |
+| **CaptureStructuredLogsForLogType[`LogType.Exception`]** | Forward `Debug.Exception` calls to Sentry | `true` |
+| **AddBreadcrumbsWithStructuredLogs** | Send `Debug` calls BOTH as Logs and as Breadcrumbs, instead of just Logs | `false` |
+| **Before Log Callback** | Handler to modify or filter log events before sending | None |

platform-includes/logs/requirements/unity.mdx

@@ -0,0 +1 @@
+Logs for Unity are supported in Sentry SDK version `4.0.0` and above.

platform-includes/logs/setup/unity.mdx

@@ -0,0 +1,82 @@
+To enable logging in your Unity game, you need to configure the Sentry SDK with structured logging enabled.
+
+### Project Settings Configuration
+
+1. Inside the editor open: **Tools > Sentry > Logging**
+2. Check the **Enable Structured Logging** option
+
+### Programmatic Configuration
+
+Alternatively, you can enable logging programmatically through the [configure callback](/platforms/unity/configuration/options/programmatic-configuration):
+
+```csharp
+public override void Configure(SentryUnityOptions options)
+{
+    options.EnableLogs = true;
+}
+```
+
+or if you're manually initializing the SDK:
+
+```csharp
+SentrySdk.Init(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+
+    // Enable logs to be sent to Sentry
+    options.EnableLogs = true;
+});
+```
+
+### Advanced Configuration Options
+
+In addition to enabling Structured Logging you can control the log capture behaviour through some additional options.
+
+#### Automatic Unity Log Forwarding
+
+You can configure the SDK to automatically forward Unity's Debug Logs to Sentry based on the enabled log level in the configuration window, or programmatically:
+
+```csharp
+// Configure automatic log forwarding programmatically
+options.EnableLogs = true;
+
+options.CaptureStructuredLogsForLogType[LogType.Log] = false;
+options.CaptureStructuredLogsForLogType[LogType.Warning] = true;
+options.CaptureStructuredLogsForLogType[LogType.Assert] = true;
+options.CaptureStructuredLogsForLogType[LogType.Error] = true;
+options.CaptureStructuredLogsForLogType[LogType.Exception] = true;
+
+options.AddBreadcrumbsWithStructuredLogs = false; // Send as structured logs instead of breadcrumbs
+```
+
+#### Before-Log Handler
+
+To filter logs, or update them before they are sent to Sentry, you can provide a custom `BeforeSendLog` callback:
+
+```csharp
+options.SetBeforeSendLog(log =>
+{
+    if (log.Message.StartsWith("Sensitive:"))
+    {
+        return null;
+    }
+
+    // Set a custom attribute for all other logs sent to Sentry
+    log.SetAttribute("my.attribute", "value");
+
+    return log;
+});
+```
+
+The callback function set via `SetBeforeSendLog(Func<SentryLog, SentryLog?>)` receives a log object, and should return the log object if you want it to be sent to Sentry, or `null` if you want to discard it.
+
+The log object of type `SentryLog` has the following members:
+- `Timestamp` Property: (`DateTimeOffset`) The timestamp of the log.
+- `TraceId` Property: (`SentryId`) The trace id of the log.
+- `Level` Property: (`SentryLogLevel`) The severity level of the log. Either `Trace`, `Debug`, `Info`, `Warning`, `Error`, or `Fatal`.
+- `Message` Property: (`string`) The formatted log message.
+- `Template` Property: (`string?`) The parameterized template string.
+- `Parameters` Property: (`ImmutableArray<KeyValuePair<string, object>>`) The parameters to the template string.
+- `ParentSpanId` Property: (`SpanId?`) The span id of the span that was active when the log was collected.
+- `TryGetAttribute(string key, out object value)` Method: Gets the attribute value associated with the specified key. Returns `true` if the log contains an attribute with the specified key and it's value is not `null`, otherwise `false`.
+- `SetAttribute(string key, object value)` Method: Sets a key-value pair of data attached to the log. Supported types are `string`, `bool`, integers up to a size of 64-bit signed, and floating-point numbers up to a size of 64-bit.

platform-includes/logs/usage/unity.mdx

@@ -0,0 +1,56 @@
+Once the feature is enabled and the SDK is initialized, you can manually send logs using the `SentrySdk.Logger` API.
+
+### Manual Logging
+
+The `SentrySdk.Logger` instance exposes six methods that you can use to log messages at different log levels: `Trace`, `Debug`, `Info`, `Warning`, `Error`, and `Fatal`.
+
+These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
+
+```csharp
+SentrySdk.Logger.LogInfo("A simple debug log message");
+SentrySdk.Logger.LogError("A {0} log message", "formatted");
+```
+
+### Automatic Logging Integration
+
+Because Unity's `LogType` does not match `SentryLogLevel`, the SDKs logging integration maps them as follows:
+
+| Unity LogLevel | Sentry Logs UI Severity |
+| --- | --- |
+| Debug | INFO |
+| Warning | WARN |
+| Assert | ERROR |
+| Error | ERROR |
+| Fatal | FATAL |
+
+```csharp
+// Standard Unity logging - automatically captured when severity levels are enabled
+Debug.Log("Player position updated.");
+Debug.LogWarning("Low memory warning.");
+Debug.LogError("Failed to save game data.");
+```
+
+You can configure whether these logs are sent as:
+- **Structured Logs**: Full log entries with searchable attributes
+- **Breadcrumbs**: Contextual information attached to errors (useful for debugging)
+
+<Alert level="info">
+With **Structured Logs** enabled additional breadcrumb attachment to events needs to be explicitly enabled with `AddBreadcrumbsWithStructuredLogs = true`.
+</Alert>
+
+## Capture with Attributes
+
+```csharp
+SentrySdk.Logger.LogWarning(static log =>
+{
+    log.SetAttribute("my.attribute", "value");
+}, "A log message with additional attributes.");
+```
+
+Supported attribute types are:
+- Textual: `string` and `char`
+- Logical: `bool`
+- Integral: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long` and `nint`
+- Floating-point: `float` and `double`
+
+Unsupported numeric types such as `ulong`, `nuint`, `decimal`, as well as all other types including `object`, are treated as `string` via `ToString()`.