Set Up Logs

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

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

Setup

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:

public override void Configure(SentryUnityOptions options)
{
    options.EnableLogs = true;
}

or if you're manually initializing the SDK:

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:

// 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:

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

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.

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:

// 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)

Capture with Attributes

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

The following configuration options are available for Sentry Logs in Unity:

Default Attributes

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

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

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

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

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

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

• 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