Set Up Logs

Structured logs allow you to send, view and query logs sent from your applications within Sentry.

With Sentry Structured Logs, you can send text-based log information from your Unreal Engine applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.

Logs for Unreal Engine are supported in Sentry Unreal Engine SDK version 1.2.0 and above.

To enable logging in your Unreal Engine project, you need to configure the Sentry SDK with structured logging enabled.

Open your project settings: Project Settings > Plugins > Sentry
Check the Enable Structured Logging option

Alternatively, you can enable logging programmatically when initializing the SDK:

Copied

#include "SentrySubsystem.h"

void ConfigureSentryWithLogs()
{
    USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

    // Create settings with logging enabled
    SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
    {
        Settings->EnableStructuredLogging = true;
    }));
}

You can configure the SDK to automatically forward Unreal Engine's native UE_LOG calls to Sentry based on the enabled severity levels:

Copied

USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

// Configure automatic log forwarding programmatically
SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
{
    Settings->EnableStructuredLogging = true;

    // Enable specific severity levels for UE_LOG forwarding
    Settings->EnableDebugLogs = false;
    Settings->EnableInfoLogs = true;
    Settings->EnableWarningLogs = true;
    Settings->EnableErrorLogs = true;
    Settings->EnableFatalLogs = true;

    Settings->bSendBreadcrumbsWithStructuredLogging = false; // Send as structured logs instead of breadcrumbs
}));

You can filter which log categories are sent to Sentry:

Copied

// Configure category filtering
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

// Create settings with logging enabled
SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
{
    Settings->EnableStructuredLogging = true;
    
    // Only forward logs from specific categories
    TArray<FString> AllowedCategories;
    AllowedCategories.Add(TEXT("LogGameFlow"));
    AllowedCategories.Add(TEXT("LogPlayerSystem"));
    AllowedCategories.Add(TEXT("LogSentrySdk"));
    Settings->LogCategoryFilter = AllowedCategories;

}));

To filter logs, or update them before they are sent to Sentry, you can create a custom before-log handler class.

Logging additional messages in the BeforeLog handler can cause recursive call of the handler, resulting in a stack overflow!

Copied

UCLASS()
class UCustomLogFilter : public USentryBeforeLogHandler
{
    GENERATED_BODY()
public:
    virtual USentryLogEvent* HandleBeforeLog_Implementation(USentryLogEvent* LogEvent) override
    {
        // Filter out all debug logs
        if (LogEvent->GetLevel() == ESentryLevel::Debug)
        {
            return nullptr; // Return null to prevent sending
        }

        // Filter out logs based on message content
        if (LogEvent->GetBody().Contains(TEXT("Sensitive")))
        {
            return nullptr; // Filter out sensitive logs
        }

        // Filter based on specific categories
        if (LogEvent->GetBody().Contains(TEXT("Password")) ||
            LogEvent->GetBody().Contains(TEXT("Token")))
        {
            return nullptr; // Filter out authentication-related logs
        }

        return LogEvent; // Return modified event
    }
};

// Configure settings using delegate
FConfigureSettingsDelegate SettingsDelegate;
SettingsDelegate.BindDynamic(this, &USomeClass::HandleSettingsDelegate);

void USomeClass::HandleSettingsDelegate(USentrySettings* Settings)
{
    // Enable structured logging
    Settings->EnableStructuredLogging = true;

    // Configure individual severity levels
    Settings->EnableDebugLogs = false;
    Settings->EnableInfoLogs = true;
    Settings->EnableWarningLogs = true;
    Settings->EnableErrorLogs = true;
    Settings->EnableFatalLogs = true;

    // Set custom before-log handler
    Settings->BeforeLogCallback = UCustomLogFilter::StaticClass();
}

// Initialize with settings delegate
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
SentrySubsystem->InitializeWithSettings(SettingsDelegate);

The HandleBeforeLog_Implementation method receives a USentryLog object, and should return the log event if you want it to be sent to Sentry, or nullptr if you want to discard it.

