---
title: "Logs"
description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry."
url: https://docs.sentry.io/platforms/unity/logs/
---

# Set Up Logs | Sentry for Unity

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](https://docs.sentry.io/platforms/unity/logs.md#requirements)

Logs for Unity are supported in Sentry SDK version `4.0.0` and above.

## [Setup](https://docs.sentry.io/platforms/unity/logs.md#setup)

To enable logging in your Unity game, you need to configure the Sentry SDK with structured logging enabled.

### [Project Settings Configuration](https://docs.sentry.io/platforms/unity/logs.md#project-settings-configuration)

1. Inside the editor open: **Tools > Sentry > Logging**
2. Check the **Enable Structured Logging** option

### [Programmatic Configuration](https://docs.sentry.io/platforms/unity/logs.md#programmatic-configuration)

Alternatively, you can enable logging programmatically through the [configure callback](https://docs.sentry.io/platforms/unity/configuration/options/programmatic-configuration.md):

```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](https://docs.sentry.io/platforms/unity/logs.md#advanced-configuration-options)

In addition to enabling Structured Logging you can control the log capture behaviour through some additional options.

#### [Automatic Unity Log Forwarding](https://docs.sentry.io/platforms/unity/logs.md#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](https://docs.sentry.io/platforms/unity/logs.md#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.

## [Usage](https://docs.sentry.io/platforms/unity/logs.md#usage)

Once the feature is enabled and the SDK is initialized, you can manually send logs using the `SentrySdk.Logger` API.

### [Manual Logging](https://docs.sentry.io/platforms/unity/logs.md#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](https://docs.sentry.io/platforms/unity/logs.md#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)

With **Structured Logs** enabled additional breadcrumb attachment to events needs to be explicitly enabled with `AddBreadcrumbsWithStructuredLogs = true`.

## [Capture with Attributes](https://docs.sentry.io/platforms/unity/logs.md#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()`.

## [Options](https://docs.sentry.io/platforms/unity/logs.md#options)

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    |

## [Default Attributes](https://docs.sentry.io/platforms/unity/logs.md#default-attributes)

The Sentry SDK for Unity automatically sets several default attributes on all log entries to provide context and improve debugging:

### [Core Attributes](https://docs.sentry.io/platforms/unity/logs.md#core-attributes)

* `environment`: The environment set in the SDK if defined. This is sent from the SDK as `sentry.environment`.
* `release`: The release set in the SDK if defined. This is sent from the SDK as `sentry.release`.
* `sdk.name`: The name of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.name`.
* `sdk.version`: The version of the SDK that sent the log. This is sent from the SDK as `sentry.sdk.version`.

### [Message Template Attributes](https://docs.sentry.io/platforms/unity/logs.md#message-template-attributes)

If the log was parameterized, Sentry adds the message template and parameters as log attributes.

* `message.template`: The parameterized template string. This is sent from the SDK as `sentry.message.template`.
* `message.parameter.X`: The parameters to fill the template string. X can either be the number that represent the parameter's position in the template string (`sentry.message.parameter.0`, `sentry.message.parameter.1`, etc) or the parameter's name (`sentry.message.parameter.item_id`, `sentry.message.parameter.user_id`, etc). This is sent from the SDK as `sentry.message.parameter.X`.

### [Server Attributes](https://docs.sentry.io/platforms/unity/logs.md#server-attributes)

* `server.address`: The address of the server that sent the log. Equivalent to `server_name` that gets attached to Sentry errors.

### [User Attributes](https://docs.sentry.io/platforms/unity/logs.md#user-attributes)

If user information is available in the current scope, the following attributes are added to the log:

* `user.id`: The user ID.
* `user.name`: The username.
* `user.email`: The email address.

### [Integration Attributes](https://docs.sentry.io/platforms/unity/logs.md#integration-attributes)

If a log is generated by an SDK integration, the SDK will set additional attributes to help you identify the source of the log.

* `origin`: The origin of the log. This is sent from the SDK as `sentry.origin`.

## [Performance Considerations](https://docs.sentry.io/platforms/unity/logs.md#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