diff --git a/docs/platforms/unreal/logs/index.mdx b/docs/platforms/unreal/logs/index.mdx new file mode 100644 index 00000000000000..be34c3cb676300 --- /dev/null +++ b/docs/platforms/unreal/logs/index.mdx @@ -0,0 +1,36 @@ +--- +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 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. + +## Requirements + + + +## Setup + + + +## Usage + + + +## Options + + + +## 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 +- Use categories to organize logs and make them easier to search and filter +- Before-log handlers are executed synchronously, so keep processing lightweight \ No newline at end of file diff --git a/docs/product/explore/logs/getting-started/index.mdx b/docs/product/explore/logs/getting-started/index.mdx index a7517242a69215..a6943d786f4723 100644 --- a/docs/product/explore/logs/getting-started/index.mdx +++ b/docs/product/explore/logs/getting-started/index.mdx @@ -290,6 +290,14 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s url="/platforms/native/logs" /> +### Gaming + +- + ## Upcoming SDKs We're actively working on adding Log functionality to additional SDKs. Check out these GitHub issues for the latest updates: @@ -304,11 +312,6 @@ We're actively working on adding Log functionality to additional SDKs. Check out 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! diff --git a/platform-includes/logs/default-attributes/unreal.mdx b/platform-includes/logs/default-attributes/unreal.mdx new file mode 100644 index 00000000000000..e88c3e89506f48 --- /dev/null +++ b/platform-includes/logs/default-attributes/unreal.mdx @@ -0,0 +1,5 @@ +The Unreal Engine SDK automatically sets several default attributes on all log entries to provide context and improve debugging: + + + + \ No newline at end of file diff --git a/platform-includes/logs/options/unreal.mdx b/platform-includes/logs/options/unreal.mdx new file mode 100644 index 00000000000000..a2f12044287f9b --- /dev/null +++ b/platform-includes/logs/options/unreal.mdx @@ -0,0 +1,15 @@ +## Configuration Options + +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 | diff --git a/platform-includes/logs/requirements/unreal.mdx b/platform-includes/logs/requirements/unreal.mdx new file mode 100644 index 00000000000000..8bc6286300ca10 --- /dev/null +++ b/platform-includes/logs/requirements/unreal.mdx @@ -0,0 +1 @@ +Logs for Unreal Engine are supported in Sentry Unreal Engine SDK version `1.2.0` and above. \ No newline at end of file diff --git a/platform-includes/logs/setup/unreal.mdx b/platform-includes/logs/setup/unreal.mdx new file mode 100644 index 00000000000000..2251f55b948ce8 --- /dev/null +++ b/platform-includes/logs/setup/unreal.mdx @@ -0,0 +1,145 @@ +To enable logging in your Unreal Engine project, you need to configure the Sentry SDK with structured logging enabled. + +### Project Settings Configuration + +1. Open your project settings: **Project Settings > Plugins > Sentry** +2. Check the **Enable Structured Logging** option + +### Programmatic Configuration + +Alternatively, you can enable logging programmatically when initializing the SDK: + +```cpp +#include "SentrySubsystem.h" + +void ConfigureSentryWithLogs() +{ + USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + + // Create settings with logging enabled + SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings) + { + Settings->EnableStructuredLogging = true; + })); +} +``` + +### Advanced Configuration Options + +#### Automatic Unreal Engine Log Forwarding + +You can configure the SDK to automatically forward Unreal Engine's native `UE_LOG` calls to Sentry based on the enabled severity levels: + +```cpp +USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + +// 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 +})); +``` + +#### Log Category Filtering + +You can filter which log categories are sent to Sentry: + +```cpp +// Configure category filtering +USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + +// Create settings with logging enabled +SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings) +{ + Settings->EnableStructuredLogging = true; + + // Only forward logs from specific categories + TArray AllowedCategories; + AllowedCategories.Add(TEXT("LogGameFlow")); + AllowedCategories.Add(TEXT("LogPlayerSystem")); + AllowedCategories.Add(TEXT("LogSentrySdk")); + Settings->LogCategoryFilter = AllowedCategories; + +})); +``` + +#### Before-Log Handler + +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! + + +```cpp +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(); +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 \ No newline at end of file diff --git a/platform-includes/logs/usage/unreal.mdx b/platform-includes/logs/usage/unreal.mdx new file mode 100644 index 00000000000000..f31b9fec907ac6 --- /dev/null +++ b/platform-includes/logs/usage/unreal.mdx @@ -0,0 +1,66 @@ +Once logging is enabled, you can send log messages to Sentry using the `AddLog` method. + +## Basic Logging + +```cpp +#include "SentrySubsystem.h" + +void SendLogs() +{ + USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + + // 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")); +} +``` + +## Log Levels + +Sentry Logs supports the following log levels: + +| Unreal ESentryLevel | Sentry Logs UI Severity | +| --- | --- | +| Debug | DEBUG | +| Info | INFO | +| Warning | WARN | +| Error | ERROR | +| Fatal | FATAL | + +```cpp +// 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")); +``` + +## Automatic UE_LOG Integration + +When structured logging is enabled with the appropriate severity levels, the SDK can automatically capture Unreal Engine's native `UE_LOG` calls: + +```cpp +// 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) + +## Blueprint Support + +You can also use Sentry Logs from Blueprints by calling the **Add Log** function: + +1. Add a **Add Log** node to your Blueprint +2. Set the **Body** parameter to your log message +3. Choose the appropriate **Level** from the dropdown +4. Optionally set a **Category** for better organization \ No newline at end of file