From d6d0ef5c8e68542b7ad0ae75c5618282fb94c4c3 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Fri, 27 Jun 2025 15:00:19 +0300 Subject: [PATCH 01/11] Add migration guide --- .../unreal/configuration/options.mdx | 6 ++ docs/platforms/unreal/migration/index.mdx | 56 +++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/platforms/unreal/migration/index.mdx diff --git a/docs/platforms/unreal/configuration/options.mdx b/docs/platforms/unreal/configuration/options.mdx index 6b71720b5ece7..da250fd622ad3 100644 --- a/docs/platforms/unreal/configuration/options.mdx +++ b/docs/platforms/unreal/configuration/options.mdx @@ -42,6 +42,12 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env + + +Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. The dist has a max length of 64 characters. + + + Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx new file mode 100644 index 0000000000000..568399223cdfc --- /dev/null +++ b/docs/platforms/unreal/migration/index.mdx @@ -0,0 +1,56 @@ +--- +title: Migration Guide +description: "Learn more about migrating to the current version." +sidebar_order: 8000 +--- + +## Migrating to 1.0.0 + +### Breaking changes + +#### Sentry Classes Instantiation + +Sentry class objects created via `NewObject` in C++ or `ConstructObjectFromClass` in Blueprints now require an explicit call to their `Initialize` method (if available) before use. In Blueprints, it's recommended to use the provided Sentry library functions to create these entities as they automatically call `Initialize` and return a fully initialized, ready-to-use object. + +#### Cleanup Public Classes + +We cleaned up our public API by removing a few functions and classes to streamline the SDK and remove ambiguities. The following changes were made: + +- Removed `USentryId` class and replaced its usages with `FString` +- Removed `SentrySubsystem::ConfigureScope` function +- Removed `USentryLibrary::StringToBytesArray` function +- Removed `USentryLibrary::ByteArrayToString` function +- Removed `USentryLibrary::SaveStringToFile` function +- Removed `USentryScope::SetEnvironment` function +- Removed `USentryScope::GetEnvironment` function +- Removed `USentryScope::SetDist` function +- Removed `USentryScope::GetDist` function + +### Issue Grouping + +The Unreal SDK no longer modifies call stacks for assertion events by trimming the topmost frames related to the engine's internal assertion handling logic. This was previously done to work around the case where all assertions were grouped into a single Sentry issue. With this change, issue grouping is now fully handled by the Sentry server. + +### SDK Configuration Changes + +- The and properties must now be set in the plugin settings and can no longer be modified programmatically via scope configuration. + +- Sentry can no longer be disabled for specific platforms using the Enable for Build Platform Types option in the plugin settings (`General -> Misc`) or the EnableTargetPlatforms property in the project configuration file. + +### Crash Reporter Changes + +The `Epic Account Id` and `Login Id` are no longer included in the `Crash Info` context for crashes captured on Windows and Linux using the default Crash Reporter. These fields are intended for internal use by Epic Games and provide no meaningful value externally. + +## Migrating to 0.19.0 + +### Breaking changes + +- Renamed `OnError` delagate property of `FSentryOutputDeviceError` class to `OnAssert` + +## Migrating to 0.15.0 + +### Breaking changes + +To enable capturing editor crashes `USentrySubsystem` base class has been changed to `UEngineSubsystem`. + +- If you're using the plugin's Blueprint API, you will need to recreate all `Get Sentry Subsystem` nodes. +- If you're using the plugin's C++ API, update your implementation to access `USentrySubsystem` via the `GEngine` pointer. From cb357feb8fb6ce3b81ee1200ee8603d32bbdcb8e Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Mon, 21 Jul 2025 14:48:23 +0300 Subject: [PATCH 02/11] Update sdk configuration --- docs/platforms/unreal/migration/index.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index 568399223cdfc..453a2d5fbff53 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -34,7 +34,11 @@ The Unreal SDK no longer modifies call stacks for assertion events by trimming t - The and properties must now be set in the plugin settings and can no longer be modified programmatically via scope configuration. -- Sentry can no longer be disabled for specific platforms using the Enable for Build Platform Types option in the plugin settings (`General -> Misc`) or the EnableTargetPlatforms property in the project configuration file. +- Sentry can no longer be disabled for specific platforms using the `Enable for Build Platform Types` option in the plugin settings (`General -> Misc`) or the EnableTargetPlatforms property in the project configuration file. + +- If upgrading from a version prior to 0.9.0 legacy settings `DsnUrl`, `EnableVerboseLogging` and `EnableStackTrace` will no longer be read from the project configuration file automatically. Instead, you must re-set them in plugin settings to adopt the new format. + +- On mobile platforms, the default traces sampler will no longer be created automatically. You must now explicitly set the `Traces Sampler` property in the plugin settings to enable performance monitoring (`General -> Performance Monitoring`). ### Crash Reporter Changes From d871afc32e5fcae3467485e76238a7bfe6fb9e43 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Wed, 20 Aug 2025 14:27:27 +0200 Subject: [PATCH 03/11] Add user feedback migration --- docs/platforms/unreal/migration/index.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index 453a2d5fbff53..89eeab4294c5d 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -26,6 +26,18 @@ We cleaned up our public API by removing a few functions and classes to streamli - Removed `USentryScope::SetDist` function - Removed `USentryScope::GetDist` function +#### User feedback + +We have reworked the user feedback feature so now it no longer needs to be associated with a specific event and the only required input is the text message. If you were using this functionality in your project consider updating it accordingly: + +- Replace `USentryUserFeedback` class references with `USentryFeedback` +- Replace `USentrySubsystem::CaptureUserFeedback` function usages with `USentrySubsystem::CaptureFeedback` +- Replace `USentryLibrary::CreateSentryUserFeedback` function usages with `USentryLibrary::CreateSentryFeedback` + +#### Event ID format (Windows/Linux) + +On Windows and Linux, `ToString` function of `SentryId` class now returns the sanitized string that doesn't contain dashes. + ### Issue Grouping The Unreal SDK no longer modifies call stacks for assertion events by trimming the topmost frames related to the engine's internal assertion handling logic. This was previously done to work around the case where all assertions were grouped into a single Sentry issue. With this change, issue grouping is now fully handled by the Sentry server. From 9d04647b0ff85874126a1bba750adf4f6e49a85e Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Mon, 25 Aug 2025 17:12:26 +0300 Subject: [PATCH 04/11] Add new section how to configure global scope after ConfigureScope method removal --- docs/platforms/unreal/migration/index.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index 89eeab4294c5d..51c2ed85ff41d 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -17,7 +17,7 @@ Sentry class objects created via `NewObject` in C++ or `ConstructObjectFromCl We cleaned up our public API by removing a few functions and classes to streamline the SDK and remove ambiguities. The following changes were made: - Removed `USentryId` class and replaced its usages with `FString` -- Removed `SentrySubsystem::ConfigureScope` function +- Removed `USentrySubsystem::ConfigureScope` function - Removed `USentryLibrary::StringToBytesArray` function - Removed `USentryLibrary::ByteArrayToString` function - Removed `USentryLibrary::SaveStringToFile` function @@ -38,6 +38,10 @@ We have reworked the user feedback feature so now it no longer needs to be assoc On Windows and Linux, `ToString` function of `SentryId` class now returns the sanitized string that doesn't contain dashes. +#### Global scope configuration + +With the removal of `USentrySubsystem::ConfigureScope` global scope values (tags, context, attachments, etc.) should now be configured directly via the subsystem interface. + ### Issue Grouping The Unreal SDK no longer modifies call stacks for assertion events by trimming the topmost frames related to the engine's internal assertion handling logic. This was previously done to work around the case where all assertions were grouped into a single Sentry issue. With this change, issue grouping is now fully handled by the Sentry server. From 7e1b853de3a9b5bd90cc18a200fe324f9456b19f Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Wed, 27 Aug 2025 16:13:22 +0300 Subject: [PATCH 05/11] Add tracing breaking changes --- docs/platforms/unreal/migration/index.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index 51c2ed85ff41d..b7983634df60a 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -34,6 +34,12 @@ We have reworked the user feedback feature so now it no longer needs to be assoc - Replace `USentrySubsystem::CaptureUserFeedback` function usages with `USentrySubsystem::CaptureFeedback` - Replace `USentryLibrary::CreateSentryUserFeedback` function usages with `USentryLibrary::CreateSentryFeedback` +#### Tracing + +The `USentrySubsystem::StartTransactionWithContextAndOptions` function now takes an `FSentryTransactionOptions` struct instead of a `TMap`, improving clarity and allowing better extensibility in the future. + +Also, the `USentrySamplingContext` class now utilizes `FSentryVariant` instead of strings for custom sampling context values. + #### Event ID format (Windows/Linux) On Windows and Linux, `ToString` function of `SentryId` class now returns the sanitized string that doesn't contain dashes. From 8f88760ff38a8b381a712452ba6dda2562cf81a8 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Thu, 28 Aug 2025 18:37:46 +0300 Subject: [PATCH 06/11] Update docs/platforms/unreal/migration/index.mdx Co-authored-by: Bruno Garcia --- docs/platforms/unreal/migration/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index b7983634df60a..81967f72a88b2 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -3,7 +3,9 @@ title: Migration Guide description: "Learn more about migrating to the current version." sidebar_order: 8000 --- - + +We recommend using this guide starting from the version closes to your current version which might require scrolling further down before jumping to the latest guide. + ## Migrating to 1.0.0 ### Breaking changes From 7a0a6ca284fa8bea259c83a541ce603cb8aa3bd9 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Thu, 28 Aug 2025 19:17:29 +0300 Subject: [PATCH 07/11] Add scope configuration example --- docs/platforms/unreal/migration/index.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index 81967f72a88b2..3e33fd42f82e2 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -50,6 +50,23 @@ On Windows and Linux, `ToString` function of `SentryId` class now returns the sa With the removal of `USentrySubsystem::ConfigureScope` global scope values (tags, context, attachments, etc.) should now be configured directly via the subsystem interface. +```cpp +USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + +// Configuring global scope before v1.0.0 +SentrySubsystem->ConfigureScope(FConfigureScopeNativeDelegate::CreateLambda([](USentryScope* Scope) +{ + Scope->SetTag(...); + Scope->SetContext(...); + Scope->AddAttachment(...); +})); + +// Configuring global scope in v1.0.0 +SentrySubsystem->SetTag(...); +SentrySubsystem->SetContext(...); +SentrySubsystem->AddAttachment(...); +``` + ### Issue Grouping The Unreal SDK no longer modifies call stacks for assertion events by trimming the topmost frames related to the engine's internal assertion handling logic. This was previously done to work around the case where all assertions were grouped into a single Sentry issue. With this change, issue grouping is now fully handled by the Sentry server. From 4e29a735f3c2cc9bd1c7f4eadaa035aadd08a766 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Thu, 28 Aug 2025 19:17:44 +0300 Subject: [PATCH 08/11] Add feedback submission example --- docs/platforms/unreal/migration/index.mdx | 35 +++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index 3e33fd42f82e2..e8ced9d194de2 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -36,6 +36,39 @@ We have reworked the user feedback feature so now it no longer needs to be assoc - Replace `USentrySubsystem::CaptureUserFeedback` function usages with `USentrySubsystem::CaptureFeedback` - Replace `USentryLibrary::CreateSentryUserFeedback` function usages with `USentryLibrary::CreateSentryFeedback` +```cpp +USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + +FString Message = TEXT("Feedback message"); +FString Name = TEXT("John Doe"); +FString Email = TEXT("test@email.com"); +FString EventId = TEXT("c3829f10764848442d813c4124cf44a0"); + +// Submitting user feedback before v1.0.0 + +USentryUserFeedback* Feedback = NewObject(); + +Feedback->Initialize(EventId); + +Feedback->SetName(Name); // optional +Feedback->SetEmail(Email); // optional +Feedback->SetComment(Message); // optional + +SentrySubsystem->CaptureUserFeedback(Feedback); + +// Submitting user feedback in v1.0.0 + +USentryFeedback* Feedback = NewObject(); + +Feedback->Initialize(Message); + +Feedback->SetName(Name); // optional +Feedback->SetContactEmail(Email); // optional +Feedback->SetAssociatedEvent(Feedback); // optional + +SentrySubsystem->CaptureFeedback(Feedback); +``` + #### Tracing The `USentrySubsystem::StartTransactionWithContextAndOptions` function now takes an `FSentryTransactionOptions` struct instead of a `TMap`, improving clarity and allowing better extensibility in the future. @@ -54,6 +87,7 @@ With the removal of `USentrySubsystem::ConfigureScope` global scope values (tags USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); // Configuring global scope before v1.0.0 + SentrySubsystem->ConfigureScope(FConfigureScopeNativeDelegate::CreateLambda([](USentryScope* Scope) { Scope->SetTag(...); @@ -62,6 +96,7 @@ SentrySubsystem->ConfigureScope(FConfigureScopeNativeDelegate::CreateLambda([](U })); // Configuring global scope in v1.0.0 + SentrySubsystem->SetTag(...); SentrySubsystem->SetContext(...); SentrySubsystem->AddAttachment(...); From cceb70bc5efabdb578392ba8cb5c9a584735009b Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Thu, 28 Aug 2025 19:22:32 +0300 Subject: [PATCH 09/11] Add sampling example --- docs/platforms/unreal/migration/index.mdx | 24 +++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index e8ced9d194de2..e4f93b7524279 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -75,6 +75,30 @@ The `USentrySubsystem::StartTransactionWithContextAndOptions` function now takes Also, the `USentrySamplingContext` class now utilizes `FSentryVariant` instead of strings for custom sampling context values. +```cpp +USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + +// Starting transaction with context and options before v1.0.0 + +USentryTransactionContext* TransactionContext = ... + +TMap Options; +Options.Add("key1", "value1"); +Options.Add("key2", "value2"); + +SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options); + +// Starting transaction with context and options in v1.0.0 + +USentryTransactionContext* TransactionContext = ... + +FSentryTransactionOptions Options; +Options.CustomSamplingContext.Add("key1", FSentryVariant("value1")); +Options.CustomSamplingContext.Add("key2", FSentryVariant("value2")); + +SentrySubsystem->StartTransactionWithContextAndOptions(TransactionContext, Options); +``` + #### Event ID format (Windows/Linux) On Windows and Linux, `ToString` function of `SentryId` class now returns the sanitized string that doesn't contain dashes. From 8f23d0a4ff50905cfa0bbe1333a3fad0501b7dab Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Thu, 28 Aug 2025 19:27:16 +0300 Subject: [PATCH 10/11] Fix param --- docs/platforms/unreal/migration/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index e4f93b7524279..c8a04ee4cdec8 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -64,7 +64,7 @@ Feedback->Initialize(Message); Feedback->SetName(Name); // optional Feedback->SetContactEmail(Email); // optional -Feedback->SetAssociatedEvent(Feedback); // optional +Feedback->SetAssociatedEvent(EventId); // optional SentrySubsystem->CaptureFeedback(Feedback); ``` From dec90b333e6590a94d7803bde12be2057db5a202 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Thu, 28 Aug 2025 19:33:54 +0300 Subject: [PATCH 11/11] Fix component --- docs/platforms/unreal/migration/index.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/platforms/unreal/migration/index.mdx b/docs/platforms/unreal/migration/index.mdx index c8a04ee4cdec8..eaa528fe0a802 100644 --- a/docs/platforms/unreal/migration/index.mdx +++ b/docs/platforms/unreal/migration/index.mdx @@ -3,9 +3,11 @@ title: Migration Guide description: "Learn more about migrating to the current version." sidebar_order: 8000 --- - + + We recommend using this guide starting from the version closes to your current version which might require scrolling further down before jumping to the latest guide. - + + ## Migrating to 1.0.0 ### Breaking changes