Skip to content

Commit 90bc95b

Browse files
mujacicatustanivsky
mujacica
and
tustanivsky
authored
docs (Unreal/logs): Add Logs documentation for Unreal SDK (#15064)
* Added Logs documentation for Unreal SDK --------- Co-authored-by: Ivan Tustanivskyi <[email protected]>
1 parent ad37c58 commit 90bc95b

File tree

7 files changed

+276
-5
lines changed

7 files changed

+276
-5
lines changed

‎docs/platforms/unreal/logs/index.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Set Up Logs
3+
sidebar_title: Logs
4+
description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry."
5+
sidebar_order: 5600
6+
---
7+
8+
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.
9+
10+
## Requirements
11+
12+
<PlatformContent includePath="logs/requirements" />
13+
14+
## Setup
15+
16+
<PlatformContent includePath="logs/setup" />
17+
18+
## Usage
19+
20+
<PlatformContent includePath="logs/usage" />
21+
22+
## Options
23+
24+
<PlatformContent includePath="logs/options" />
25+
26+
## Default Attributes
27+
28+
<PlatformContent includePath="logs/default-attributes" />
29+
30+
## Performance Considerations
31+
32+
- Logs are sent asynchronously to avoid impacting game performance
33+
- Consider disabling Debug level logs in production to avoid excessive log volume
34+
- Each severity level can be individually controlled to fine-tune what gets sent to Sentry
35+
- Use categories to organize logs and make them easier to search and filter
36+
- Before-log handlers are executed synchronously, so keep processing lightweight

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

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,14 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s
290290
url="/platforms/native/logs"
291291
/>
292292

293+
### Gaming
294+
295+
- <LinkWithPlatformIcon
296+
platform="unreal"
297+
label="Unreal Engine"
298+
url="/platforms/unreal/logs/"
299+
/>
300+
293301
## Upcoming SDKs
294302

295303
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
304312
label="Unity"
305313
url="https://github.com/getsentry/sentry-unity/issues/2172"
306314
/>
307-
- <LinkWithPlatformIcon
308-
platform="unreal"
309-
label="Unreal"
310-
url="https://github.com/getsentry/sentry-unreal/issues/883"
311-
/>
312315

313316
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!
314317

‎platform-includes/logs/default-attributes/unreal.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
The Unreal Engine SDK automatically sets several default attributes on all log entries to provide context and improve debugging:
2+
3+
<Include name="logs/default-attributes/core" />
4+
5+
<Include name="logs/default-attributes/user-mobile" />

‎platform-includes/logs/options/unreal.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
## Configuration Options
2+
3+
The following configuration options are available for Sentry Logs in Unreal Engine:
4+
5+
| Option | Description | Default |
6+
|--------|-------------|------------|
7+
| **Enable Structured Logging** | Master toggle for the structured logging feature | `false` |
8+
| **Enable Debug Logs** | Forward Debug level UE_LOG calls to Sentry | `false` |
9+
| **Enable Info Logs** | Forward Info level UE_LOG calls to Sentry | `false` |
10+
| **Enable Warning Logs** | Forward Warning level UE_LOG calls to Sentry | `true` |
11+
| **Enable Error Logs** | Forward Error level UE_LOG calls to Sentry | `true` |
12+
| **Enable Fatal Logs** | Forward Fatal level UE_LOG calls to Sentry | `true` |
13+
| **Send Logs As Breadcrumbs** | Send UE_LOG calls BOTH as Logs and as Breadcrumbs, instead of just Logs | `false` |
14+
| **Log Category Filter** | Array of log categories to include (empty = all categories) | Empty |
15+
| **Before Log Callback** | Handler to modify or filter log events before sending | None |

‎platform-includes/logs/requirements/unreal.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Logs for Unreal Engine are supported in Sentry Unreal Engine SDK version `1.2.0` and above.

‎platform-includes/logs/setup/unreal.mdx‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
To enable logging in your Unreal Engine project, you need to configure the Sentry SDK with structured logging enabled.
2+
3+
### Project Settings Configuration
4+
5+
1. Open your project settings: **Project Settings > Plugins > Sentry**
6+
2. Check the **Enable Structured Logging** option
7+
8+
### Programmatic Configuration
9+
10+
Alternatively, you can enable logging programmatically when initializing the SDK:
11+
12+
```cpp
13+
#include "SentrySubsystem.h"
14+
15+
void ConfigureSentryWithLogs()
16+
{
17+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
18+
19+
// Create settings with logging enabled
20+
SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
21+
{
22+
Settings->EnableStructuredLogging = true;
23+
}));
24+
}
25+
```
26+
27+
### Advanced Configuration Options
28+
29+
#### Automatic Unreal Engine Log Forwarding
30+
31+
You can configure the SDK to automatically forward Unreal Engine's native `UE_LOG` calls to Sentry based on the enabled severity levels:
32+
33+
```cpp
34+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
35+
36+
// Configure automatic log forwarding programmatically
37+
SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
38+
{
39+
Settings->EnableStructuredLogging = true;
40+
41+
// Enable specific severity levels for UE_LOG forwarding
42+
Settings->EnableDebugLogs = false;
43+
Settings->EnableInfoLogs = true;
44+
Settings->EnableWarningLogs = true;
45+
Settings->EnableErrorLogs = true;
46+
Settings->EnableFatalLogs = true;
47+
48+
Settings->bSendBreadcrumbsWithStructuredLogging = false; // Send as structured logs instead of breadcrumbs
49+
}));
50+
```
51+
52+
#### Log Category Filtering
53+
54+
You can filter which log categories are sent to Sentry:
55+
56+
```cpp
57+
// Configure category filtering
58+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
59+
60+
// Create settings with logging enabled
61+
SentrySubsystem->InitializeWithSettings(FConfigureSettingsNativeDelegate::CreateLambda([=](USentrySettings* Settings)
62+
{
63+
Settings->EnableStructuredLogging = true;
64+
65+
// Only forward logs from specific categories
66+
TArray<FString> AllowedCategories;
67+
AllowedCategories.Add(TEXT("LogGameFlow"));
68+
AllowedCategories.Add(TEXT("LogPlayerSystem"));
69+
AllowedCategories.Add(TEXT("LogSentrySdk"));
70+
Settings->LogCategoryFilter = AllowedCategories;
71+
72+
}));
73+
```
74+
75+
#### Before-Log Handler
76+
77+
To filter logs, or update them before they are sent to Sentry, you can create a custom before-log handler class.
78+
79+
<Alert level="info">
80+
Logging additional messages in the BeforeLog handler can cause recursive call of the handler, resulting in a stack overflow!
81+
</Alert>
82+
83+
```cpp
84+
UCLASS()
85+
class UCustomLogFilter : public USentryBeforeLogHandler
86+
{
87+
GENERATED_BODY()
88+
public:
89+
virtual USentryLogEvent* HandleBeforeLog_Implementation(USentryLogEvent* LogEvent) override
90+
{
91+
// Filter out all debug logs
92+
if (LogEvent->GetLevel() == ESentryLevel::Debug)
93+
{
94+
return nullptr; // Return null to prevent sending
95+
}
96+
97+
// Filter out logs based on message content
98+
if (LogEvent->GetBody().Contains(TEXT("Sensitive")))
99+
{
100+
return nullptr; // Filter out sensitive logs
101+
}
102+
103+
// Filter based on specific categories
104+
if (LogEvent->GetBody().Contains(TEXT("Password")) ||
105+
LogEvent->GetBody().Contains(TEXT("Token")))
106+
{
107+
return nullptr; // Filter out authentication-related logs
108+
}
109+
110+
return LogEvent; // Return modified event
111+
}
112+
};
113+
114+
// Configure settings using delegate
115+
FConfigureSettingsDelegate SettingsDelegate;
116+
SettingsDelegate.BindDynamic(this, &USomeClass::HandleSettingsDelegate);
117+
118+
void USomeClass::HandleSettingsDelegate(USentrySettings* Settings)
119+
{
120+
// Enable structured logging
121+
Settings->EnableStructuredLogging = true;
122+
123+
// Configure individual severity levels
124+
Settings->EnableDebugLogs = false;
125+
Settings->EnableInfoLogs = true;
126+
Settings->EnableWarningLogs = true;
127+
Settings->EnableErrorLogs = true;
128+
Settings->EnableFatalLogs = true;
129+
130+
// Set custom before-log handler
131+
Settings->BeforeLogCallback = UCustomLogFilter::StaticClass();
132+
}
133+
134+
// Initialize with settings delegate
135+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
136+
SentrySubsystem->InitializeWithSettings(SettingsDelegate);
137+
```
138+
139+
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.
140+
141+
The `USentryLog` object has the following methods:
142+
- `GetLevel()`: Returns the severity level of the log (`ESentryLevel`)
143+
- `GetBody()`: Returns the formatted log message (`FString`)
144+
- `SetLevel(ESentryLevel Level)`: Sets the Level of the Log Event
145+
- `SetBody(FString& Body)`: Sets the Body of the Log Event

‎platform-includes/logs/usage/unreal.mdx‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
Once logging is enabled, you can send log messages to Sentry using the `AddLog` method.
2+
3+
## Basic Logging
4+
5+
```cpp
6+
#include "SentrySubsystem.h"
7+
8+
void SendLogs()
9+
{
10+
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
11+
12+
// Send a simple log message
13+
SentrySubsystem->AddLog(TEXT("User completed tutorial"), ESentryLevel::Info);
14+
15+
// Send a log message with category
16+
SentrySubsystem->AddLog(TEXT("Failed to load texture asset"), ESentryLevel::Warning, TEXT("AssetLoading"));
17+
18+
// Send an error log
19+
SentrySubsystem->AddLog(TEXT("Database connection failed"), ESentryLevel::Error, TEXT("Database"));
20+
}
21+
```
22+
23+
## Log Levels
24+
25+
Sentry Logs supports the following log levels:
26+
27+
| Unreal ESentryLevel | Sentry Logs UI Severity |
28+
| --- | --- |
29+
| Debug | DEBUG |
30+
| Info | INFO |
31+
| Warning | WARN |
32+
| Error | ERROR |
33+
| Fatal | FATAL |
34+
35+
```cpp
36+
// Examples of different log levels
37+
SentrySubsystem->AddLog(TEXT("Player position updated"), ESentryLevel::Debug, TEXT("Player"));
38+
SentrySubsystem->AddLog(TEXT("Level loaded successfully"), ESentryLevel::Info, TEXT("GameFlow"));
39+
SentrySubsystem->AddLog(TEXT("Low memory warning"), ESentryLevel::Warning, TEXT("Performance"));
40+
SentrySubsystem->AddLog(TEXT("Failed to save game data"), ESentryLevel::Error, TEXT("SaveSystem"));
41+
SentrySubsystem->AddLog(TEXT("Critical system failure"), ESentryLevel::Fatal, TEXT("System"));
42+
```
43+
44+
## Automatic UE_LOG Integration
45+
46+
When structured logging is enabled with the appropriate severity levels, the SDK can automatically capture Unreal Engine's native `UE_LOG` calls:
47+
48+
```cpp
49+
// Standard Unreal Engine logging - automatically captured when severity levels are enabled
50+
UE_LOG(LogGameFlow, Warning, TEXT("Player health is critically low: %d"), PlayerHealth);
51+
UE_LOG(LogAssets, Error, TEXT("Failed to load texture: %s"), *TexturePath);
52+
UE_LOG(LogTemp, Log, TEXT("Debug information")); // Only sent if EnableInfoLogs = true
53+
```
54+
55+
You can configure whether these logs are sent as:
56+
- **Structured Logs**: Full log entries with searchable attributes
57+
- **Breadcrumbs**: Contextual information attached to errors (useful for debugging)
58+
59+
## Blueprint Support
60+
61+
You can also use Sentry Logs from Blueprints by calling the **Add Log** function:
62+
63+
1. Add a **Add Log** node to your Blueprint
64+
2. Set the **Body** parameter to your log message
65+
3. Choose the appropriate **Level** from the dropdown
66+
4. Optionally set a **Category** for better organization

0 commit comments

Comments
 (0)