Add attributes support for structured logs by tustanivsky · Pull Request #1190 · getsentry/sentry-unreal

tustanivsky · 2026-01-12T15:24:55Z

Overview

This PR adds support for structured log attributes to Sentry's logging system enabling developers to attach metadata to individual log entries. Attributes are key-value pairs that can be used to add contextual information to logs beyond just the message body, log category and severity level.

It is now possible to capture logs with a given set of attributes (provided as a TMap<FString, FSentryVariant>) and to get or set individual log item attributes in the BeforeLog handler. Also, attributes can be set globally, meaning they will be applied to all captured logs.

Attributes support all FSentryVariant types:

Primitives: String, Integer (int32), Float, Boolean
Complex types: Array, Map are converted to JSON strings

Separate LogXXXWithAttributes methods were added to USentrySubsystem instead of extending the existing LogXXX methods, because UFUNCTION's parameters of type TMap cannot have default values. Adding them would therefore introduce a breaking API change which this approach avoids.

Closes #1163

Usage examples

Add a log with attributes:

TMap<FString, FSentryVariant> Attributes;
Attributes.Add(TEXT("user_id"), FSentryVariant(TEXT("12345")));
Attributes.Add(TEXT("request_id"), FSentryVariant(TEXT("abc-def-ghi")));
Attributes.Add(TEXT("retry_count"), FSentryVariant(3));
Attributes.Add(TEXT("success"), FSentryVariant(false));

USentrySubsystem* Sentry = GEngine->GetEngineSubsystem<USentrySubsystem>();
Sentry->LogErrorWithAttributes(TEXT("Payment processing failed"), Attributes, TEXT("Payment"));

Manipulate attributes in BeforeLog Handler

USentryLog* MyBeforeLogHandler::HandleBeforeLog(USentryLog* LogData)
{
    // Read existing attributes
    FSentryVariant UserId = LogData->GetAttribute(TEXT("user_id"));

    // Add or modify attributes
    LogData->SetAttribute(TEXT("environment"), FSentryVariant(TEXT("production")));
    LogData->SetAttribute(TEXT("server_name"), FSentryVariant(TEXT("game-server-01")));

    // Remove sensitive attributes
    LogData->RemoveAttribute(TEXT("password"));

    return LogData;
}

Set global attributes:

// Get the Sentry subsystem                                                                                                                                                                                      
USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();                                                                                                                             
                                                                                                                                                                                                                 
// Set string attribute                                                                                                                                                                                          
SentrySubsystem->SetAttribute(TEXT("user.tier"), FSentryVariant(TEXT("premium")));                                                                                                                               
                                                                                                                                                                                                                 
// Set numeric attributes                                                                                                                                                                                        
SentrySubsystem->SetAttribute(TEXT("session.duration"), FSentryVariant(1234));                                                                                                                                   
SentrySubsystem->SetAttribute(TEXT("player.health"), FSentryVariant(85.5f));                                                                                                                                     
                                                                                                                                                                                                                 
// Set boolean attribute                                                                                                                                                                                         
SentrySubsystem->SetAttribute(TEXT("feature.enabled"), FSentryVariant(true));                                                                                                                                                                                                                                                  
                                                                                                                                                                                                                 
// Remove an attribute when no longer needed                                                                                                                                                                     
SentrySubsystem->RemoveAttribute(TEXT("session.duration"));

Other

Logging inside FSentryVariant was removed to prevent infinite recursion that could crash the SDK. This could previously happen if variants were misused in a custom BeforeLog handler (e.g. when attempting to get value of the non-existent attribute retrieved using USentryLog::GetAttribute).

To align SDK behavior across platforms, the Flush function is invoked internally on Android and Apple platforms to ensure all logs are flushed during app shutdown.

Testing

Newly added attributes API is covered with unit and integration tests.

Depends on:

feat: Add utilities to query structured logs from Sentry app-runner#34

Documentation

Unreal Engine: Add log attributes documentation sentry-docs#16046

…eal into feat/log-attributes # Conflicts: # plugin-dev/Source/Sentry/Private/Apple/Infrastructure/AppleSentryConverters.cpp

github-actions · 2026-01-12T15:25:30Z

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 5069650

plugin-dev/Source/Sentry/Private/Android/AndroidSentryLog.cpp

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java

plugin-dev/Source/Sentry/Private/Android/AndroidSentryLog.cpp

plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.cpp

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java

...dev/Source/Sentry/Private/GenericPlatform/Infrastructure/GenericPlatformSentryConverters.cpp

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java

plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.cpp

plugin-dev/Source/Sentry/Private/Apple/Infrastructure/AppleSentryConverters.cpp

...dev/Source/Sentry/Private/GenericPlatform/Infrastructure/GenericPlatformSentryConverters.cpp

plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.cpp

plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.cpp

plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentryLog.cpp

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

integration-test/Integration.Android.Tests.ps1

…eal into feat/log-attributes

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

integration-test/Integration.Android.Tests.ps1

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

integration-test/Integration.Android.Tests.ps1

This PR documents the new structured logging attributes API for Unreal SDK: - `LogXxxWithAttributes()` methods for attaching custom attributes to individual logs - Global attributes via `SetAttribute()`/`RemoveAttribute()` (with Android limitation note) - Attribute manipulation methods on `USentryLog` for use in `BeforeLogHandler` Also fixes incorrect `AddLog()` references to use the actual public API (`LogDebug()`, `LogInfo()`, etc.). Related items: - getsentry/sentry-unreal#1190

tustanivsky and others added 12 commits January 7, 2026 15:55

Add API allowing to capture logs with attributes

97ef07e

Add attributes API for single log item

d9fb75c