The USentryLog object has the following methods:

GetLevel(): Returns the severity level of the log (ESentryLevel)
GetBody(): Returns the formatted log message (FString)
SetLevel(ESentryLevel Level): Sets the Level of the Log Event
SetBody(FString& Body): Sets the Body of the Log Event

Once logging is enabled, you can send log messages to Sentry using the AddLog method.

Copied

#include "SentrySubsystem.h"

void SendLogs()
{
    USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();

    // Send a simple log message
    SentrySubsystem->AddLog(TEXT("User completed tutorial"), ESentryLevel::Info);

    // Send a log message with category
    SentrySubsystem->AddLog(TEXT("Failed to load texture asset"), ESentryLevel::Warning, TEXT("AssetLoading"));

    // Send an error log
    SentrySubsystem->AddLog(TEXT("Database connection failed"), ESentryLevel::Error, TEXT("Database"));
}

Sentry Logs supports the following log levels:

Unreal ESentryLevel	Sentry Logs UI Severity
Debug	DEBUG
Info	INFO
Warning	WARN
Error	ERROR
Fatal	FATAL

Copied

// Examples of different log levels
SentrySubsystem->AddLog(TEXT("Player position updated"), ESentryLevel::Debug, TEXT("Player"));
SentrySubsystem->AddLog(TEXT("Level loaded successfully"), ESentryLevel::Info, TEXT("GameFlow"));
SentrySubsystem->AddLog(TEXT("Low memory warning"), ESentryLevel::Warning, TEXT("Performance"));
SentrySubsystem->AddLog(TEXT("Failed to save game data"), ESentryLevel::Error, TEXT("SaveSystem"));
SentrySubsystem->AddLog(TEXT("Critical system failure"), ESentryLevel::Fatal, TEXT("System"));

When structured logging is enabled with the appropriate severity levels, the SDK can automatically capture Unreal Engine's native UE_LOG calls:

Copied

// Standard Unreal Engine logging - automatically captured when severity levels are enabled
UE_LOG(LogGameFlow, Warning, TEXT("Player health is critically low: %d"), PlayerHealth);
UE_LOG(LogAssets, Error, TEXT("Failed to load texture: %s"), *TexturePath);
UE_LOG(LogTemp, Log, TEXT("Debug information")); // Only sent if EnableInfoLogs = true

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)

You can also use Sentry Logs from Blueprints by calling the Add Log function:

Add a Add Log node to your Blueprint
Set the Body parameter to your log message
Choose the appropriate Level from the dropdown
Optionally set a Category for better organization

The following configuration options are available for Sentry Logs in Unreal Engine:

Option	Description	Default
Enable Structured Logging	Master toggle for the structured logging feature	`false`
Enable Debug Logs	Forward Debug level UE_LOG calls to Sentry	`false`
Enable Info Logs	Forward Info level UE_LOG calls to Sentry	`false`
Enable Warning Logs	Forward Warning level UE_LOG calls to Sentry	`true`
Enable Error Logs	Forward Error level UE_LOG calls to Sentry	`true`
Enable Fatal Logs	Forward Fatal level UE_LOG calls to Sentry	`true`
Send Logs As Breadcrumbs	Send UE_LOG calls BOTH as Logs and as Breadcrumbs, instead of just Logs	`false`
Log Category Filter	Array of log categories to include (empty = all categories)	Empty
Before Log Callback	Handler to modify or filter log events before sending	None

The Unreal Engine SDK automatically sets several default attributes on all log entries to provide context and improve debugging:

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.
trace.parent_span_id: The span ID of the span that was active when the log was collected (only set if there was an active span). This is sent from the SDK as sentry.trace.parent_span_id.
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.

user.id: The user ID. Maps to id in the User payload, which is set by default by the SDKs.

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

user.name: The username. Maps to username in the User payload.
user.email: The email address. Maps to email in the User payload.

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
Use categories to organize logs and make them easier to search and filter
Before-log handlers are executed synchronously, so keep processing lightweight

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support