Add log attributes unit tests

2b94078

Add log item attributes API implementation for Android

adbb734

Add Adnroid attributes for log capture

a21c70f

Refactor Android bridge

050473d

Add logs attributes impl for Apple

07961c3

Format code

99705ba

Fix attributes array population when capturing log

85bce32

Remove internal logging for variant type

b876dd1

Merge branch 'feat/log-attributes' of github.com:getsentry/sentry-unr…

e609d4b

…eal into feat/log-attributes # Conflicts: # plugin-dev/Source/Sentry/Private/Apple/Infrastructure/AppleSentryConverters.cpp

Format code

11d4a34

Update changelog

75d70c9

tustanivsky marked this pull request as ready for review January 12, 2026 16:33

cursor bot reviewed Jan 12, 2026

View reviewed changes

plugin-dev/Source/Sentry/Private/Android/AndroidSentryLog.cpp Show resolved Hide resolved

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java Show resolved Hide resolved

plugin-dev/Source/Sentry/Private/Android/AndroidSentryLog.cpp Show resolved Hide resolved

Add extra security checks for android

fc24719

sentry bot reviewed Jan 13, 2026

View reviewed changes

plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.cpp Outdated Show resolved Hide resolved

cursor bot reviewed Jan 13, 2026

View reviewed changes

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java Show resolved Hide resolved

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java Show resolved Hide resolved

tustanivsky added 2 commits January 13, 2026 13:10

Fix PR suggestions

7bab2e2

Fix encoding

1981896

sentry bot reviewed Jan 13, 2026

View reviewed changes

...dev/Source/Sentry/Private/GenericPlatform/Infrastructure/GenericPlatformSentryConverters.cpp Show resolved Hide resolved

cursor bot reviewed Jan 13, 2026

View reviewed changes

...dev/Source/Sentry/Private/GenericPlatform/Infrastructure/GenericPlatformSentryConverters.cpp Outdated Show resolved Hide resolved

plugin-dev/Source/Sentry/Private/Android/Java/SentryBridgeJava.java Show resolved Hide resolved

tustanivsky added 3 commits January 13, 2026 13:29

Fix encoding

a5857ca

Fix attribute format for map and array types (Apple)

d79da57

Fix attribute map and array format for android

dbe48ff

cursor bot reviewed Jan 13, 2026

View reviewed changes

plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.cpp Show resolved Hide resolved

plugin-dev/Source/Sentry/Private/Apple/Infrastructure/AppleSentryConverters.cpp Show resolved Hide resolved

tustanivsky and others added 3 commits January 13, 2026 15:28

Update docs

d8c8332

Fix potential crash when variant array/map has empty items

54affb0

Format code

e547371

tustanivsky added 3 commits January 15, 2026 12:17

Uncomment

d9ddfce

Bump app-runner

b9083e8

Remove timeout override

b09c611

cursor bot reviewed Jan 15, 2026

View reviewed changes

...dev/Source/Sentry/Private/GenericPlatform/Infrastructure/GenericPlatformSentryConverters.cpp Show resolved Hide resolved

Add flush on SDK close for Cocoa and Android

50fb7e0

sentry bot reviewed Jan 15, 2026

View reviewed changes

plugin-dev/Source/Sentry/Private/Apple/AppleSentrySubsystem.cpp Show resolved Hide resolved

plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentrySubsystem.cpp Outdated Show resolved Hide resolved

tustanivsky added 2 commits January 15, 2026 16:07

Fix

78d9185

Fix Android log integrations tests

b67b9d7

sentry bot reviewed Jan 15, 2026

View reviewed changes

plugin-dev/Source/Sentry/Private/GenericPlatform/GenericPlatformSentryLog.cpp Show resolved Hide resolved

tustanivsky added 3 commits January 16, 2026 08:59

Merge branch 'main' into feat/log-attributes

51e723d

Test

f52719b

Add global attributes API

e891297

cursor bot reviewed Jan 16, 2026

View reviewed changes

integration-test/Integration.Android.Tests.ps1 Outdated Show resolved Hide resolved

tustanivsky and others added 4 commits January 16, 2026 10:52

Add global attribute tests

859748e

Format code

dcda151

Update snapshot

3241661

Merge branch 'feat/log-attributes' of github.com:getsentry/sentry-unr…

ade5586

…eal into feat/log-attributes

cursor bot reviewed Jan 16, 2026

View reviewed changes

integration-test/Integration.Android.Tests.ps1 Outdated Show resolved Hide resolved

tustanivsky mentioned this pull request Jan 16, 2026

Unreal Engine: Add log attributes documentation getsentry/sentry-docs#16046

Merged

Bump app-runner

d5c468c

cursor bot reviewed Jan 16, 2026

View reviewed changes

integration-test/Integration.Android.Tests.ps1 Outdated Show resolved Hide resolved

Fix native tests

5069650

tustanivsky requested review from limbonaut and mujacica January 16, 2026 12:29

mujacica approved these changes Jan 16, 2026

View reviewed changes

tustanivsky merged commit 00b68a6 into main Jan 16, 2026
108 of 109 checks passed

tustanivsky deleted the feat/log-attributes branch January 16, 2026 13:19

tustanivsky mentioned this pull request Jan 20, 2026

Add category as attribute to structured logs #1199

Merged

tustanivsky mentioned this pull request Mar 6, 2026

Add global attributes support for Android #1274

Merged

Uh oh!

Conversation

tustanivsky commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Usage examples

Other

Testing

Documentation

Uh oh!

github-actions bot commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tustanivsky commented Jan 12, 2026 •

edited

Loading

github-actions bot commented Jan 12, 2026 •

edited

Loading