From f6d335de3e4f20bf5a36b548d822516c661acef4 Mon Sep 17 00:00:00 2001 From: Bogdan Ivanov Date: Wed, 9 Sep 2026 14:22:46 +0300 Subject: [PATCH 1/4] feat: add structured error reporting --- Aptabase.uplugin | 4 +- CHANGELOG.md | 10 + Docs/testing.md | 17 ++ README.md | 52 +++- Source/Aptabase/Private/Aptabase.cpp | 6 +- .../Private/AptabaseAnalyticsProvider.cpp | 65 ++++- .../Private/AptabaseAnalyticsProvider.h | 9 + .../Private/AptabaseBlueprintLibrary.cpp | 19 ++ .../Private/AptabaseErrorDispatcher.cpp | 123 ++++++++++ .../Private/AptabaseErrorDispatcher.h | 29 +++ Source/Aptabase/Private/AptabaseErrorLog.cpp | 36 +++ Source/Aptabase/Private/AptabaseErrorLog.h | 19 ++ .../Aptabase/Private/AptabaseErrorQueue.cpp | 68 ++++++ Source/Aptabase/Private/AptabaseErrorQueue.h | 28 +++ .../Aptabase/Private/AptabaseErrorReport.cpp | 59 +++++ Source/Aptabase/Private/AptabaseErrorReport.h | 35 +++ Source/Aptabase/Private/AptabaseSettings.h | 6 + .../Tests/AptabaseErrorReportingTests.cpp | 231 ++++++++++++++++++ .../Public/AptabaseBlueprintLibrary.h | 22 ++ llms.txt | 20 +- 20 files changed, 848 insertions(+), 10 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 Docs/testing.md create mode 100644 Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp create mode 100644 Source/Aptabase/Private/AptabaseErrorDispatcher.cpp create mode 100644 Source/Aptabase/Private/AptabaseErrorDispatcher.h create mode 100644 Source/Aptabase/Private/AptabaseErrorLog.cpp create mode 100644 Source/Aptabase/Private/AptabaseErrorLog.h create mode 100644 Source/Aptabase/Private/AptabaseErrorQueue.cpp create mode 100644 Source/Aptabase/Private/AptabaseErrorQueue.h create mode 100644 Source/Aptabase/Private/AptabaseErrorReport.cpp create mode 100644 Source/Aptabase/Private/AptabaseErrorReport.h create mode 100644 Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp create mode 100644 Source/Aptabase/Public/AptabaseBlueprintLibrary.h diff --git a/Aptabase.uplugin b/Aptabase.uplugin index 7c2b7cf..9a8632f 100644 --- a/Aptabase.uplugin +++ b/Aptabase.uplugin @@ -1,6 +1,6 @@ { "FileVersion": 3, - "VersionName": "0.2.0", + "VersionName": "0.3.0", "EngineVersion": "5.6", "FriendlyName": "Aptabase", "Description": "Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps", @@ -19,4 +19,4 @@ "LoadingPhase": "Default" } ] -} \ No newline at end of file +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..35188c0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +## 0.3.0 + +- Add `UAptabaseBlueprintLibrary::TrackError` and the **Track Error** Blueprint node for structured handled and fatal error reports. +- Add opt-in **Enable Error Logging** to report Unreal Error/Fatal log messages during active sessions. +- Include capture-time session, timestamp, OS, app version, SDK version, severity, kind, and debug mode; truncate fields to the server limits. +- Send errors individually to `/api/v0/error`, retry network failures and HTTP 408/429/5xx on later flushes, and discard permanent rejections including HTTP 403 quota exhaustion. +- Bound outstanding reports to 25 and deduplicate up to 100 unique errors per session. +- Clean up log subscriptions and HTTP callbacks at shutdown; fix flushing event batches with fewer than 25 events. diff --git a/Docs/testing.md b/Docs/testing.md new file mode 100644 index 0000000..383e75d --- /dev/null +++ b/Docs/testing.md @@ -0,0 +1,17 @@ +# Testing error reporting + +Install the plugin in a C++ Unreal Engine project and build the Development Editor target. Open **Tools → Test Automation** (or **Session Frontend → Automation**) and run **Aptabase.Errors**. + +For a command-line run, substitute your engine executable and project path: + +```sh +UnrealEditor-Cmd YourProject.uproject -unattended -NullRHI \ + -ExecCmds="Automation RunTests Aptabase.Errors" \ + -TestExit="Automation Test Queue Empty" -log +``` + +The tests cover the JSON contract and field limits, retry status codes, capture-time context across sessions, deduplication, in-flight queue capacity, session limits, and concurrent capture. They do not send data to Aptabase. + +For an end-to-end check, configure a local HTTP server as the SH host and start an analytics session in Play-in-Editor. Record a normal event and call **Track Error**. Verify that the event goes to `/api/v0/events` as an array and the error goes to `/api/v0/error` as one JSON object, with `App-Key` and `Content-Type: application/json` headers. Return 202 to accept a report; repeat with 400/403 (no retry), 408/429/500 (retry on the next flush), and a disconnected server. End/start PIE and verify that pending retries retain the old session and that new reports carry the new session. + +Enable **Enable Error Logging** before starting the session. Emit the same `UE_LOG(LogTemp, Error, TEXT("Test error"))` several times: only one report should arrive. Emit a Warning and verify that no report arrives. End the session and verify that subsequent error logs are not reported. Fatal logging actually terminates Unreal and is not required to test classification: use **Track Error** with **Fatal** enabled instead. diff --git a/README.md b/README.md index 7b43caf..6ca4f97 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,59 @@ A few important notes: 3. You do not need to await for the record event calls, they will run in the background. 4. Only strings and numbers values are allowed on custom properties +## Error Reporting + +Error reporting is in beta. Reports appear on the **Errors** page of your Aptabase dashboard. + +Start an analytics session using the **Start Session** Blueprint node or your configured provider's `StartSession()` before tracking events or errors. End it with **End Session** / `EndSession()` when your game session ends. + +### C++ + +Add `"Aptabase"` to your game's `Build.cs` dependencies and call the API on the game thread: + +```cpp +#include "AptabaseBlueprintLibrary.h" + +UAptabaseBlueprintLibrary::TrackError( + TEXT("Could not save the game"), TEXT("SaveError")); + +// Supply the original stack trace when available. Fatal means the app cannot recover; +// setting it does not terminate the app. +UAptabaseBlueprintLibrary::TrackError( + TEXT("Required assets are missing"), TEXT("LoadError"), TEXT("LoadAssets\nStartGame"), true); +``` + +Manual reports have severity `error` and kind `handled`. With `bFatal = true`, they have severity `fatal` and kind `crash`. The message, type, and optional stack are sent with the session ID, capture timestamp, OS, app/SDK versions, and debug/release mode. Empty error types default to `Error`. + +### Blueprints + +Use **Track Error** under **Analytics → Aptabase**. Set **Error Message** and **Error Type**; expand the advanced pins for **Stack Trace** and **Fatal**. The node uses Aptabase's own provider instance and also works when Aptabase is configured through the Multicast provider. + +### Automatic error logs + +Enable **Project Settings → Analytics → Aptabase → Enable Error Logging** before starting the session, or add this to `Config/DefaultAptabase.ini`: + +```ini +[/Script/Aptabase.AptabaseSettings] +bEnableErrorLogging=True +``` + +This is off by default. While enabled, Unreal `Error` log messages are reported as `unhandled`/`error`, with the log category as the error type. `Fatal` messages reaching the log listener are classified as `crash`/`fatal`. Warnings, ordinary logs, and Aptabase/HTTP diagnostics are ignored. Automatic reports contain the log message; they do not synthesize a stack trace. Worker-thread logs are supported, and the listener is removed at session end, including Play-in-Editor sessions. + +This listener does not intercept native crashes, assertions that bypass the log listener, or platform signals. Fatal delivery is best effort: the game thread and HTTP system must still run to send the report. Logging compiled out of a Shipping build cannot be captured. Unreal's own Crash Reporter remains available. + +### Delivery + +- Reports are sent asynchronously, one per request. Capturing an error schedules an immediate send on the game thread; `FlushEvents()` and the normal send timer also flush errors. +- Failed requests are retained for a later flush on connection errors or HTTP 408, 429, and 5xx. Other responses, including HTTP 403 (monthly quota exhausted), are not retried. +- The queue holds up to 25 outstanding reports, including requests in progress. New reports are dropped when full. Each unique combination of kind, type, message, and stack is reported once per session, up to 100 unique reports. +- Retries retain their original session and system context. Reports are stored in memory only and can be lost when the process exits. Ending a session initiates a final flush without waiting for delivery. +- Error text can contain application data. Only include information you intend to send to Aptabase. + +See [testing instructions](Docs/testing.md) for the Unreal automation suite. + ## Preparing for Submission to Apple App Store When submitting your app to the Apple App Store, you'll need to fill out the `App Privacy` form. You can find all the answers on our [How to fill out the Apple App Privacy when using Aptabase](https://aptabase.com/docs/apple-app-privacy) guide. For AI/LLM integration instructions, see [llms.txt](./llms.txt) - diff --git a/Source/Aptabase/Private/Aptabase.cpp b/Source/Aptabase/Private/Aptabase.cpp index b5419be..1083af1 100644 --- a/Source/Aptabase/Private/Aptabase.cpp +++ b/Source/Aptabase/Private/Aptabase.cpp @@ -31,6 +31,8 @@ void FAptabaseModule::StartupModule() void FAptabaseModule::ShutdownModule() { + OnApplicationShutdown(); + AnalyticsProvider.Reset(); if (FSlateApplication::IsInitialized()) { FSlateApplication& Application = FSlateApplication::Get(); @@ -48,8 +50,6 @@ void FAptabaseModule::OnApplicationShutdown() { AnalyticsProvider->EndSession(); } - - AnalyticsProvider.Reset(); } #if WITH_EDITOR @@ -62,4 +62,4 @@ void FAptabaseModule::OnEndPIE(bool bIsSimulating) } #endif -IMPLEMENT_MODULE(FAptabaseModule, Aptabase); \ No newline at end of file +IMPLEMENT_MODULE(FAptabaseModule, Aptabase); diff --git a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp index 55e06d2..e5eda5d 100644 --- a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp +++ b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp @@ -13,6 +13,8 @@ #include #include "AptabaseData.h" +#include "AptabaseErrorDispatcher.h" +#include "AptabaseErrorLog.h" #include "AptabaseLog.h" #include "AptabaseSettings.h" #include "ExtendedAnalyticsEventAttribute.h" @@ -21,6 +23,10 @@ namespace { UGameInstance* GetCurrentGameInstance() { + if (!GEngine) + { + return nullptr; + } for (const FWorldContext& Context : GEngine->GetWorldContexts()) { if (Context.WorldType == EWorldType::PIE || Context.WorldType == EWorldType::Game) @@ -44,6 +50,29 @@ namespace } } // namespace +FAptabaseAnalyticsProvider::FAptabaseAnalyticsProvider() : ErrorDispatcher(MakeShared()) +{ +} + +FAptabaseAnalyticsProvider::~FAptabaseAnalyticsProvider() +{ + ErrorLog.Reset(); + if (const UGameInstance* GameInstance = GetCurrentGameInstance()) + { + GameInstance->GetTimerManager().ClearTimer(BatchEventTimerHandle); + } + for (const FHttpRequestPtr& Request : EventRequests) + { + Request->OnProcessRequestComplete().Unbind(); + Request->CancelRequest(); + } +} + +void FAptabaseAnalyticsProvider::TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal) +{ + ErrorDispatcher->TrackError(ErrorType, Message, StackTrace, bFatal); +} + void FAptabaseAnalyticsProvider::RecordExtendedEvent(const FString& EventName, const TArray& Attributes) { RecordEventInternal(EventName, Attributes); @@ -51,6 +80,10 @@ void FAptabaseAnalyticsProvider::RecordExtendedEvent(const FString& EventName, c bool FAptabaseAnalyticsProvider::StartSession(const TArray& Attributes) { + if (bHasActiveSession) + { + return true; + } const UGameInstance* GameInstance = GetCurrentGameInstance(); if (!ensure(GameInstance)) { @@ -68,11 +101,30 @@ bool FAptabaseAnalyticsProvider::StartSession(const TArray()->ProjectVersion; + const TSharedPtr Plugin = IPluginManager::Get().FindPlugin(TEXT("Aptabase")); + ErrorContext.SdkVersion = FString::Printf(TEXT("aptabase-unreal@%s"), Plugin.IsValid() ? *Plugin->GetDescriptor().VersionName : TEXT("unknown")); + ErrorContext.bIsDebug = !IsInReleaseMode(); + ErrorContext.ApiUrl = Settings->GetApiUrl(); + ErrorContext.ApiUrl.RemoveFromEnd(TEXT("/")); + ErrorContext.AppKey = Settings->AppKey; + ErrorDispatcher->StartSession(ErrorContext); + if (Settings->bEnableErrorLogging) + { + ErrorLog = MakeUnique(ErrorDispatcher.ToSharedRef()); + } return true; } void FAptabaseAnalyticsProvider::EndSession() { + ErrorLog.Reset(); + ErrorDispatcher->EndSession(); if (BatchEventTimerHandle.IsValid()) { if (const UGameInstance* GameInstance = GetCurrentGameInstance()) @@ -111,11 +163,12 @@ void FAptabaseAnalyticsProvider::FlushEvents() TArray CurrentBatch; CurrentBatch.Append(EventsToProcess.Left(NumEventsPerRequest)); - EventsToProcess.RightChopInline(NumEventsPerRequest); + EventsToProcess.RightChopInline(FMath::Min(NumEventsPerRequest, EventsToProcess.Num())); SendEventsNow(CurrentBatch); } BatchedEvents.Empty(); + ErrorDispatcher->Flush(); } void FAptabaseAnalyticsProvider::SetUserID(const FString& InUserID) @@ -198,12 +251,18 @@ void FAptabaseAnalyticsProvider::SendEventsNow(const TArraySetHeader(TEXT("Content-Type"), TEXT("application/json")); HttpRequest->SetURL(RequestUrl); HttpRequest->OnProcessRequestComplete().BindRaw(this, &FAptabaseAnalyticsProvider::OnEventsRecoded, EventPayloads); - HttpRequest->ProcessRequest(); + EventRequests.Add(HttpRequest); + if (!HttpRequest->ProcessRequest()) + { + HttpRequest->OnProcessRequestComplete().Unbind(); + EventRequests.Remove(HttpRequest); + } } void FAptabaseAnalyticsProvider::OnEventsRecoded(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bWasSuccessful, TArray OriginalEvents) { - if (!bWasSuccessful) + EventRequests.Remove(Request); + if (!bWasSuccessful || !Response.IsValid()) { UE_LOG(LogAptabase, Error, TEXT("Request to record the event was unsuccessful.")); return; diff --git a/Source/Aptabase/Private/AptabaseAnalyticsProvider.h b/Source/Aptabase/Private/AptabaseAnalyticsProvider.h index fc2e93a..9688263 100644 --- a/Source/Aptabase/Private/AptabaseAnalyticsProvider.h +++ b/Source/Aptabase/Private/AptabaseAnalyticsProvider.h @@ -7,6 +7,8 @@ #include "AptabaseData.h" struct FExtendedAnalyticsEventAttribute; +class FAptabaseErrorDispatcher; +class FAptabaseErrorLog; /** * Implementation of Aptabase Analytics provider @@ -14,6 +16,10 @@ struct FExtendedAnalyticsEventAttribute; class FAptabaseAnalyticsProvider final : public IAnalyticsProvider { public: + FAptabaseAnalyticsProvider(); + virtual ~FAptabaseAnalyticsProvider() override; + void TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal); + /** * Overload for RecordEvent that takes an array of ExtendedAttributes */ @@ -71,4 +77,7 @@ class FAptabaseAnalyticsProvider final : public IAnalyticsProvider * @brief Default event attributes that will be added to all events */ TArray DefaultEventAttributes; + TSharedPtr ErrorDispatcher; + TUniquePtr ErrorLog; + TArray EventRequests; }; diff --git a/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp b/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp new file mode 100644 index 0000000..646120f --- /dev/null +++ b/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp @@ -0,0 +1,19 @@ +#include "AptabaseBlueprintLibrary.h" + +#include + +#include "Aptabase.h" +#include "AptabaseAnalyticsProvider.h" + +void UAptabaseBlueprintLibrary::TrackError(const FString& ErrorMessage, const FString& ErrorType, const FString& StackTrace, bool bFatal) +{ + // The default provider may be a Multicast provider or another SDK. Resolve our + // own module's instance instead of casting an arbitrary IAnalyticsProvider. + if (const FAptabaseModule* Module = FModuleManager::GetModulePtr(TEXT("Aptabase"))) + { + if (Module->AnalyticsProvider.IsValid()) + { + StaticCastSharedPtr(Module->AnalyticsProvider)->TrackError(ErrorType, ErrorMessage, StackTrace, bFatal); + } + } +} diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp new file mode 100644 index 0000000..32c4db4 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp @@ -0,0 +1,123 @@ +#include "AptabaseErrorDispatcher.h" + +#include +#include +#include +#include + +#include "AptabaseLog.h" + +FAptabaseErrorDispatcher::~FAptabaseErrorDispatcher() +{ + if (ActiveRequest.IsValid()) + { + ActiveRequest->OnProcessRequestComplete().Unbind(); + ActiveRequest->CancelRequest(); + } +} + +void FAptabaseErrorDispatcher::StartSession(const FAptabaseErrorContext& Context) +{ + Queue.StartSession(Context); +} + +void FAptabaseErrorDispatcher::EndSession() +{ + Queue.EndSession(); +} + +void FAptabaseErrorDispatcher::TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic) +{ + if (!Queue.Enqueue(ErrorType, Message, StackTrace, bFatal, bAutomatic) || bFlushScheduled.exchange(true)) + { + return; + } + + // Coalesce worker-thread log bursts into one game-thread task. Never start HTTP + // inside a log callback, which could recursively generate more log messages. + TWeakPtr WeakThis = AsShared(); + AsyncTask( + ENamedThreads::GameThread, + [WeakThis]() + { + if (const auto Dispatcher = WeakThis.Pin()) + { + Dispatcher->bFlushScheduled = false; + Dispatcher->Flush(); + } + } + ); +} + +void FAptabaseErrorDispatcher::Flush() +{ + check(IsInGameThread()); + if (bFlushing) + { + bFlushAgain = true; + return; + } + Batch = Queue.TakeBatch(); + BatchIndex = 0; + bFlushing = !Batch.IsEmpty(); + if (bFlushing) + { + SendNext(); + } +} + +void FAptabaseErrorDispatcher::SendNext() +{ + if (!Batch.IsValidIndex(BatchIndex)) + { + Batch.Empty(); + bFlushing = false; + if (bFlushAgain) + { + bFlushAgain = false; + Flush(); + } + return; + } + + const FAptabaseErrorReport& Report = Batch[BatchIndex]; + FString Body; + FJsonSerializer::Serialize(Report.ToJsonObject(), TJsonWriterFactory<>::Create(&Body)); + const FHttpRequestRef Request = FHttpModule::Get().CreateRequest(); + Request->SetURL(Report.Context.ApiUrl + TEXT("/api/v0/error")); + Request->SetVerb(TEXT("POST")); + Request->SetHeader(TEXT("App-Key"), Report.Context.AppKey); + Request->SetHeader(TEXT("Content-Type"), TEXT("application/json")); + Request->SetContentAsString(Body); + Request->OnProcessRequestComplete().BindSP(AsShared(), &FAptabaseErrorDispatcher::OnComplete); + ActiveRequest = Request; + if (!Request->ProcessRequest() && ActiveRequest == Request) + { + // Some HTTP implementations fail to start without invoking the delegate. + Request->OnProcessRequestComplete().Unbind(); + OnComplete(Request, nullptr, false); + } +} + +void FAptabaseErrorDispatcher::OnComplete(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bWasSuccessful) +{ + if (Request != ActiveRequest) + { + return; + } + const int32 ResponseCode = Response.IsValid() ? Response->GetResponseCode() : 0; + Queue.Complete(Batch[BatchIndex], bWasSuccessful, ResponseCode); + if (!bWasSuccessful || ResponseCode < 200 || ResponseCode >= 300) + { + UE_LOG( + LogAptabase, + Warning, + TEXT("Error report request failed (HTTP %d). %s"), + ResponseCode, + FAptabaseErrorQueue::ShouldRetry(bWasSuccessful, ResponseCode) ? TEXT("Will retry on a later flush.") : TEXT("Report discarded.") + ); + } + ActiveRequest.Reset(); + ++BatchIndex; + SendNext(); +} diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.h b/Source/Aptabase/Private/AptabaseErrorDispatcher.h new file mode 100644 index 0000000..0016c3e --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.h @@ -0,0 +1,29 @@ +#pragma once + +#include + +#include "AptabaseErrorQueue.h" +#include + +/** Captures on any thread; all HTTP work and lifecycle operations run on the game thread. */ +class FAptabaseErrorDispatcher : public TSharedFromThis +{ +public: + ~FAptabaseErrorDispatcher(); + void StartSession(const FAptabaseErrorContext& Context); + void EndSession(); + void TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic = false); + void Flush(); + +private: + void SendNext(); + void OnComplete(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bWasSuccessful); + + FAptabaseErrorQueue Queue; + TArray Batch; + int32 BatchIndex = 0; + FHttpRequestPtr ActiveRequest; + std::atomic bFlushScheduled{false}; + bool bFlushing = false; + bool bFlushAgain = false; +}; diff --git a/Source/Aptabase/Private/AptabaseErrorLog.cpp b/Source/Aptabase/Private/AptabaseErrorLog.cpp new file mode 100644 index 0000000..ba14282 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorLog.cpp @@ -0,0 +1,36 @@ +#include "AptabaseErrorLog.h" + +#include + +FAptabaseErrorLog::FAptabaseErrorLog(TSharedRef InDispatcher) : Dispatcher(InDispatcher) +{ + if (GLog) + { + GLog->AddOutputDevice(this); + } +} + +FAptabaseErrorLog::~FAptabaseErrorLog() +{ + if (GLog) + { + GLog->RemoveOutputDevice(this); + } +} + +void FAptabaseErrorLog::Serialize(const TCHAR* Message, ELogVerbosity::Type Verbosity, const FName& Category) +{ + // Ignore transport diagnostics as well as our own logs to avoid reporting a + // failure to send an error as another error. Warnings and normal logs are noise. + if ((Verbosity != ELogVerbosity::Error && Verbosity != ELogVerbosity::Fatal) || Category == FName(TEXT("LogAptabase")) || Category == FName(TEXT("LogHttp"))) + { + return; + } + static thread_local bool bReporting = false; + if (bReporting) + { + return; + } + TGuardValue Guard(bReporting, true); + Dispatcher->TrackError(Category.ToString(), Message ? Message : TEXT(""), TEXT(""), Verbosity == ELogVerbosity::Fatal, true); +} diff --git a/Source/Aptabase/Private/AptabaseErrorLog.h b/Source/Aptabase/Private/AptabaseErrorLog.h new file mode 100644 index 0000000..42c36c0 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorLog.h @@ -0,0 +1,19 @@ +#pragma once + +#include + +#include "AptabaseErrorDispatcher.h" + +/** Opt-in capture of engine error logs. Does not install native crash/signal handlers. */ +class FAptabaseErrorLog final : public FOutputDevice +{ +public: + explicit FAptabaseErrorLog(TSharedRef InDispatcher); + virtual ~FAptabaseErrorLog() override; + virtual void Serialize(const TCHAR* Message, ELogVerbosity::Type Verbosity, const FName& Category) override; + virtual bool CanBeUsedOnAnyThread() const override { return true; } + virtual bool CanBeUsedOnMultipleThreads() const override { return true; } + +private: + TSharedRef Dispatcher; +}; diff --git a/Source/Aptabase/Private/AptabaseErrorQueue.cpp b/Source/Aptabase/Private/AptabaseErrorQueue.cpp new file mode 100644 index 0000000..97b921c --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorQueue.cpp @@ -0,0 +1,68 @@ +#include "AptabaseErrorQueue.h" + +#include + +void FAptabaseErrorQueue::StartSession(const FAptabaseErrorContext& InContext) +{ + FScopeLock Lock(&Mutex); + Context = InContext; + Seen.Empty(); + bActive = true; +} + +void FAptabaseErrorQueue::EndSession() +{ + FScopeLock Lock(&Mutex); + bActive = false; +} + +bool FAptabaseErrorQueue::Enqueue(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic) +{ + FScopeLock Lock(&Mutex); + if (!bActive || Outstanding >= MaxPendingReports || Seen.Num() >= MaxUniqueErrorsPerSession) + { + return false; + } + + FAptabaseErrorReport Report = FAptabaseErrorReport::Create(ErrorType, Message, StackTrace, bFatal, bAutomatic, Context); + const uint64 Fingerprint = Report.GetFingerprint(); + if (Seen.Contains(Fingerprint)) + { + return false; + } + Seen.Add(Fingerprint); + Pending.Add(MoveTemp(Report)); + ++Outstanding; + return true; +} + +TArray FAptabaseErrorQueue::TakeBatch() +{ + FScopeLock Lock(&Mutex); + TArray Batch = MoveTemp(Pending); + Pending.Empty(); + return Batch; +} + +void FAptabaseErrorQueue::Complete(const FAptabaseErrorReport& Report, bool bWasSuccessful, int32 ResponseCode) +{ + FScopeLock Lock(&Mutex); + if (ShouldRetry(bWasSuccessful, ResponseCode)) + { + Pending.Add(Report); + } + else + { + --Outstanding; + } +} + +bool FAptabaseErrorQueue::ShouldRetry(bool bWasSuccessful, int32 ResponseCode) +{ + // The server deliberately returns 403 for an exhausted monthly quota. + if (ResponseCode >= 400 && ResponseCode < 500 && ResponseCode != 408 && ResponseCode != 429) + { + return false; + } + return !bWasSuccessful || ResponseCode <= 0 || ResponseCode == 408 || ResponseCode == 429 || ResponseCode >= 500; +} diff --git a/Source/Aptabase/Private/AptabaseErrorQueue.h b/Source/Aptabase/Private/AptabaseErrorQueue.h new file mode 100644 index 0000000..22ab323 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorQueue.h @@ -0,0 +1,28 @@ +#pragma once + +#include + +#include "AptabaseErrorReport.h" + +/** Thread-safe capture and retry state. In-flight reports count towards the capacity. */ +class FAptabaseErrorQueue +{ +public: + static constexpr int32 MaxPendingReports = 25; + static constexpr int32 MaxUniqueErrorsPerSession = 100; + + void StartSession(const FAptabaseErrorContext& InContext); + void EndSession(); + bool Enqueue(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic); + TArray TakeBatch(); + void Complete(const FAptabaseErrorReport& Report, bool bWasSuccessful, int32 ResponseCode); + static bool ShouldRetry(bool bWasSuccessful, int32 ResponseCode); + +private: + FCriticalSection Mutex; + FAptabaseErrorContext Context; + TArray Pending; + TSet Seen; + int32 Outstanding = 0; + bool bActive = false; +}; diff --git a/Source/Aptabase/Private/AptabaseErrorReport.cpp b/Source/Aptabase/Private/AptabaseErrorReport.cpp new file mode 100644 index 0000000..efeb82f --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorReport.cpp @@ -0,0 +1,59 @@ +#include "AptabaseErrorReport.h" + +#include + +FAptabaseErrorReport FAptabaseErrorReport::Create(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic, const FAptabaseErrorContext& Context) +{ + FAptabaseErrorReport Report; + const FString NormalizedType = ErrorType.TrimStartAndEnd(); + Report.ErrorType = NormalizedType.IsEmpty() ? TEXT("Error") : NormalizedType.Left(100); + Report.ErrorMessage = (FString(bFatal ? TEXT("Fatal ") : TEXT("")) + Report.ErrorType + TEXT(": ") + Message).Left(5000); + Report.StackTrace = StackTrace.Left(10000); + Report.Timestamp = FDateTime::UtcNow().ToIso8601(); + Report.Severity = bFatal ? TEXT("fatal") : TEXT("error"); + Report.Kind = bFatal ? TEXT("crash") : (bAutomatic ? TEXT("unhandled") : TEXT("handled")); + Report.Context = Context; + Report.Context.SessionId = Context.SessionId.Left(100); + Report.Context.OsName = Context.OsName.Left(30); + Report.Context.OsVersion = Context.OsVersion.Left(100); + Report.Context.AppVersion = Context.AppVersion.Left(50); + Report.Context.SdkVersion = Context.SdkVersion.Left(40); + return Report; +} + +TSharedRef FAptabaseErrorReport::ToJsonObject() const +{ + TSharedRef Json = MakeShared(); + Json->SetStringField(TEXT("errorType"), ErrorType); + Json->SetStringField(TEXT("errorMessage"), ErrorMessage); + if (!StackTrace.IsEmpty()) + { + Json->SetStringField(TEXT("stackTrace"), StackTrace); + } + Json->SetStringField(TEXT("timestamp"), Timestamp); + Json->SetStringField(TEXT("platform"), TEXT("Unreal")); + Json->SetStringField(TEXT("sessionId"), Context.SessionId); + Json->SetStringField(TEXT("osName"), Context.OsName); + Json->SetStringField(TEXT("osVersion"), Context.OsVersion); + Json->SetStringField(TEXT("appVersion"), Context.AppVersion); + Json->SetStringField(TEXT("sdkVersion"), Context.SdkVersion); + Json->SetBoolField(TEXT("isDebug"), Context.bIsDebug); + Json->SetStringField(TEXT("severity"), Severity); + Json->SetStringField(TEXT("kind"), Kind); + return Json; +} + +uint64 FAptabaseErrorReport::GetFingerprint() const +{ + // FNV-1a keeps the deduplication set small even when reports carry large stacks. + uint64 Hash = 14695981039346656037ull; + for (const FString* Field : {&Kind, &ErrorType, &ErrorMessage, &StackTrace}) + { + for (TCHAR Character : *Field) + { + Hash = (Hash ^ static_cast(Character)) * 1099511628211ull; + } + Hash = (Hash ^ 0xffull) * 1099511628211ull; + } + return Hash; +} diff --git a/Source/Aptabase/Private/AptabaseErrorReport.h b/Source/Aptabase/Private/AptabaseErrorReport.h new file mode 100644 index 0000000..f2eca43 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorReport.h @@ -0,0 +1,35 @@ +#pragma once + +#include + +class FJsonObject; + +/** Context copied on the game thread at session start; safe to use from log callbacks. */ +struct FAptabaseErrorContext +{ + FString SessionId; + FString OsName; + FString OsVersion; + FString AppVersion; + FString SdkVersion; + bool bIsDebug = false; + FString ApiUrl; + FString AppKey; +}; + +/** One immutable POST /api/v0/error body, enriched and limited at capture time. */ +struct FAptabaseErrorReport +{ + static FAptabaseErrorReport Create(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic, const FAptabaseErrorContext& Context); + + FString ErrorType; + FString ErrorMessage; + FString StackTrace; + FString Timestamp; + FString Severity; + FString Kind; + FAptabaseErrorContext Context; + + TSharedRef ToJsonObject() const; + uint64 GetFingerprint() const; +}; diff --git a/Source/Aptabase/Private/AptabaseSettings.h b/Source/Aptabase/Private/AptabaseSettings.h index 4c94374..75e49d8 100644 --- a/Source/Aptabase/Private/AptabaseSettings.h +++ b/Source/Aptabase/Private/AptabaseSettings.h @@ -56,6 +56,12 @@ class APTABASE_API UAptabaseSettings : public UDeveloperSettings */ UPROPERTY(Config, EditAnywhere, Category = "Aptabase Analytics", meta = (Unit = "s")) float DebugSendInterval = 2.0f; + /** + * Automatically report engine Error/Fatal log messages during an active session. + * Warnings and Aptabase/HTTP diagnostics are excluded. Native crashes are not intercepted. + */ + UPROPERTY(Config, EditAnywhere, Category = "Aptabase Error Reporting") + bool bEnableErrorLogging = false; private: // Begin UDeveloperSettings interface diff --git a/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp new file mode 100644 index 0000000..c56c501 --- /dev/null +++ b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp @@ -0,0 +1,231 @@ +#if WITH_DEV_AUTOMATION_TESTS + +#include +#include +#include + +#include "AptabaseErrorQueue.h" + +namespace +{ + FAptabaseErrorContext TestContext() + { + FAptabaseErrorContext Context; + Context.SessionId = TEXT("123456789012345678"); + Context.OsName = TEXT("Mac"); + Context.OsVersion = TEXT("15.0"); + Context.AppVersion = TEXT("1.2.3"); + Context.SdkVersion = TEXT("aptabase-unreal@0.3.0"); + Context.bIsDebug = true; + Context.ApiUrl = TEXT("http://localhost:3000"); + Context.AppKey = TEXT("A-DEV-1234567890"); + return Context; + } +} // namespace + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorPayloadTest, "Aptabase.Errors.Payload", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseErrorPayloadTest::RunTest(const FString& Parameters) +{ + const FAptabaseErrorReport Report = FAptabaseErrorReport::Create(TEXT("SaveError"), TEXT("Disk full"), TEXT("SaveGame\nMain"), false, false, TestContext()); + const auto Json = Report.ToJsonObject(); + TestEqual(TEXT("Error type"), Json->GetStringField(TEXT("errorType")), FString(TEXT("SaveError"))); + TestEqual(TEXT("Message"), Json->GetStringField(TEXT("errorMessage")), FString(TEXT("SaveError: Disk full"))); + TestEqual(TEXT("Original stack"), Json->GetStringField(TEXT("stackTrace")), FString(TEXT("SaveGame\nMain"))); + TestEqual(TEXT("SDK platform"), Json->GetStringField(TEXT("platform")), FString(TEXT("Unreal"))); + TestEqual(TEXT("Session"), Json->GetStringField(TEXT("sessionId")), TestContext().SessionId); + TestEqual(TEXT("OS"), Json->GetStringField(TEXT("osName")), TestContext().OsName); + TestEqual(TEXT("OS version"), Json->GetStringField(TEXT("osVersion")), TestContext().OsVersion); + TestEqual(TEXT("App version"), Json->GetStringField(TEXT("appVersion")), TestContext().AppVersion); + TestEqual(TEXT("SDK version"), Json->GetStringField(TEXT("sdkVersion")), TestContext().SdkVersion); + TestTrue(TEXT("Debug flag"), Json->GetBoolField(TEXT("isDebug"))); + TestEqual(TEXT("Handled severity"), Json->GetStringField(TEXT("severity")), FString(TEXT("error"))); + TestEqual(TEXT("Handled kind"), Json->GetStringField(TEXT("kind")), FString(TEXT("handled"))); + TestFalse(TEXT("Credentials are not serialized"), Json->HasField(TEXT("appKey"))); + TestFalse(TEXT("No event properties envelope"), Json->HasField(TEXT("systemProps"))); + FDateTime Timestamp; + TestTrue(TEXT("ISO timestamp"), FDateTime::ParseIso8601(*Json->GetStringField(TEXT("timestamp")), Timestamp)); + + const auto Fatal = FAptabaseErrorReport::Create(TEXT("LoadError"), TEXT("Missing assets"), TEXT(""), true, false, TestContext()).ToJsonObject(); + TestEqual(TEXT("Fatal severity"), Fatal->GetStringField(TEXT("severity")), FString(TEXT("fatal"))); + TestEqual(TEXT("Fatal kind"), Fatal->GetStringField(TEXT("kind")), FString(TEXT("crash"))); + TestEqual(TEXT("Fatal prefix"), Fatal->GetStringField(TEXT("errorMessage")), FString(TEXT("Fatal LoadError: Missing assets"))); + TestFalse(TEXT("Missing stack omitted"), Fatal->HasField(TEXT("stackTrace"))); + const auto Automatic = FAptabaseErrorReport::Create(TEXT("LogGame"), TEXT("Failed"), TEXT(""), false, true, TestContext()); + TestEqual(TEXT("Log error kind"), Automatic.Kind, FString(TEXT("unhandled"))); + return true; +} + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorLimitsTest, "Aptabase.Errors.FieldLimits", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseErrorLimitsTest::RunTest(const FString& Parameters) +{ + const FString LongValue = FString::ChrN(11000, TCHAR('x')); + auto Context = TestContext(); + Context.SessionId = Context.OsName = Context.OsVersion = Context.AppVersion = Context.SdkVersion = LongValue; + const auto Json = FAptabaseErrorReport::Create(LongValue, LongValue, LongValue, true, false, Context).ToJsonObject(); + TestEqual(TEXT("Message limit"), Json->GetStringField(TEXT("errorMessage")).Len(), 5000); + TestEqual(TEXT("Type limit"), Json->GetStringField(TEXT("errorType")).Len(), 100); + TestEqual(TEXT("Stack limit"), Json->GetStringField(TEXT("stackTrace")).Len(), 10000); + TestEqual(TEXT("Session limit"), Json->GetStringField(TEXT("sessionId")).Len(), 100); + TestEqual(TEXT("OS name limit"), Json->GetStringField(TEXT("osName")).Len(), 30); + TestEqual(TEXT("OS version limit"), Json->GetStringField(TEXT("osVersion")).Len(), 100); + TestEqual(TEXT("App version limit"), Json->GetStringField(TEXT("appVersion")).Len(), 50); + TestEqual(TEXT("SDK version limit"), Json->GetStringField(TEXT("sdkVersion")).Len(), 40); + const auto Empty = FAptabaseErrorReport::Create(TEXT(" \t\n"), TEXT(""), TEXT(""), false, false, Context); + TestEqual(TEXT("Whitespace type fallback"), Empty.ErrorType, FString(TEXT("Error"))); + TestEqual(TEXT("Empty message is still a valid report"), Empty.ErrorMessage, FString(TEXT("Error: "))); + const auto Padded = FAptabaseErrorReport::Create(FString::ChrN(101, TCHAR(' ')) + TEXT("Error"), TEXT("test"), TEXT(""), false, false, Context); + TestEqual(TEXT("Trim before truncating so the type remains valid"), Padded.ErrorType, FString(TEXT("Error"))); + return true; +} + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorRetryTest, "Aptabase.Errors.Retry", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseErrorRetryTest::RunTest(const FString& Parameters) +{ + for (int32 Code : {0, 408, 429, 500, 503}) + { + FAptabaseErrorQueue Queue; + Queue.StartSession(TestContext()); + Queue.Enqueue(TEXT("NetworkError"), TEXT("Offline"), TEXT("original stack"), false, false); + const auto Batch = Queue.TakeBatch(); + if (!TestEqual(TEXT("One initial report"), Batch.Num(), 1)) + { + return false; + } + Queue.Complete(Batch[0], Code != 0, Code); + const auto Retry = Queue.TakeBatch(); + if (!TestEqual(FString::Printf(TEXT("HTTP %d retried"), Code), Retry.Num(), 1)) + { + return false; + } + TestEqual(TEXT("Retry preserves timestamp"), Retry[0].Timestamp, Batch[0].Timestamp); + TestEqual(TEXT("Retry preserves stack"), Retry[0].StackTrace, Batch[0].StackTrace); + Queue.Complete(Retry[0], true, 202); + TestEqual(TEXT("Delivered report removed"), Queue.TakeBatch().Num(), 0); + } + for (int32 Code : {200, 202, 204, 301, 400, 401, 403, 404, 422}) + { + TestFalse(FString::Printf(TEXT("HTTP %d is terminal"), Code), FAptabaseErrorQueue::ShouldRetry(true, Code)); + } + TestFalse(TEXT("403 is terminal even if transport reports failure"), FAptabaseErrorQueue::ShouldRetry(false, 403)); + TestTrue(TEXT("Failed transport retried"), FAptabaseErrorQueue::ShouldRetry(false, 200)); + return true; +} + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorCapacityTest, "Aptabase.Errors.CapacityAndDeduplication", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseErrorCapacityTest::RunTest(const FString& Parameters) +{ + FAptabaseErrorQueue Queue; + Queue.StartSession(TestContext()); + TestTrue(TEXT("First occurrence accepted"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), false, false)); + TestFalse(TEXT("Duplicate suppressed"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), false, false)); + TestTrue(TEXT("Fatal has separate identity"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), true, false)); + TestTrue(TEXT("Automatic has separate identity"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), false, true)); + TestTrue(TEXT("Different stack has separate identity"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("other stack"), false, false)); + for (int32 Index = 4; Index < FAptabaseErrorQueue::MaxPendingReports; ++Index) + { + TestTrue(TEXT("Queue space available"), Queue.Enqueue(TEXT("Error"), FString::FromInt(Index), TEXT(""), false, false)); + } + const auto Batch = Queue.TakeBatch(); + TestEqual(TEXT("Full batch"), Batch.Num(), 25); + TestFalse(TEXT("In-flight reports count towards capacity"), Queue.Enqueue(TEXT("Error"), TEXT("Overflow"), TEXT(""), false, false)); + for (const auto& Report : Batch) + { + Queue.Complete(Report, false, 0); + } + const auto Retries = Queue.TakeBatch(); + TestEqual(TEXT("All original reports retained after failure"), Retries.Num(), 25); + for (const auto& Report : Retries) + { + Queue.Complete(Report, true, 202); + } + TestTrue(TEXT("Overflow can be reported once capacity is available"), Queue.Enqueue(TEXT("Error"), TEXT("Overflow"), TEXT(""), false, false)); + return true; +} + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorSessionTest, "Aptabase.Errors.SessionLifecycle", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseErrorSessionTest::RunTest(const FString& Parameters) +{ + FAptabaseErrorQueue Queue; + TestFalse(TEXT("No capture before session"), Queue.Enqueue(TEXT("Error"), TEXT("test"), TEXT(""), false, false)); + Queue.StartSession(TestContext()); + for (int32 Index = 0; Index < FAptabaseErrorQueue::MaxUniqueErrorsPerSession; ++Index) + { + TestTrue(TEXT("Unique report accepted"), Queue.Enqueue(TEXT("Error"), FString::FromInt(Index), TEXT(""), false, false)); + const auto Batch = Queue.TakeBatch(); + if (Batch.Num() != 1) + { + return false; + } + Queue.Complete(Batch[0], true, 202); + } + TestFalse(TEXT("Session cap applies after delivery"), Queue.Enqueue(TEXT("Error"), TEXT("Over cap"), TEXT(""), false, false)); + Queue.EndSession(); + TestFalse(TEXT("No capture after session"), Queue.Enqueue(TEXT("Error"), TEXT("Stopped"), TEXT(""), false, false)); + Queue.StartSession(TestContext()); + TestTrue(TEXT("New session resets deduplication"), Queue.Enqueue(TEXT("Error"), TEXT("0"), TEXT(""), false, false)); + const auto OldBatch = Queue.TakeBatch(); + if (OldBatch.Num() != 1) + { + return false; + } + Queue.EndSession(); + auto NewContext = TestContext(); + NewContext.SessionId = TEXT("new session"); + NewContext.AppKey = TEXT("A-DEV-9999999999"); + NewContext.ApiUrl = TEXT("https://another-host.example"); + NewContext.AppVersion = TEXT("2.0"); + Queue.StartSession(NewContext); + Queue.Complete(OldBatch[0], true, 429); + const auto Retry = Queue.TakeBatch(); + if (!TestEqual(TEXT("Previous session report retried"), Retry.Num(), 1)) + { + return false; + } + TestEqual(TEXT("Original session retained"), Retry[0].Context.SessionId, TestContext().SessionId); + TestEqual(TEXT("Original app key retained"), Retry[0].Context.AppKey, TestContext().AppKey); + TestEqual(TEXT("Original host retained"), Retry[0].Context.ApiUrl, TestContext().ApiUrl); + TestEqual(TEXT("Original app version retained"), Retry[0].Context.AppVersion, TestContext().AppVersion); + return true; +} + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorThreadTest, "Aptabase.Errors.ConcurrentCapture", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseErrorThreadTest::RunTest(const FString& Parameters) +{ + FAptabaseErrorQueue Queue; + Queue.StartSession(TestContext()); + TArray> Workers; + for (int32 Worker = 0; Worker < 4; ++Worker) + { + Workers.Add(Async( + EAsyncExecution::Thread, + [&Queue]() + { + for (int32 Index = 0; Index < 100; ++Index) + { + Queue.Enqueue(TEXT("LogGame"), FString::FromInt(Index), TEXT(""), false, true); + } + } + )); + } + for (auto& Worker : Workers) + { + Worker.Wait(); + } + const auto Batch = Queue.TakeBatch(); + TestEqual(TEXT("Concurrent capture is bounded"), Batch.Num(), 25); + TSet Fingerprints; + for (const auto& Report : Batch) + { + Fingerprints.Add(Report.GetFingerprint()); + } + TestEqual(TEXT("Concurrent duplicates suppressed"), Fingerprints.Num(), Batch.Num()); + return true; +} + +#endif diff --git a/Source/Aptabase/Public/AptabaseBlueprintLibrary.h b/Source/Aptabase/Public/AptabaseBlueprintLibrary.h new file mode 100644 index 0000000..bf87bcd --- /dev/null +++ b/Source/Aptabase/Public/AptabaseBlueprintLibrary.h @@ -0,0 +1,22 @@ +#pragma once + +#include +#include + +#include "AptabaseBlueprintLibrary.generated.h" + +/** Aptabase-specific APIs available to both C++ and Blueprints. */ +UCLASS() +class APTABASE_API UAptabaseBlueprintLibrary : public UBlueprintFunctionLibrary +{ + GENERATED_BODY() + +public: + /** + * Reports a handled error, or a fatal error when the application cannot recover. + * Requires an active Aptabase session. Call on the game thread. + * Supply the original stack trace if available; an empty stack is omitted. + */ + UFUNCTION(BlueprintCallable, Category = "Analytics|Aptabase", meta = (AdvancedDisplay = "StackTrace,bFatal")) + static void TrackError(const FString& ErrorMessage, const FString& ErrorType = TEXT("Error"), const FString& StackTrace = TEXT(""), bool bFatal = false); +}; diff --git a/llms.txt b/llms.txt index f237063..b6e128d 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ # Aptabase Unreal Engine SDK -> Unreal Engine plugin for Aptabase — open-source, privacy-first analytics for games and apps. Tracks custom events with string and number properties. No PII collection. Supports UE 5.x on all major platforms. +> Unreal Engine plugin for Aptabase — open-source, privacy-first analytics and error reporting for games and apps. Tracks custom events with string and number properties using anonymous sessions. Error text may contain application data supplied by callers or captured from opted-in logs. Supports UE 5.x on all major platforms. ## Installation @@ -35,6 +35,7 @@ Then configure in `Project Settings → Analytics → Aptabase`: | CustomHost | FString | "" | URL for self-hosted instances (only when Host = SH) | | SendInterval | float | 60.0 | Seconds between batch flushes in Release mode | | DebugSendInterval | float | 2.0 | Seconds between batch flushes in Debug mode | +| bEnableErrorLogging | bool | false | Capture Unreal Error/Fatal logs during active sessions | If you already use another analytics provider, use the [Multicast Analytics Provider Plugin](https://docs.unrealengine.com/4.26/en-US/TestingAndOptimization/Analytics/Multicast/) to run both. @@ -73,6 +74,23 @@ Use the [Blueprint Analytics Plugin](https://docs.unrealengine.com/4.27/en-US/Te - **Record Currency Purchase** — pre-built commerce event - Other standard `IAnalyticsProvider` nodes +## Error Reporting (Beta) + +Start an Aptabase analytics session with the configured provider's `StartSession()` or the **Start Session** Blueprint node first. Add `"Aptabase"` to your C++ module dependencies. + +```cpp +#include "AptabaseBlueprintLibrary.h" + +UAptabaseBlueprintLibrary::TrackError(TEXT("Save failed"), TEXT("SaveError")); +UAptabaseBlueprintLibrary::TrackError(TEXT("Cannot continue"), TEXT("LoadError"), TEXT("original stack"), true); +``` + +Call on the game thread. The **Track Error** Blueprint node under **Analytics → Aptabase** exposes the same API. Manual reports are `handled`/`error`; setting `bFatal` gives `crash`/`fatal` without terminating the app. Stack traces are optional and must be supplied by the caller. Reports appear on the dashboard's Errors page with capture-time session, timestamp, OS, app/SDK versions, and debug mode. + +Opt in to **Enable Error Logging** in Project Settings, or set `bEnableErrorLogging=True` in `[/Script/Aptabase.AptabaseSettings]` in `Config/DefaultAptabase.ini`. Unreal Error logs become `unhandled`/`error` and Fatal logs reaching the listener become `crash`/`fatal`; the type is the log category and no stack is synthesized. Warnings and Aptabase/HTTP diagnostics are ignored. Capture ends with the session. Native crashes, signals, assertions bypassing the listener, and logs compiled out of Shipping builds are not captured; fatal delivery is best effort. + +Errors use individual `POST /api/v0/error` requests with an `App-Key` header. Network errors and HTTP 408/429/5xx are retried on later flushes; 403 quota exhaustion and other permanent failures are dropped. The queue is bounded to 25 outstanding reports with per-session deduplication and a cap of 100 unique errors. `FlushEvents()` also flushes errors. Pending reports live in memory only. + ## Platform Notes - Supports all platforms supported by Unreal Engine 5 From 28c2208faf89cd2a9a2ba72cb0178762ba4e0a6a Mon Sep 17 00:00:00 2001 From: Bogdan Ivanov Date: Thu, 10 Sep 2026 11:22:47 +0300 Subject: [PATCH 2/4] feat: report fatal errors from the engine error handler Replace the GLog Error/Fatal listener with FAptabaseCrashReporter, which hooks FCoreDelegates::OnHandleSystemError and OnShutdownAfterError, builds a crash report from GErrorHist and sends it synchronously with a 3 second timeout. Fatal errors never reach GLog at Fatal verbosity, so the listener could not classify them, and non-fatal Error logs are too noisy to report automatically. Rename the setting to bEnableCrashReporting to match the other SDKs and drop the "unhandled" kind. Use message-first parameter order internally to match the public API, spell UFUNCTION defaults as FString(TEXT("...")), revert the no-op RightChopInline clamp and its changelog claim, record the StartSession idempotency change, and document that errors outside a session are not captured. Add a parsing test for the crash report. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 5 +- Docs/testing.md | 4 +- README.md | 16 ++- .../Private/AptabaseAnalyticsProvider.cpp | 16 +-- .../Private/AptabaseAnalyticsProvider.h | 6 +- .../Private/AptabaseBlueprintLibrary.cpp | 2 +- .../Private/AptabaseCrashReporter.cpp | 124 ++++++++++++++++++ .../Aptabase/Private/AptabaseCrashReporter.h | 42 ++++++ .../Private/AptabaseErrorDispatcher.cpp | 7 +- .../Private/AptabaseErrorDispatcher.h | 4 +- Source/Aptabase/Private/AptabaseErrorLog.cpp | 36 ----- Source/Aptabase/Private/AptabaseErrorLog.h | 19 --- .../Aptabase/Private/AptabaseErrorQueue.cpp | 4 +- Source/Aptabase/Private/AptabaseErrorQueue.h | 2 +- .../Aptabase/Private/AptabaseErrorReport.cpp | 4 +- Source/Aptabase/Private/AptabaseErrorReport.h | 4 +- Source/Aptabase/Private/AptabaseSettings.h | 7 +- .../Tests/AptabaseErrorReportingTests.cpp | 82 ++++++++---- .../Public/AptabaseBlueprintLibrary.h | 2 +- llms.txt | 6 +- 20 files changed, 273 insertions(+), 119 deletions(-) create mode 100644 Source/Aptabase/Private/AptabaseCrashReporter.cpp create mode 100644 Source/Aptabase/Private/AptabaseCrashReporter.h delete mode 100644 Source/Aptabase/Private/AptabaseErrorLog.cpp delete mode 100644 Source/Aptabase/Private/AptabaseErrorLog.h diff --git a/CHANGELOG.md b/CHANGELOG.md index 35188c0..770f24d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,9 @@ ## 0.3.0 - Add `UAptabaseBlueprintLibrary::TrackError` and the **Track Error** Blueprint node for structured handled and fatal error reports. -- Add opt-in **Enable Error Logging** to report Unreal Error/Fatal log messages during active sessions. +- Add opt-in **Enable Crash Reporting** to report fatal errors (assertion failures, `Fatal` logs, crashes routed through the engine's error handler) during active sessions, sent best-effort from the error handler. - Include capture-time session, timestamp, OS, app version, SDK version, severity, kind, and debug mode; truncate fields to the server limits. - Send errors individually to `/api/v0/error`, retry network failures and HTTP 408/429/5xx on later flushes, and discard permanent rejections including HTTP 403 quota exhaustion. - Bound outstanding reports to 25 and deduplicate up to 100 unique errors per session. -- Clean up log subscriptions and HTTP callbacks at shutdown; fix flushing event batches with fewer than 25 events. +- `StartSession()` now returns `true` without starting a new session when one is already active; previously it replaced the session ID and restarted the flush timer. +- Cancel in-flight event requests and unbind their callbacks when the provider is destroyed; guard against responses without a body. diff --git a/Docs/testing.md b/Docs/testing.md index 383e75d..5954855 100644 --- a/Docs/testing.md +++ b/Docs/testing.md @@ -10,8 +10,8 @@ UnrealEditor-Cmd YourProject.uproject -unattended -NullRHI \ -TestExit="Automation Test Queue Empty" -log ``` -The tests cover the JSON contract and field limits, retry status codes, capture-time context across sessions, deduplication, in-flight queue capacity, session limits, and concurrent capture. They do not send data to Aptabase. +The tests cover the JSON contract and field limits, retry status codes, capture-time context across sessions, deduplication, in-flight queue capacity, session limits, concurrent capture, and parsing the engine's error history into a crash report. They do not send data to Aptabase. For an end-to-end check, configure a local HTTP server as the SH host and start an analytics session in Play-in-Editor. Record a normal event and call **Track Error**. Verify that the event goes to `/api/v0/events` as an array and the error goes to `/api/v0/error` as one JSON object, with `App-Key` and `Content-Type: application/json` headers. Return 202 to accept a report; repeat with 400/403 (no retry), 408/429/500 (retry on the next flush), and a disconnected server. End/start PIE and verify that pending retries retain the old session and that new reports carry the new session. -Enable **Enable Error Logging** before starting the session. Emit the same `UE_LOG(LogTemp, Error, TEXT("Test error"))` several times: only one report should arrive. Emit a Warning and verify that no report arrives. End the session and verify that subsequent error logs are not reported. Fatal logging actually terminates Unreal and is not required to test classification: use **Track Error** with **Fatal** enabled instead. +To exercise crash reporting, enable **Enable Crash Reporting**, start a session, then trigger a fatal error from a packaged or `-game` build rather than Play-in-Editor, since a fatal error terminates the whole editor: for example a Blueprint-callable test function containing `UE_LOG(LogTemp, Fatal, TEXT("Test crash"))` or `check(false)`. Verify that one request arrives at `/api/v0/error` with `kind: "crash"`, `severity: "fatal"`, the engine's description as `errorMessage` and the call stack as `stackTrace`, before the engine's crash reporter appears. Repeat with the server stopped to confirm the game still terminates normally after the 3 second timeout. Non-fatal `UE_LOG(..., Error, ...)` messages must not produce a report. diff --git a/README.md b/README.md index 6ca4f97..ce35843 100644 --- a/README.md +++ b/README.md @@ -113,22 +113,26 @@ Manual reports have severity `error` and kind `handled`. With `bFatal = true`, t Use **Track Error** under **Analytics → Aptabase**. Set **Error Message** and **Error Type**; expand the advanced pins for **Stack Trace** and **Fatal**. The node uses Aptabase's own provider instance and also works when Aptabase is configured through the Multicast provider. -### Automatic error logs +### Automatic crash reporting -Enable **Project Settings → Analytics → Aptabase → Enable Error Logging** before starting the session, or add this to `Config/DefaultAptabase.ini`: +Enable **Project Settings → Analytics → Aptabase → Enable Crash Reporting** before starting the session, or add this to `Config/DefaultAptabase.ini`: ```ini [/Script/Aptabase.AptabaseSettings] -bEnableErrorLogging=True +bEnableCrashReporting=True ``` -This is off by default. While enabled, Unreal `Error` log messages are reported as `unhandled`/`error`, with the log category as the error type. `Fatal` messages reaching the log listener are classified as `crash`/`fatal`. Warnings, ordinary logs, and Aptabase/HTTP diagnostics are ignored. Automatic reports contain the log message; they do not synthesize a stack trace. Worker-thread logs are supported, and the listener is removed at session end, including Play-in-Editor sessions. +This is off by default. While enabled, fatal errors that reach the engine's error handler during an active session are reported as `crash`/`fatal`: `check` and `verify` assertion failures, `UE_LOG` messages at `Fatal` verbosity, `LowLevelFatalError`, and unhandled native exceptions or signals on platforms where the engine routes them through its error handler. The report is built from the engine's error history: the heading becomes the error type (`AssertionFailed`, `FatalError`, `UnhandledException`), the description becomes the message and the engine's call stack is included. -This listener does not intercept native crashes, assertions that bypass the log listener, or platform signals. Fatal delivery is best effort: the game thread and HTTP system must still run to send the report. Logging compiled out of a Shipping build cannot be captured. Unreal's own Crash Reporter remains available. +Non-fatal `Error` log messages are never reported automatically. Use **Track Error** for errors your game detects itself. + +Delivery of crash reports is best effort. The process is terminating, so the report is sent synchronously from the error handler with a 3 second timeout while the engine's own crash handling continues afterwards. Nothing is sent when the HTTP thread is not running (for example with `-nohttpthread`), when the crash corrupts the process beyond what the engine's handler survives, or when the device is offline; crash reports are not persisted for a later launch. Unreal's own Crash Reporter remains available and is unaffected. + +Errors and crashes that happen before `StartSession()` or after `EndSession()` are not captured. Start the session as early as your game can, for example in your `GameInstance::Init`. ### Delivery -- Reports are sent asynchronously, one per request. Capturing an error schedules an immediate send on the game thread; `FlushEvents()` and the normal send timer also flush errors. +- Manual reports are sent asynchronously, one per request. Capturing an error schedules an immediate send on the game thread; `FlushEvents()` and the normal send timer also flush errors. Crash reports bypass the queue and are sent synchronously from the error handler. - Failed requests are retained for a later flush on connection errors or HTTP 408, 429, and 5xx. Other responses, including HTTP 403 (monthly quota exhausted), are not retried. - The queue holds up to 25 outstanding reports, including requests in progress. New reports are dropped when full. Each unique combination of kind, type, message, and stack is reported once per session, up to 100 unique reports. - Retries retain their original session and system context. Reports are stored in memory only and can be lost when the process exits. Ending a session initiates a final flush without waiting for delivery. diff --git a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp index e5eda5d..987271e 100644 --- a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp +++ b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp @@ -12,9 +12,9 @@ #include #include +#include "AptabaseCrashReporter.h" #include "AptabaseData.h" #include "AptabaseErrorDispatcher.h" -#include "AptabaseErrorLog.h" #include "AptabaseLog.h" #include "AptabaseSettings.h" #include "ExtendedAnalyticsEventAttribute.h" @@ -56,7 +56,7 @@ FAptabaseAnalyticsProvider::FAptabaseAnalyticsProvider() : ErrorDispatcher(MakeS FAptabaseAnalyticsProvider::~FAptabaseAnalyticsProvider() { - ErrorLog.Reset(); + CrashReporter.Reset(); if (const UGameInstance* GameInstance = GetCurrentGameInstance()) { GameInstance->GetTimerManager().ClearTimer(BatchEventTimerHandle); @@ -68,9 +68,9 @@ FAptabaseAnalyticsProvider::~FAptabaseAnalyticsProvider() } } -void FAptabaseAnalyticsProvider::TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal) +void FAptabaseAnalyticsProvider::TrackError(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal) { - ErrorDispatcher->TrackError(ErrorType, Message, StackTrace, bFatal); + ErrorDispatcher->TrackError(Message, ErrorType, StackTrace, bFatal); } void FAptabaseAnalyticsProvider::RecordExtendedEvent(const FString& EventName, const TArray& Attributes) @@ -114,16 +114,16 @@ bool FAptabaseAnalyticsProvider::StartSession(const TArrayAppKey; ErrorDispatcher->StartSession(ErrorContext); - if (Settings->bEnableErrorLogging) + if (Settings->bEnableCrashReporting) { - ErrorLog = MakeUnique(ErrorDispatcher.ToSharedRef()); + CrashReporter = MakeUnique(ErrorContext); } return true; } void FAptabaseAnalyticsProvider::EndSession() { - ErrorLog.Reset(); + CrashReporter.Reset(); ErrorDispatcher->EndSession(); if (BatchEventTimerHandle.IsValid()) { @@ -163,7 +163,7 @@ void FAptabaseAnalyticsProvider::FlushEvents() TArray CurrentBatch; CurrentBatch.Append(EventsToProcess.Left(NumEventsPerRequest)); - EventsToProcess.RightChopInline(FMath::Min(NumEventsPerRequest, EventsToProcess.Num())); + EventsToProcess.RightChopInline(NumEventsPerRequest); SendEventsNow(CurrentBatch); } diff --git a/Source/Aptabase/Private/AptabaseAnalyticsProvider.h b/Source/Aptabase/Private/AptabaseAnalyticsProvider.h index 9688263..621c905 100644 --- a/Source/Aptabase/Private/AptabaseAnalyticsProvider.h +++ b/Source/Aptabase/Private/AptabaseAnalyticsProvider.h @@ -8,7 +8,7 @@ struct FExtendedAnalyticsEventAttribute; class FAptabaseErrorDispatcher; -class FAptabaseErrorLog; +class FAptabaseCrashReporter; /** * Implementation of Aptabase Analytics provider @@ -18,7 +18,7 @@ class FAptabaseAnalyticsProvider final : public IAnalyticsProvider public: FAptabaseAnalyticsProvider(); virtual ~FAptabaseAnalyticsProvider() override; - void TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal); + void TrackError(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal); /** * Overload for RecordEvent that takes an array of ExtendedAttributes @@ -78,6 +78,6 @@ class FAptabaseAnalyticsProvider final : public IAnalyticsProvider */ TArray DefaultEventAttributes; TSharedPtr ErrorDispatcher; - TUniquePtr ErrorLog; + TUniquePtr CrashReporter; TArray EventRequests; }; diff --git a/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp b/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp index 646120f..8094887 100644 --- a/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp +++ b/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp @@ -13,7 +13,7 @@ void UAptabaseBlueprintLibrary::TrackError(const FString& ErrorMessage, const FS { if (Module->AnalyticsProvider.IsValid()) { - StaticCastSharedPtr(Module->AnalyticsProvider)->TrackError(ErrorType, ErrorMessage, StackTrace, bFatal); + StaticCastSharedPtr(Module->AnalyticsProvider)->TrackError(ErrorMessage, ErrorType, StackTrace, bFatal); } } } diff --git a/Source/Aptabase/Private/AptabaseCrashReporter.cpp b/Source/Aptabase/Private/AptabaseCrashReporter.cpp new file mode 100644 index 0000000..288c4a6 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseCrashReporter.cpp @@ -0,0 +1,124 @@ +#include "AptabaseCrashReporter.h" + +#include +#include +#include +#include +#include +#include +#include +#include + +FAptabaseCrashReporter::FAptabaseCrashReporter(const FAptabaseErrorContext& InContext) : Context(InContext) +{ + // Loading a module from inside the error handler is not safe, so make sure HTTP is loaded now. + // The events path loads it lazily on the first flush, which may not have happened yet. + FHttpModule::Get(); + // Both delegates can fire for the same failure; whichever comes first sends the report. + SystemErrorHandle = FCoreDelegates::OnHandleSystemError.AddRaw(this, &FAptabaseCrashReporter::OnFatalError); + ShutdownAfterErrorHandle = FCoreDelegates::OnShutdownAfterError.AddRaw(this, &FAptabaseCrashReporter::OnFatalError); +} + +FAptabaseCrashReporter::~FAptabaseCrashReporter() +{ + FCoreDelegates::OnHandleSystemError.Remove(SystemErrorHandle); + FCoreDelegates::OnShutdownAfterError.Remove(ShutdownAfterErrorHandle); +} + +FAptabaseErrorReport FAptabaseCrashReporter::CreateReport(const TCHAR* ErrorHistory, const FAptabaseErrorContext& InContext) +{ + FString History = FString(ErrorHistory ? ErrorHistory : TEXT("")).Replace(TEXT("\r\n"), TEXT("\n")).TrimStartAndEnd(); + + // The engine writes the description, a blank line, then the call stack. Fall back to the first + // line that looks like a stack frame when the blank line is missing. + FString Message = History; + FString StackTrace; + int32 Split = History.Find(TEXT("\n\n")); + if (Split == INDEX_NONE) + { + static const TCHAR* const FrameMarkers[] = {TEXT("\n0x"), TEXT("\n[Callstack]")}; + for (const TCHAR* Marker : FrameMarkers) + { + const int32 MarkerIndex = History.Find(Marker); + if (MarkerIndex != INDEX_NONE && (Split == INDEX_NONE || MarkerIndex < Split)) + { + Split = MarkerIndex; + } + } + } + if (Split != INDEX_NONE) + { + Message = History.Left(Split).TrimEnd(); + StackTrace = History.Mid(Split).TrimStart(); + } + + // "Fatal error: [File:...] [Line: 12] \nMessage" -> type "FatalError", message "[File:...] [Line: 12] \nMessage". + FString ErrorType = TEXT("FatalError"); + int32 Colon = INDEX_NONE; + if (Message.FindChar(TEXT(':'), Colon) && Colon > 0 && Colon <= 60) + { + const FString Heading = Message.Left(Colon); + if (!Heading.Contains(TEXT("\n")) && !Heading.Contains(TEXT("["))) + { + TArray Words; + Heading.ParseIntoArrayWS(Words); + ErrorType.Reset(); + for (FString& Word : Words) + { + Word[0] = FChar::ToUpper(Word[0]); + ErrorType += Word; + } + Message = Message.Mid(Colon + 1).TrimStart(); + } + } + if (Message.IsEmpty()) + { + Message = TEXT("Fatal error without details"); + } + + return FAptabaseErrorReport::Create(Message, ErrorType, StackTrace, true, InContext); +} + +void FAptabaseCrashReporter::OnFatalError() +{ + // OnShutdownAfterError can run before the error text exists; leave the flag clear so a later + // delegate with details still reports. + if (GErrorHist[0] == 0 || bReported.exchange(true)) + { + return; + } + + // Do not log, assert or touch the game thread from here: the engine is inside its error handler. + if (!FModuleManager::Get().IsModuleLoaded(TEXT("HTTP"))) + { + return; + } + + const FAptabaseErrorReport Report = CreateReport(GErrorHist, Context); + FString Body; + FJsonSerializer::Serialize(Report.ToJsonObject(), TJsonWriterFactory<>::Create(&Body)); + + const FHttpRequestRef Request = FHttpModule::Get().CreateRequest(); + Request->SetURL(Context.ApiUrl + TEXT("/api/v0/error")); + Request->SetVerb(TEXT("POST")); + Request->SetHeader(TEXT("App-Key"), Context.AppKey); + Request->SetHeader(TEXT("Content-Type"), TEXT("application/json")); + Request->SetContentAsString(Body); + Request->SetTimeout(SendTimeoutSeconds); + if (!Request->ProcessRequest()) + { + return; + } + + // Requests are processed on the HTTP thread, which keeps running while this thread waits. + // The completion delegate would only run on the game thread, so poll the status instead. + const double Deadline = FPlatformTime::Seconds() + SendTimeoutSeconds; + while (Request->GetStatus() == EHttpRequestStatus::Processing && FPlatformTime::Seconds() < Deadline) + { + FPlatformProcess::Sleep(0.01f); + } + if (Request->GetStatus() == EHttpRequestStatus::Processing) + { + Request->CancelRequest(); + } +} diff --git a/Source/Aptabase/Private/AptabaseCrashReporter.h b/Source/Aptabase/Private/AptabaseCrashReporter.h new file mode 100644 index 0000000..371c726 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseCrashReporter.h @@ -0,0 +1,42 @@ +#pragma once + +#include +#include + +#include "AptabaseErrorReport.h" +#include + +/** + * Opt-in reporting of fatal engine errors: asserts, Fatal logs and crashes that reach the engine's + * error handler. Unreal never delivers these through GLog at Fatal verbosity and terminates the + * process right after, so the report is built from GErrorHist and sent synchronously from the + * error handler with a short timeout. Best effort only: the request is processed by the HTTP + * thread while the crashing thread waits, and nothing is sent if that thread is not running. + */ +class FAptabaseCrashReporter final +{ +public: + /** How long the crashing thread waits for the report to be delivered before the engine continues shutting down. */ + static constexpr float SendTimeoutSeconds = 3.0f; + + explicit FAptabaseCrashReporter(const FAptabaseErrorContext& InContext); + ~FAptabaseCrashReporter(); + + FAptabaseCrashReporter(const FAptabaseCrashReporter&) = delete; + FAptabaseCrashReporter& operator=(const FAptabaseCrashReporter&) = delete; + + /** + * Builds a crash report from the engine's error history (GErrorHist). The heading before the first + * colon ("Fatal error", "Assertion failed", "Unhandled Exception") becomes the error type; the text + * up to the first blank line is the message and the remainder is the call stack. + */ + static FAptabaseErrorReport CreateReport(const TCHAR* ErrorHistory, const FAptabaseErrorContext& Context); + +private: + void OnFatalError(); + + FAptabaseErrorContext Context; + std::atomic bReported{false}; + FDelegateHandle SystemErrorHandle; + FDelegateHandle ShutdownAfterErrorHandle; +}; diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp index 32c4db4..392bdb6 100644 --- a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp @@ -26,15 +26,14 @@ void FAptabaseErrorDispatcher::EndSession() Queue.EndSession(); } -void FAptabaseErrorDispatcher::TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic) +void FAptabaseErrorDispatcher::TrackError(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal) { - if (!Queue.Enqueue(ErrorType, Message, StackTrace, bFatal, bAutomatic) || bFlushScheduled.exchange(true)) + if (!Queue.Enqueue(Message, ErrorType, StackTrace, bFatal) || bFlushScheduled.exchange(true)) { return; } - // Coalesce worker-thread log bursts into one game-thread task. Never start HTTP - // inside a log callback, which could recursively generate more log messages. + // Coalesce bursts from any thread into one game-thread task; HTTP requests are only started there. TWeakPtr WeakThis = AsShared(); AsyncTask( ENamedThreads::GameThread, diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.h b/Source/Aptabase/Private/AptabaseErrorDispatcher.h index 0016c3e..c05f7a2 100644 --- a/Source/Aptabase/Private/AptabaseErrorDispatcher.h +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.h @@ -5,14 +5,14 @@ #include "AptabaseErrorQueue.h" #include -/** Captures on any thread; all HTTP work and lifecycle operations run on the game thread. */ +/** Queues manual reports from any thread; all HTTP work and lifecycle operations run on the game thread. */ class FAptabaseErrorDispatcher : public TSharedFromThis { public: ~FAptabaseErrorDispatcher(); void StartSession(const FAptabaseErrorContext& Context); void EndSession(); - void TrackError(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic = false); + void TrackError(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal); void Flush(); private: diff --git a/Source/Aptabase/Private/AptabaseErrorLog.cpp b/Source/Aptabase/Private/AptabaseErrorLog.cpp deleted file mode 100644 index ba14282..0000000 --- a/Source/Aptabase/Private/AptabaseErrorLog.cpp +++ /dev/null @@ -1,36 +0,0 @@ -#include "AptabaseErrorLog.h" - -#include - -FAptabaseErrorLog::FAptabaseErrorLog(TSharedRef InDispatcher) : Dispatcher(InDispatcher) -{ - if (GLog) - { - GLog->AddOutputDevice(this); - } -} - -FAptabaseErrorLog::~FAptabaseErrorLog() -{ - if (GLog) - { - GLog->RemoveOutputDevice(this); - } -} - -void FAptabaseErrorLog::Serialize(const TCHAR* Message, ELogVerbosity::Type Verbosity, const FName& Category) -{ - // Ignore transport diagnostics as well as our own logs to avoid reporting a - // failure to send an error as another error. Warnings and normal logs are noise. - if ((Verbosity != ELogVerbosity::Error && Verbosity != ELogVerbosity::Fatal) || Category == FName(TEXT("LogAptabase")) || Category == FName(TEXT("LogHttp"))) - { - return; - } - static thread_local bool bReporting = false; - if (bReporting) - { - return; - } - TGuardValue Guard(bReporting, true); - Dispatcher->TrackError(Category.ToString(), Message ? Message : TEXT(""), TEXT(""), Verbosity == ELogVerbosity::Fatal, true); -} diff --git a/Source/Aptabase/Private/AptabaseErrorLog.h b/Source/Aptabase/Private/AptabaseErrorLog.h deleted file mode 100644 index 42c36c0..0000000 --- a/Source/Aptabase/Private/AptabaseErrorLog.h +++ /dev/null @@ -1,19 +0,0 @@ -#pragma once - -#include - -#include "AptabaseErrorDispatcher.h" - -/** Opt-in capture of engine error logs. Does not install native crash/signal handlers. */ -class FAptabaseErrorLog final : public FOutputDevice -{ -public: - explicit FAptabaseErrorLog(TSharedRef InDispatcher); - virtual ~FAptabaseErrorLog() override; - virtual void Serialize(const TCHAR* Message, ELogVerbosity::Type Verbosity, const FName& Category) override; - virtual bool CanBeUsedOnAnyThread() const override { return true; } - virtual bool CanBeUsedOnMultipleThreads() const override { return true; } - -private: - TSharedRef Dispatcher; -}; diff --git a/Source/Aptabase/Private/AptabaseErrorQueue.cpp b/Source/Aptabase/Private/AptabaseErrorQueue.cpp index 97b921c..14b1c0b 100644 --- a/Source/Aptabase/Private/AptabaseErrorQueue.cpp +++ b/Source/Aptabase/Private/AptabaseErrorQueue.cpp @@ -16,7 +16,7 @@ void FAptabaseErrorQueue::EndSession() bActive = false; } -bool FAptabaseErrorQueue::Enqueue(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic) +bool FAptabaseErrorQueue::Enqueue(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal) { FScopeLock Lock(&Mutex); if (!bActive || Outstanding >= MaxPendingReports || Seen.Num() >= MaxUniqueErrorsPerSession) @@ -24,7 +24,7 @@ bool FAptabaseErrorQueue::Enqueue(const FString& ErrorType, const FString& Messa return false; } - FAptabaseErrorReport Report = FAptabaseErrorReport::Create(ErrorType, Message, StackTrace, bFatal, bAutomatic, Context); + FAptabaseErrorReport Report = FAptabaseErrorReport::Create(Message, ErrorType, StackTrace, bFatal, Context); const uint64 Fingerprint = Report.GetFingerprint(); if (Seen.Contains(Fingerprint)) { diff --git a/Source/Aptabase/Private/AptabaseErrorQueue.h b/Source/Aptabase/Private/AptabaseErrorQueue.h index 22ab323..7b47de2 100644 --- a/Source/Aptabase/Private/AptabaseErrorQueue.h +++ b/Source/Aptabase/Private/AptabaseErrorQueue.h @@ -13,7 +13,7 @@ class FAptabaseErrorQueue void StartSession(const FAptabaseErrorContext& InContext); void EndSession(); - bool Enqueue(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic); + bool Enqueue(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal); TArray TakeBatch(); void Complete(const FAptabaseErrorReport& Report, bool bWasSuccessful, int32 ResponseCode); static bool ShouldRetry(bool bWasSuccessful, int32 ResponseCode); diff --git a/Source/Aptabase/Private/AptabaseErrorReport.cpp b/Source/Aptabase/Private/AptabaseErrorReport.cpp index efeb82f..88ec911 100644 --- a/Source/Aptabase/Private/AptabaseErrorReport.cpp +++ b/Source/Aptabase/Private/AptabaseErrorReport.cpp @@ -2,7 +2,7 @@ #include -FAptabaseErrorReport FAptabaseErrorReport::Create(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic, const FAptabaseErrorContext& Context) +FAptabaseErrorReport FAptabaseErrorReport::Create(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal, const FAptabaseErrorContext& Context) { FAptabaseErrorReport Report; const FString NormalizedType = ErrorType.TrimStartAndEnd(); @@ -11,7 +11,7 @@ FAptabaseErrorReport FAptabaseErrorReport::Create(const FString& ErrorType, cons Report.StackTrace = StackTrace.Left(10000); Report.Timestamp = FDateTime::UtcNow().ToIso8601(); Report.Severity = bFatal ? TEXT("fatal") : TEXT("error"); - Report.Kind = bFatal ? TEXT("crash") : (bAutomatic ? TEXT("unhandled") : TEXT("handled")); + Report.Kind = bFatal ? TEXT("crash") : TEXT("handled"); Report.Context = Context; Report.Context.SessionId = Context.SessionId.Left(100); Report.Context.OsName = Context.OsName.Left(30); diff --git a/Source/Aptabase/Private/AptabaseErrorReport.h b/Source/Aptabase/Private/AptabaseErrorReport.h index f2eca43..cd755e7 100644 --- a/Source/Aptabase/Private/AptabaseErrorReport.h +++ b/Source/Aptabase/Private/AptabaseErrorReport.h @@ -4,7 +4,7 @@ class FJsonObject; -/** Context copied on the game thread at session start; safe to use from log callbacks. */ +/** Context copied on the game thread at session start; safe to use from any thread, including the error handler. */ struct FAptabaseErrorContext { FString SessionId; @@ -20,7 +20,7 @@ struct FAptabaseErrorContext /** One immutable POST /api/v0/error body, enriched and limited at capture time. */ struct FAptabaseErrorReport { - static FAptabaseErrorReport Create(const FString& ErrorType, const FString& Message, const FString& StackTrace, bool bFatal, bool bAutomatic, const FAptabaseErrorContext& Context); + static FAptabaseErrorReport Create(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal, const FAptabaseErrorContext& Context); FString ErrorType; FString ErrorMessage; diff --git a/Source/Aptabase/Private/AptabaseSettings.h b/Source/Aptabase/Private/AptabaseSettings.h index 75e49d8..e2c3db1 100644 --- a/Source/Aptabase/Private/AptabaseSettings.h +++ b/Source/Aptabase/Private/AptabaseSettings.h @@ -57,11 +57,12 @@ class APTABASE_API UAptabaseSettings : public UDeveloperSettings UPROPERTY(Config, EditAnywhere, Category = "Aptabase Analytics", meta = (Unit = "s")) float DebugSendInterval = 2.0f; /** - * Automatically report engine Error/Fatal log messages during an active session. - * Warnings and Aptabase/HTTP diagnostics are excluded. Native crashes are not intercepted. + * Report fatal errors (asserts, Fatal logs and crashes handled by the engine's error handler) that + * occur during an active session. The report is sent synchronously from the error handler on a + * best-effort basis. Non-fatal Error logs are never reported automatically. */ UPROPERTY(Config, EditAnywhere, Category = "Aptabase Error Reporting") - bool bEnableErrorLogging = false; + bool bEnableCrashReporting = false; private: // Begin UDeveloperSettings interface diff --git a/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp index c56c501..da044e0 100644 --- a/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp +++ b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp @@ -4,6 +4,7 @@ #include #include +#include "AptabaseCrashReporter.h" #include "AptabaseErrorQueue.h" namespace @@ -27,7 +28,7 @@ IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorPayloadTest, "Aptabase.Errors.Pay bool FAptabaseErrorPayloadTest::RunTest(const FString& Parameters) { - const FAptabaseErrorReport Report = FAptabaseErrorReport::Create(TEXT("SaveError"), TEXT("Disk full"), TEXT("SaveGame\nMain"), false, false, TestContext()); + const FAptabaseErrorReport Report = FAptabaseErrorReport::Create(TEXT("Disk full"), TEXT("SaveError"), TEXT("SaveGame\nMain"), false, TestContext()); const auto Json = Report.ToJsonObject(); TestEqual(TEXT("Error type"), Json->GetStringField(TEXT("errorType")), FString(TEXT("SaveError"))); TestEqual(TEXT("Message"), Json->GetStringField(TEXT("errorMessage")), FString(TEXT("SaveError: Disk full"))); @@ -46,13 +47,11 @@ bool FAptabaseErrorPayloadTest::RunTest(const FString& Parameters) FDateTime Timestamp; TestTrue(TEXT("ISO timestamp"), FDateTime::ParseIso8601(*Json->GetStringField(TEXT("timestamp")), Timestamp)); - const auto Fatal = FAptabaseErrorReport::Create(TEXT("LoadError"), TEXT("Missing assets"), TEXT(""), true, false, TestContext()).ToJsonObject(); + const auto Fatal = FAptabaseErrorReport::Create(TEXT("Missing assets"), TEXT("LoadError"), TEXT(""), true, TestContext()).ToJsonObject(); TestEqual(TEXT("Fatal severity"), Fatal->GetStringField(TEXT("severity")), FString(TEXT("fatal"))); TestEqual(TEXT("Fatal kind"), Fatal->GetStringField(TEXT("kind")), FString(TEXT("crash"))); TestEqual(TEXT("Fatal prefix"), Fatal->GetStringField(TEXT("errorMessage")), FString(TEXT("Fatal LoadError: Missing assets"))); TestFalse(TEXT("Missing stack omitted"), Fatal->HasField(TEXT("stackTrace"))); - const auto Automatic = FAptabaseErrorReport::Create(TEXT("LogGame"), TEXT("Failed"), TEXT(""), false, true, TestContext()); - TestEqual(TEXT("Log error kind"), Automatic.Kind, FString(TEXT("unhandled"))); return true; } @@ -63,7 +62,7 @@ bool FAptabaseErrorLimitsTest::RunTest(const FString& Parameters) const FString LongValue = FString::ChrN(11000, TCHAR('x')); auto Context = TestContext(); Context.SessionId = Context.OsName = Context.OsVersion = Context.AppVersion = Context.SdkVersion = LongValue; - const auto Json = FAptabaseErrorReport::Create(LongValue, LongValue, LongValue, true, false, Context).ToJsonObject(); + const auto Json = FAptabaseErrorReport::Create(LongValue, LongValue, LongValue, true, Context).ToJsonObject(); TestEqual(TEXT("Message limit"), Json->GetStringField(TEXT("errorMessage")).Len(), 5000); TestEqual(TEXT("Type limit"), Json->GetStringField(TEXT("errorType")).Len(), 100); TestEqual(TEXT("Stack limit"), Json->GetStringField(TEXT("stackTrace")).Len(), 10000); @@ -72,10 +71,10 @@ bool FAptabaseErrorLimitsTest::RunTest(const FString& Parameters) TestEqual(TEXT("OS version limit"), Json->GetStringField(TEXT("osVersion")).Len(), 100); TestEqual(TEXT("App version limit"), Json->GetStringField(TEXT("appVersion")).Len(), 50); TestEqual(TEXT("SDK version limit"), Json->GetStringField(TEXT("sdkVersion")).Len(), 40); - const auto Empty = FAptabaseErrorReport::Create(TEXT(" \t\n"), TEXT(""), TEXT(""), false, false, Context); + const auto Empty = FAptabaseErrorReport::Create(TEXT(""), TEXT(" \t\n"), TEXT(""), false, Context); TestEqual(TEXT("Whitespace type fallback"), Empty.ErrorType, FString(TEXT("Error"))); TestEqual(TEXT("Empty message is still a valid report"), Empty.ErrorMessage, FString(TEXT("Error: "))); - const auto Padded = FAptabaseErrorReport::Create(FString::ChrN(101, TCHAR(' ')) + TEXT("Error"), TEXT("test"), TEXT(""), false, false, Context); + const auto Padded = FAptabaseErrorReport::Create(TEXT("test"), FString::ChrN(101, TCHAR(' ')) + TEXT("Error"), TEXT(""), false, Context); TestEqual(TEXT("Trim before truncating so the type remains valid"), Padded.ErrorType, FString(TEXT("Error"))); return true; } @@ -88,7 +87,7 @@ bool FAptabaseErrorRetryTest::RunTest(const FString& Parameters) { FAptabaseErrorQueue Queue; Queue.StartSession(TestContext()); - Queue.Enqueue(TEXT("NetworkError"), TEXT("Offline"), TEXT("original stack"), false, false); + Queue.Enqueue(TEXT("Offline"), TEXT("NetworkError"), TEXT("original stack"), false); const auto Batch = Queue.TakeBatch(); if (!TestEqual(TEXT("One initial report"), Batch.Num(), 1)) { @@ -120,18 +119,18 @@ bool FAptabaseErrorCapacityTest::RunTest(const FString& Parameters) { FAptabaseErrorQueue Queue; Queue.StartSession(TestContext()); - TestTrue(TEXT("First occurrence accepted"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), false, false)); - TestFalse(TEXT("Duplicate suppressed"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), false, false)); - TestTrue(TEXT("Fatal has separate identity"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), true, false)); - TestTrue(TEXT("Automatic has separate identity"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("stack"), false, true)); - TestTrue(TEXT("Different stack has separate identity"), Queue.Enqueue(TEXT("Error"), TEXT("Repeated"), TEXT("other stack"), false, false)); + TestTrue(TEXT("First occurrence accepted"), Queue.Enqueue(TEXT("Repeated"), TEXT("Error"), TEXT("stack"), false)); + TestFalse(TEXT("Duplicate suppressed"), Queue.Enqueue(TEXT("Repeated"), TEXT("Error"), TEXT("stack"), false)); + TestTrue(TEXT("Fatal has separate identity"), Queue.Enqueue(TEXT("Repeated"), TEXT("Error"), TEXT("stack"), true)); + TestTrue(TEXT("Different type has separate identity"), Queue.Enqueue(TEXT("Repeated"), TEXT("OtherError"), TEXT("stack"), false)); + TestTrue(TEXT("Different stack has separate identity"), Queue.Enqueue(TEXT("Repeated"), TEXT("Error"), TEXT("other stack"), false)); for (int32 Index = 4; Index < FAptabaseErrorQueue::MaxPendingReports; ++Index) { - TestTrue(TEXT("Queue space available"), Queue.Enqueue(TEXT("Error"), FString::FromInt(Index), TEXT(""), false, false)); + TestTrue(TEXT("Queue space available"), Queue.Enqueue(FString::FromInt(Index), TEXT("Error"), TEXT(""), false)); } const auto Batch = Queue.TakeBatch(); TestEqual(TEXT("Full batch"), Batch.Num(), 25); - TestFalse(TEXT("In-flight reports count towards capacity"), Queue.Enqueue(TEXT("Error"), TEXT("Overflow"), TEXT(""), false, false)); + TestFalse(TEXT("In-flight reports count towards capacity"), Queue.Enqueue(TEXT("Overflow"), TEXT("Error"), TEXT(""), false)); for (const auto& Report : Batch) { Queue.Complete(Report, false, 0); @@ -142,7 +141,7 @@ bool FAptabaseErrorCapacityTest::RunTest(const FString& Parameters) { Queue.Complete(Report, true, 202); } - TestTrue(TEXT("Overflow can be reported once capacity is available"), Queue.Enqueue(TEXT("Error"), TEXT("Overflow"), TEXT(""), false, false)); + TestTrue(TEXT("Overflow can be reported once capacity is available"), Queue.Enqueue(TEXT("Overflow"), TEXT("Error"), TEXT(""), false)); return true; } @@ -151,11 +150,11 @@ IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseErrorSessionTest, "Aptabase.Errors.Ses bool FAptabaseErrorSessionTest::RunTest(const FString& Parameters) { FAptabaseErrorQueue Queue; - TestFalse(TEXT("No capture before session"), Queue.Enqueue(TEXT("Error"), TEXT("test"), TEXT(""), false, false)); + TestFalse(TEXT("No capture before session"), Queue.Enqueue(TEXT("test"), TEXT("Error"), TEXT(""), false)); Queue.StartSession(TestContext()); for (int32 Index = 0; Index < FAptabaseErrorQueue::MaxUniqueErrorsPerSession; ++Index) { - TestTrue(TEXT("Unique report accepted"), Queue.Enqueue(TEXT("Error"), FString::FromInt(Index), TEXT(""), false, false)); + TestTrue(TEXT("Unique report accepted"), Queue.Enqueue(FString::FromInt(Index), TEXT("Error"), TEXT(""), false)); const auto Batch = Queue.TakeBatch(); if (Batch.Num() != 1) { @@ -163,11 +162,11 @@ bool FAptabaseErrorSessionTest::RunTest(const FString& Parameters) } Queue.Complete(Batch[0], true, 202); } - TestFalse(TEXT("Session cap applies after delivery"), Queue.Enqueue(TEXT("Error"), TEXT("Over cap"), TEXT(""), false, false)); + TestFalse(TEXT("Session cap applies after delivery"), Queue.Enqueue(TEXT("Over cap"), TEXT("Error"), TEXT(""), false)); Queue.EndSession(); - TestFalse(TEXT("No capture after session"), Queue.Enqueue(TEXT("Error"), TEXT("Stopped"), TEXT(""), false, false)); + TestFalse(TEXT("No capture after session"), Queue.Enqueue(TEXT("Stopped"), TEXT("Error"), TEXT(""), false)); Queue.StartSession(TestContext()); - TestTrue(TEXT("New session resets deduplication"), Queue.Enqueue(TEXT("Error"), TEXT("0"), TEXT(""), false, false)); + TestTrue(TEXT("New session resets deduplication"), Queue.Enqueue(TEXT("0"), TEXT("Error"), TEXT(""), false)); const auto OldBatch = Queue.TakeBatch(); if (OldBatch.Num() != 1) { @@ -208,7 +207,7 @@ bool FAptabaseErrorThreadTest::RunTest(const FString& Parameters) { for (int32 Index = 0; Index < 100; ++Index) { - Queue.Enqueue(TEXT("LogGame"), FString::FromInt(Index), TEXT(""), false, true); + Queue.Enqueue(FString::FromInt(Index), TEXT("WorkerError"), TEXT(""), false); } } )); @@ -228,4 +227,43 @@ bool FAptabaseErrorThreadTest::RunTest(const FString& Parameters) return true; } +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseCrashReportTest, "Aptabase.Errors.CrashReport", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseCrashReportTest::RunTest(const FString& Parameters) +{ + // Fatal log / assert as written to GErrorHist: heading, location, message, blank line, call stack. + const auto Assert = FAptabaseCrashReporter::CreateReport( + TEXT("Assertion failed: Ptr != nullptr [File:D:/Game/Source/Player.cpp] [Line: 42] \r\nPlayer has no pawn\r\n\r\n0x00007ff6 Game.exe!APlayer::Tick()\r\n0x00007ff7 Game.exe!AActor::TickActor()"), + TestContext() + ); + TestEqual(TEXT("Assert type"), Assert.ErrorType, FString(TEXT("AssertionFailed"))); + TestEqual(TEXT("Assert message"), Assert.ErrorMessage, FString(TEXT("Fatal AssertionFailed: Ptr != nullptr [File:D:/Game/Source/Player.cpp] [Line: 42] \nPlayer has no pawn"))); + TestEqual(TEXT("Assert stack"), Assert.StackTrace, FString(TEXT("0x00007ff6 Game.exe!APlayer::Tick()\n0x00007ff7 Game.exe!AActor::TickActor()"))); + TestEqual(TEXT("Crash severity"), Assert.Severity, FString(TEXT("fatal"))); + TestEqual(TEXT("Crash kind"), Assert.Kind, FString(TEXT("crash"))); + TestEqual(TEXT("Session context"), Assert.Context.SessionId, TestContext().SessionId); + + const auto Fatal = FAptabaseCrashReporter::CreateReport(TEXT("Fatal error: [File:Main.cpp] [Line: 7] \nOut of memory\n\n[Callstack] 0x1 Game!Main()"), TestContext()); + TestEqual(TEXT("Fatal type"), Fatal.ErrorType, FString(TEXT("FatalError"))); + TestEqual(TEXT("Fatal message"), Fatal.ErrorMessage, FString(TEXT("Fatal FatalError: [File:Main.cpp] [Line: 7] \nOut of memory"))); + TestEqual(TEXT("Fatal stack"), Fatal.StackTrace, FString(TEXT("[Callstack] 0x1 Game!Main()"))); + + // Crash description without the blank line still splits at the first frame. + const auto Crash = FAptabaseCrashReporter::CreateReport(TEXT("Unhandled Exception: EXCEPTION_ACCESS_VIOLATION reading address 0x0\n0x00007ff6 Game.exe!Foo()"), TestContext()); + TestEqual(TEXT("Exception type"), Crash.ErrorType, FString(TEXT("UnhandledException"))); + TestEqual(TEXT("Exception message"), Crash.ErrorMessage, FString(TEXT("Fatal UnhandledException: EXCEPTION_ACCESS_VIOLATION reading address 0x0"))); + TestEqual(TEXT("Exception stack"), Crash.StackTrace, FString(TEXT("0x00007ff6 Game.exe!Foo()"))); + + // Unknown formats are reported verbatim under a generic type; a location-only heading is not a type. + const auto Plain = FAptabaseCrashReporter::CreateReport(TEXT("[File:X.cpp] [Line: 1] something broke"), TestContext()); + TestEqual(TEXT("Generic type"), Plain.ErrorType, FString(TEXT("FatalError"))); + TestEqual(TEXT("Verbatim message"), Plain.ErrorMessage, FString(TEXT("Fatal FatalError: [File:X.cpp] [Line: 1] something broke"))); + TestTrue(TEXT("No stack"), Plain.StackTrace.IsEmpty()); + + const auto Empty = FAptabaseCrashReporter::CreateReport(TEXT(""), TestContext()); + TestEqual(TEXT("Empty history still yields a valid report"), Empty.ErrorMessage, FString(TEXT("Fatal FatalError: Fatal error without details"))); + TestEqual(TEXT("Empty history keeps the generic type"), Empty.ErrorType, FString(TEXT("FatalError"))); + return true; +} + #endif diff --git a/Source/Aptabase/Public/AptabaseBlueprintLibrary.h b/Source/Aptabase/Public/AptabaseBlueprintLibrary.h index bf87bcd..73012d0 100644 --- a/Source/Aptabase/Public/AptabaseBlueprintLibrary.h +++ b/Source/Aptabase/Public/AptabaseBlueprintLibrary.h @@ -18,5 +18,5 @@ class APTABASE_API UAptabaseBlueprintLibrary : public UBlueprintFunctionLibrary * Supply the original stack trace if available; an empty stack is omitted. */ UFUNCTION(BlueprintCallable, Category = "Analytics|Aptabase", meta = (AdvancedDisplay = "StackTrace,bFatal")) - static void TrackError(const FString& ErrorMessage, const FString& ErrorType = TEXT("Error"), const FString& StackTrace = TEXT(""), bool bFatal = false); + static void TrackError(const FString& ErrorMessage, const FString& ErrorType = FString(TEXT("Error")), const FString& StackTrace = FString(), bool bFatal = false); }; diff --git a/llms.txt b/llms.txt index b6e128d..7572f3e 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ # Aptabase Unreal Engine SDK -> Unreal Engine plugin for Aptabase — open-source, privacy-first analytics and error reporting for games and apps. Tracks custom events with string and number properties using anonymous sessions. Error text may contain application data supplied by callers or captured from opted-in logs. Supports UE 5.x on all major platforms. +> Unreal Engine plugin for Aptabase — open-source, privacy-first analytics and error reporting for games and apps. Tracks custom events with string and number properties using anonymous sessions. Error text may contain application data supplied by callers or captured from opted-in crash reports. Supports UE 5.x on all major platforms. ## Installation @@ -35,7 +35,7 @@ Then configure in `Project Settings → Analytics → Aptabase`: | CustomHost | FString | "" | URL for self-hosted instances (only when Host = SH) | | SendInterval | float | 60.0 | Seconds between batch flushes in Release mode | | DebugSendInterval | float | 2.0 | Seconds between batch flushes in Debug mode | -| bEnableErrorLogging | bool | false | Capture Unreal Error/Fatal logs during active sessions | +| bEnableCrashReporting | bool | false | Report fatal errors (asserts, Fatal logs, crashes) during active sessions | If you already use another analytics provider, use the [Multicast Analytics Provider Plugin](https://docs.unrealengine.com/4.26/en-US/TestingAndOptimization/Analytics/Multicast/) to run both. @@ -87,7 +87,7 @@ UAptabaseBlueprintLibrary::TrackError(TEXT("Cannot continue"), TEXT("LoadError") Call on the game thread. The **Track Error** Blueprint node under **Analytics → Aptabase** exposes the same API. Manual reports are `handled`/`error`; setting `bFatal` gives `crash`/`fatal` without terminating the app. Stack traces are optional and must be supplied by the caller. Reports appear on the dashboard's Errors page with capture-time session, timestamp, OS, app/SDK versions, and debug mode. -Opt in to **Enable Error Logging** in Project Settings, or set `bEnableErrorLogging=True` in `[/Script/Aptabase.AptabaseSettings]` in `Config/DefaultAptabase.ini`. Unreal Error logs become `unhandled`/`error` and Fatal logs reaching the listener become `crash`/`fatal`; the type is the log category and no stack is synthesized. Warnings and Aptabase/HTTP diagnostics are ignored. Capture ends with the session. Native crashes, signals, assertions bypassing the listener, and logs compiled out of Shipping builds are not captured; fatal delivery is best effort. +Opt in to **Enable Crash Reporting** in Project Settings, or set `bEnableCrashReporting=True` in `[/Script/Aptabase.AptabaseSettings]` in `Config/DefaultAptabase.ini`. Fatal errors that reach the engine's error handler during an active session (assertion failures, `Fatal` logs, `LowLevelFatalError`, unhandled native exceptions where the engine routes them through its handler) are reported as `crash`/`fatal` with the engine's description and call stack. Non-fatal `Error` logs are never reported automatically. Crash reports are sent synchronously from the error handler with a 3 second timeout and are not persisted; delivery is best effort. Errors before `StartSession()` or after `EndSession()` are not captured. Errors use individual `POST /api/v0/error` requests with an `App-Key` header. Network errors and HTTP 408/429/5xx are retried on later flushes; 403 quota exhaustion and other permanent failures are dropped. The queue is bounded to 25 outstanding reports with per-session deduplication and a cap of 100 unique errors. `FlushEvents()` also flushes errors. Pending reports live in memory only. From 68899c3507ce4f902d1fb776be073d01f3d93190 Mon Sep 17 00:00:00 2001 From: Bogdan Ivanov Date: Sat, 19 Sep 2026 08:12:40 +0300 Subject: [PATCH 3/4] fix: persist crash reports and send them on the next session start On Apple and Unix platforms the engine's crash handler enables a crash allocator that suspends every other thread, including the HTTP thread, before OnHandleSystemError fires, so the synchronous send from the error handler never started and always timed out. The crash context also overwrites GErrorHist with the call stack there, so the parsed message was the first stack frame. The crash reporter now writes the report to Saved/Aptabase/Crashes from the error handler and the next session start sends pending reports under the crashed session ID, deleting a file once the server accepts or permanently rejects it and keeping it while offline. The fatal message is recovered from the "appError called" line the platform error device logs, with GErrorExceptionDescription as the fallback for native crashes. The immediate send is kept on Windows only, where the crash is handled on a separate thread, and completes on the HTTP thread so its status can be observed. Adds automation tests for the Apple error state and persistence. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 2 +- Docs/testing.md | 2 +- README.md | 4 +- .../Private/AptabaseAnalyticsProvider.cpp | 12 +- .../Private/AptabaseCrashReporter.cpp | 154 +++++++++++++++--- .../Aptabase/Private/AptabaseCrashReporter.h | 53 +++++- .../Private/AptabaseErrorDispatcher.cpp | 10 ++ .../Private/AptabaseErrorDispatcher.h | 4 + .../Aptabase/Private/AptabaseErrorQueue.cpp | 22 ++- Source/Aptabase/Private/AptabaseErrorQueue.h | 6 + .../Aptabase/Private/AptabaseErrorReport.cpp | 28 ++++ Source/Aptabase/Private/AptabaseErrorReport.h | 8 + Source/Aptabase/Private/AptabaseSettings.h | 5 +- .../Tests/AptabaseErrorReportingTests.cpp | 132 ++++++++++++++- 14 files changed, 398 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 770f24d..a2578e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ## 0.3.0 - Add `UAptabaseBlueprintLibrary::TrackError` and the **Track Error** Blueprint node for structured handled and fatal error reports. -- Add opt-in **Enable Crash Reporting** to report fatal errors (assertion failures, `Fatal` logs, crashes routed through the engine's error handler) during active sessions, sent best-effort from the error handler. +- Add opt-in **Enable Crash Reporting** to report fatal errors (assertion failures, `Fatal` logs, crashes routed through the engine's error handler) during active sessions. The error handler writes the report to `Saved/Aptabase/Crashes` and the next session start sends it; on Windows the handler also attempts an immediate send. - Include capture-time session, timestamp, OS, app version, SDK version, severity, kind, and debug mode; truncate fields to the server limits. - Send errors individually to `/api/v0/error`, retry network failures and HTTP 408/429/5xx on later flushes, and discard permanent rejections including HTTP 403 quota exhaustion. - Bound outstanding reports to 25 and deduplicate up to 100 unique errors per session. diff --git a/Docs/testing.md b/Docs/testing.md index 5954855..17eddd8 100644 --- a/Docs/testing.md +++ b/Docs/testing.md @@ -14,4 +14,4 @@ The tests cover the JSON contract and field limits, retry status codes, capture- For an end-to-end check, configure a local HTTP server as the SH host and start an analytics session in Play-in-Editor. Record a normal event and call **Track Error**. Verify that the event goes to `/api/v0/events` as an array and the error goes to `/api/v0/error` as one JSON object, with `App-Key` and `Content-Type: application/json` headers. Return 202 to accept a report; repeat with 400/403 (no retry), 408/429/500 (retry on the next flush), and a disconnected server. End/start PIE and verify that pending retries retain the old session and that new reports carry the new session. -To exercise crash reporting, enable **Enable Crash Reporting**, start a session, then trigger a fatal error from a packaged or `-game` build rather than Play-in-Editor, since a fatal error terminates the whole editor: for example a Blueprint-callable test function containing `UE_LOG(LogTemp, Fatal, TEXT("Test crash"))` or `check(false)`. Verify that one request arrives at `/api/v0/error` with `kind: "crash"`, `severity: "fatal"`, the engine's description as `errorMessage` and the call stack as `stackTrace`, before the engine's crash reporter appears. Repeat with the server stopped to confirm the game still terminates normally after the 3 second timeout. Non-fatal `UE_LOG(..., Error, ...)` messages must not produce a report. +To exercise crash reporting, enable **Enable Crash Reporting**, start a session, then trigger a fatal error from a packaged or `-game` build rather than Play-in-Editor, since a fatal error terminates the whole editor: for example a Blueprint-callable test function containing `UE_LOG(LogTemp, Fatal, TEXT("Test crash"))` or `check(false)`. Verify that one JSON file appears under `Saved/Aptabase/Crashes` with `kind: "crash"`, `severity: "fatal"`, the engine's description as `errorMessage` and the call stack as `stackTrace`. Launch the game again and start a session: the report must arrive at `/api/v0/error` with the crashed session's `sessionId` and the file must be deleted after a 2xx or 4xx response. Repeat with the server stopped during the second launch to confirm the file survives for a later launch. On Windows the first launch also sends the report immediately with a 3 second timeout, and the file is deleted when that succeeds. Non-fatal `UE_LOG(..., Error, ...)` messages must not produce a report. diff --git a/README.md b/README.md index ce35843..0fe98c5 100644 --- a/README.md +++ b/README.md @@ -122,11 +122,11 @@ Enable **Project Settings → Analytics → Aptabase → Enable Crash Reporting* bEnableCrashReporting=True ``` -This is off by default. While enabled, fatal errors that reach the engine's error handler during an active session are reported as `crash`/`fatal`: `check` and `verify` assertion failures, `UE_LOG` messages at `Fatal` verbosity, `LowLevelFatalError`, and unhandled native exceptions or signals on platforms where the engine routes them through its error handler. The report is built from the engine's error history: the heading becomes the error type (`AssertionFailed`, `FatalError`, `UnhandledException`), the description becomes the message and the engine's call stack is included. +This is off by default. While enabled, fatal errors that reach the engine's error handler during an active session are reported as `crash`/`fatal`: `check` and `verify` assertion failures, `UE_LOG` messages at `Fatal` verbosity, `LowLevelFatalError`, and unhandled native exceptions or signals on platforms where the engine routes them through its error handler. The report is built from the engine's error state: the heading becomes the error type (`AssertionFailed`, `FatalError`, `UnhandledException`, or the signal name such as `SIGSEGV` for a native crash on Apple and Unix platforms), the description becomes the message and the engine's call stack is included. Non-fatal `Error` log messages are never reported automatically. Use **Track Error** for errors your game detects itself. -Delivery of crash reports is best effort. The process is terminating, so the report is sent synchronously from the error handler with a 3 second timeout while the engine's own crash handling continues afterwards. Nothing is sent when the HTTP thread is not running (for example with `-nohttpthread`), when the crash corrupts the process beyond what the engine's handler survives, or when the device is offline; crash reports are not persisted for a later launch. Unreal's own Crash Reporter remains available and is unaffected. +Delivery of crash reports is best effort. The process is terminating, so the error handler writes the report to `Saved/Aptabase/Crashes` and the next session start sends the pending reports, each under the session in which the crash happened. The newest 10 pending reports are kept; a report is deleted once the server accepts or permanently rejects it, so an offline launch keeps it for a later one. On Windows the handler also tries to send the report immediately with a 3 second timeout, because the engine handles the crash on a separate thread while the HTTP thread keeps running; a report delivered this way is not sent again. On macOS, iOS and Linux the engine switches to a crash allocator that suspends every other thread, including the HTTP thread, so crash reports always arrive at the next launch. Nothing is captured when the crash corrupts the process beyond what the engine's handler survives. Unreal's own Crash Reporter remains available and is unaffected. Errors and crashes that happen before `StartSession()` or after `EndSession()` are not captured. Start the session as early as your game can, for example in your `GameInstance::Init`. diff --git a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp index 987271e..284095e 100644 --- a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp +++ b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp @@ -9,6 +9,7 @@ #include #include #include +#include #include #include @@ -116,7 +117,14 @@ bool FAptabaseAnalyticsProvider::StartSession(const TArrayStartSession(ErrorContext); if (Settings->bEnableCrashReporting) { - CrashReporter = MakeUnique(ErrorContext); + // Crashes persisted by earlier runs are sent with the new session, under their own session IDs. + const FString PendingCrashDirectory = FPaths::Combine(FPaths::ProjectSavedDir(), TEXT("Aptabase"), TEXT("Crashes")); + for (FAptabaseErrorReport& PendingReport : FAptabaseCrashReporter::LoadPendingReports(PendingCrashDirectory)) + { + ErrorDispatcher->EnqueueReport(MoveTemp(PendingReport)); + } + ErrorDispatcher->Flush(); + CrashReporter = MakeUnique(ErrorContext, PendingCrashDirectory); } return true; } @@ -310,7 +318,7 @@ FAnalyticsEventAttribute FAptabaseAnalyticsProvider::GetDefaultEventAttribute(in { return DefaultEventAttributes[AttributeIndex]; } - + UE_LOG(LogAptabase, Warning, TEXT("Requested default event attribute index %d is out of bounds (count: %d)"), AttributeIndex, DefaultEventAttributes.Num()); return FAnalyticsEventAttribute(); } diff --git a/Source/Aptabase/Private/AptabaseCrashReporter.cpp b/Source/Aptabase/Private/AptabaseCrashReporter.cpp index 288c4a6..3b7ea91 100644 --- a/Source/Aptabase/Private/AptabaseCrashReporter.cpp +++ b/Source/Aptabase/Private/AptabaseCrashReporter.cpp @@ -1,19 +1,55 @@ #include "AptabaseCrashReporter.h" #include +#include +#include #include #include #include #include +#include #include +#include +#include +#include #include +#include #include -FAptabaseCrashReporter::FAptabaseCrashReporter(const FAptabaseErrorContext& InContext) : Context(InContext) +namespace { + bool LooksLikeStackFrame(const FString& Text) + { + return Text.StartsWith(TEXT("0x")) || Text.StartsWith(TEXT("[Callstack]")); + } +} // namespace + +void FAptabaseCrashReporter::FLoggedMessageCapture::Serialize(const TCHAR* Data, ELogVerbosity::Type Verbosity, const FName& Category) +{ + // FMacErrorOutputDevice, FWindowsErrorOutputDevice and FUnixErrorOutputDevice all log the fatal + // message this way on the first appError, before raising the exception that runs the crash handler. + static const TCHAR Prefix[] = TEXT("appError called: "); + constexpr int32 PrefixLength = UE_ARRAY_COUNT(Prefix) - 1; + if (Verbosity != ELogVerbosity::Error || !Data || FCString::Strncmp(Data, Prefix, PrefixLength) != 0 || bCaptured.exchange(true)) + { + return; + } + FCString::Strncpy(Message, Data + PrefixLength, UE_ARRAY_COUNT(Message)); +} + +FAptabaseCrashReporter::FAptabaseCrashReporter(const FAptabaseErrorContext& InContext, const FString& InPendingDirectory) : Context(InContext), PendingDirectory(InPendingDirectory) +{ + if (!PendingDirectory.IsEmpty()) + { + IFileManager::Get().MakeDirectory(*PendingDirectory, true); + } // Loading a module from inside the error handler is not safe, so make sure HTTP is loaded now. // The events path loads it lazily on the first flush, which may not have happened yet. FHttpModule::Get(); + if (GLog) + { + GLog->AddOutputDevice(&LoggedMessage); + } // Both delegates can fire for the same failure; whichever comes first sends the report. SystemErrorHandle = FCoreDelegates::OnHandleSystemError.AddRaw(this, &FAptabaseCrashReporter::OnFatalError); ShutdownAfterErrorHandle = FCoreDelegates::OnShutdownAfterError.AddRaw(this, &FAptabaseCrashReporter::OnFatalError); @@ -23,33 +59,53 @@ FAptabaseCrashReporter::~FAptabaseCrashReporter() { FCoreDelegates::OnHandleSystemError.Remove(SystemErrorHandle); FCoreDelegates::OnShutdownAfterError.Remove(ShutdownAfterErrorHandle); + if (GLog) + { + GLog->RemoveOutputDevice(&LoggedMessage); + } } -FAptabaseErrorReport FAptabaseCrashReporter::CreateReport(const TCHAR* ErrorHistory, const FAptabaseErrorContext& InContext) +FAptabaseErrorReport FAptabaseCrashReporter::CreateReport(const TCHAR* ErrorHistory, const TCHAR* LoggedMessage, const TCHAR* ExceptionDescription, const FAptabaseErrorContext& InContext) { FString History = FString(ErrorHistory ? ErrorHistory : TEXT("")).Replace(TEXT("\r\n"), TEXT("\n")).TrimStartAndEnd(); - // The engine writes the description, a blank line, then the call stack. Fall back to the first - // line that looks like a stack frame when the blank line is missing. - FString Message = History; + FString Message; FString StackTrace; - int32 Split = History.Find(TEXT("\n\n")); - if (Split == INDEX_NONE) + if (LooksLikeStackFrame(History)) { - static const TCHAR* const FrameMarkers[] = {TEXT("\n0x"), TEXT("\n[Callstack]")}; - for (const TCHAR* Marker : FrameMarkers) + StackTrace = History; + } + else + { + // The engine writes the description, a blank line, then the call stack. Fall back to the first + // line that looks like a stack frame when the blank line is missing. + Message = History; + int32 Split = History.Find(TEXT("\n\n")); + if (Split == INDEX_NONE) { - const int32 MarkerIndex = History.Find(Marker); - if (MarkerIndex != INDEX_NONE && (Split == INDEX_NONE || MarkerIndex < Split)) + static const TCHAR* const FrameMarkers[] = {TEXT("\n0x"), TEXT("\n[Callstack]")}; + for (const TCHAR* Marker : FrameMarkers) { - Split = MarkerIndex; + const int32 MarkerIndex = History.Find(Marker); + if (MarkerIndex != INDEX_NONE && (Split == INDEX_NONE || MarkerIndex < Split)) + { + Split = MarkerIndex; + } } } + if (Split != INDEX_NONE) + { + Message = History.Left(Split).TrimEnd(); + StackTrace = History.Mid(Split).TrimStart(); + } + } + if (Message.IsEmpty() && LoggedMessage && LoggedMessage[0] != 0) + { + Message = FString(LoggedMessage).Replace(TEXT("\r\n"), TEXT("\n")).TrimStartAndEnd(); } - if (Split != INDEX_NONE) + if (Message.IsEmpty() && ExceptionDescription && ExceptionDescription[0] != 0) { - Message = History.Left(Split).TrimEnd(); - StackTrace = History.Mid(Split).TrimStart(); + Message = FString(ExceptionDescription).TrimStartAndEnd(); } // "Fatal error: [File:...] [Line: 12] \nMessage" -> type "FatalError", message "[File:...] [Line: 12] \nMessage". @@ -79,6 +135,53 @@ FAptabaseErrorReport FAptabaseCrashReporter::CreateReport(const TCHAR* ErrorHist return FAptabaseErrorReport::Create(Message, ErrorType, StackTrace, true, InContext); } +TArray FAptabaseCrashReporter::LoadPendingReports(const FString& PendingDirectory) +{ + TArray Reports; + if (PendingDirectory.IsEmpty()) + { + return Reports; + } + IFileManager& FileManager = IFileManager::Get(); + TArray FileNames; + FileManager.FindFiles(FileNames, *PendingDirectory, TEXT("json")); + // File names start with the capture time, so the lexical order is the chronological order. + FileNames.Sort( + [](const FString& A, const FString& B) + { + return A > B; + } + ); + for (int32 Index = 0; Index < FileNames.Num(); ++Index) + { + const FString Path = FPaths::Combine(PendingDirectory, FileNames[Index]); + FString Body; + TSharedPtr Json; + FAptabaseErrorReport Report; + if (Reports.Num() < MaxPersistedReports && FFileHelper::LoadFileToString(Body, *Path) && FJsonSerializer::Deserialize(TJsonReaderFactory<>::Create(Body), Json) && Json.IsValid() && + FAptabaseErrorReport::FromJsonObject(*Json, Report)) + { + Report.PersistedPath = Path; + Reports.Add(MoveTemp(Report)); + } + else + { + FileManager.Delete(*Path, false, false, true); + } + } + return Reports; +} + +FString FAptabaseCrashReporter::Persist(const FString& Body) const +{ + if (PendingDirectory.IsEmpty()) + { + return FString(); + } + const FString Path = FPaths::Combine(PendingDirectory, FString::Printf(TEXT("%lld-%s.json"), FDateTime::UtcNow().ToUnixTimestamp(), *Context.SessionId)); + return FFileHelper::SaveStringToFile(Body, *Path, FFileHelper::EEncodingOptions::ForceUTF8WithoutBOM) ? Path : FString(); +} + void FAptabaseCrashReporter::OnFatalError() { // OnShutdownAfterError can run before the error text exists; leave the flag clear so a later @@ -89,15 +192,17 @@ void FAptabaseCrashReporter::OnFatalError() } // Do not log, assert or touch the game thread from here: the engine is inside its error handler. + const FAptabaseErrorReport Report = CreateReport(GErrorHist, LoggedMessage.Get(), GErrorExceptionDescription, Context); + FString Body; + FJsonSerializer::Serialize(Report.ToJsonObject(), TJsonWriterFactory<>::Create(&Body)); + const FString PersistedPath = Persist(Body); + +#if PLATFORM_WINDOWS if (!FModuleManager::Get().IsModuleLoaded(TEXT("HTTP"))) { return; } - const FAptabaseErrorReport Report = CreateReport(GErrorHist, Context); - FString Body; - FJsonSerializer::Serialize(Report.ToJsonObject(), TJsonWriterFactory<>::Create(&Body)); - const FHttpRequestRef Request = FHttpModule::Get().CreateRequest(); Request->SetURL(Context.ApiUrl + TEXT("/api/v0/error")); Request->SetVerb(TEXT("POST")); @@ -105,13 +210,14 @@ void FAptabaseCrashReporter::OnFatalError() Request->SetHeader(TEXT("Content-Type"), TEXT("application/json")); Request->SetContentAsString(Body); Request->SetTimeout(SendTimeoutSeconds); + // The game thread is suspended, so let the HTTP thread finish the request and update its status. + Request->SetDelegateThreadPolicy(EHttpRequestDelegateThreadPolicy::CompleteOnHttpThread); if (!Request->ProcessRequest()) { return; } // Requests are processed on the HTTP thread, which keeps running while this thread waits. - // The completion delegate would only run on the game thread, so poll the status instead. const double Deadline = FPlatformTime::Seconds() + SendTimeoutSeconds; while (Request->GetStatus() == EHttpRequestStatus::Processing && FPlatformTime::Seconds() < Deadline) { @@ -120,5 +226,13 @@ void FAptabaseCrashReporter::OnFatalError() if (Request->GetStatus() == EHttpRequestStatus::Processing) { Request->CancelRequest(); + return; + } + const FHttpResponsePtr Response = Request->GetResponse(); + if (!PersistedPath.IsEmpty() && Request->GetStatus() == EHttpRequestStatus::Succeeded && Response.IsValid() && EHttpResponseCodes::IsOk(Response->GetResponseCode())) + { + // Delivered now; the next launch must not send it again. + IFileManager::Get().Delete(*PersistedPath, false, false, true); } +#endif } diff --git a/Source/Aptabase/Private/AptabaseCrashReporter.h b/Source/Aptabase/Private/AptabaseCrashReporter.h index 371c726..153863f 100644 --- a/Source/Aptabase/Private/AptabaseCrashReporter.h +++ b/Source/Aptabase/Private/AptabaseCrashReporter.h @@ -2,6 +2,7 @@ #include #include +#include #include "AptabaseErrorReport.h" #include @@ -9,33 +10,67 @@ /** * Opt-in reporting of fatal engine errors: asserts, Fatal logs and crashes that reach the engine's * error handler. Unreal never delivers these through GLog at Fatal verbosity and terminates the - * process right after, so the report is built from GErrorHist and sent synchronously from the - * error handler with a short timeout. Best effort only: the request is processed by the HTTP - * thread while the crashing thread waits, and nothing is sent if that thread is not running. + * process right after, so the report is built inside the error handler from GErrorHist, the + * exception description and the message the error device logged, then written to disk. Pending + * reports are sent at the next session start. On Windows the handler also tries to send the report + * right away: the crash is handled on a separate thread while the HTTP thread keeps running. On + * Apple and Unix platforms the handler switches to a crash allocator that suspends every other + * thread on its next allocation, including the HTTP thread, so nothing can be sent until relaunch. */ class FAptabaseCrashReporter final { public: - /** How long the crashing thread waits for the report to be delivered before the engine continues shutting down. */ + /** How long the crashing thread waits for an immediate delivery before the engine continues shutting down. */ static constexpr float SendTimeoutSeconds = 3.0f; + /** Newest pending reports kept on disk; older files are deleted when reports are loaded. */ + static constexpr int32 MaxPersistedReports = 10; - explicit FAptabaseCrashReporter(const FAptabaseErrorContext& InContext); + /** PendingDirectory receives one JSON file per crash; empty disables persistence. */ + FAptabaseCrashReporter(const FAptabaseErrorContext& InContext, const FString& PendingDirectory); ~FAptabaseCrashReporter(); FAptabaseCrashReporter(const FAptabaseCrashReporter&) = delete; FAptabaseCrashReporter& operator=(const FAptabaseCrashReporter&) = delete; /** - * Builds a crash report from the engine's error history (GErrorHist). The heading before the first - * colon ("Fatal error", "Assertion failed", "Unhandled Exception") becomes the error type; the text - * up to the first blank line is the message and the remainder is the call stack. + * Builds a crash report from the engine's error state. ErrorHistory is GErrorHist: on Windows the + * description, a blank line and the call stack; on Apple platforms the call stack alone because the + * crash context overwrites the history before the error handler runs. LoggedMessage is the text the + * error device logged when the fatal error was raised, used when the history has no description, and + * ExceptionDescription (GErrorExceptionDescription) is the last resort. The heading before the first + * colon ("Fatal error", "Assertion failed", "SIGSEGV") becomes the error type. */ - static FAptabaseErrorReport CreateReport(const TCHAR* ErrorHistory, const FAptabaseErrorContext& Context); + static FAptabaseErrorReport CreateReport(const TCHAR* ErrorHistory, const TCHAR* LoggedMessage, const TCHAR* ExceptionDescription, const FAptabaseErrorContext& Context); + + /** + * Loads reports persisted by earlier runs, newest first, deleting unreadable files and anything + * beyond the newest MaxPersistedReports readable ones. Each report carries the file in PersistedPath so the queue can delete + * it once the outcome is final. + */ + static TArray LoadPendingReports(const FString& PendingDirectory); private: + /** Records the message the platform error device logs as "appError called: ..." before the crash handler runs. */ + class FLoggedMessageCapture final : public FOutputDevice + { + public: + virtual void Serialize(const TCHAR* Data, ELogVerbosity::Type Verbosity, const FName& Category) override; + virtual bool CanBeUsedOnAnyThread() const override { return true; } + virtual bool CanBeUsedOnMultipleThreads() const override { return true; } + virtual bool CanBeUsedOnPanicThread() const override { return true; } + const TCHAR* Get() const { return bCaptured ? Message : TEXT(""); } + + private: + std::atomic bCaptured{false}; + TCHAR Message[4096] = {0}; + }; + void OnFatalError(); + FString Persist(const FString& Body) const; FAptabaseErrorContext Context; + FString PendingDirectory; + FLoggedMessageCapture LoggedMessage; std::atomic bReported{false}; FDelegateHandle SystemErrorHandle; FDelegateHandle ShutdownAfterErrorHandle; diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp index 392bdb6..868e9bf 100644 --- a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp @@ -48,6 +48,16 @@ void FAptabaseErrorDispatcher::TrackError(const FString& Message, const FString& ); } +bool FAptabaseErrorDispatcher::EnqueueReport(FAptabaseErrorReport Report) +{ + return Queue.EnqueueReport(MoveTemp(Report)); +} + +bool FAptabaseErrorDispatcher::EnqueueReport(FAptabaseErrorReport Report) +{ + return Queue.EnqueueReport(MoveTemp(Report)); +} + void FAptabaseErrorDispatcher::Flush() { check(IsInGameThread()); diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.h b/Source/Aptabase/Private/AptabaseErrorDispatcher.h index c05f7a2..d7e33b5 100644 --- a/Source/Aptabase/Private/AptabaseErrorDispatcher.h +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.h @@ -13,6 +13,10 @@ class FAptabaseErrorDispatcher : public TSharedFromThis #include void FAptabaseErrorQueue::StartSession(const FAptabaseErrorContext& InContext) @@ -36,6 +37,20 @@ bool FAptabaseErrorQueue::Enqueue(const FString& Message, const FString& ErrorTy return true; } +bool FAptabaseErrorQueue::EnqueueReport(FAptabaseErrorReport Report) +{ + FScopeLock Lock(&Mutex); + if (!bActive || Outstanding >= MaxPendingReports) + { + return false; + } + Report.Context.ApiUrl = Context.ApiUrl; + Report.Context.AppKey = Context.AppKey; + Pending.Add(MoveTemp(Report)); + ++Outstanding; + return true; +} + TArray FAptabaseErrorQueue::TakeBatch() { FScopeLock Lock(&Mutex); @@ -50,10 +65,13 @@ void FAptabaseErrorQueue::Complete(const FAptabaseErrorReport& Report, bool bWas if (ShouldRetry(bWasSuccessful, ResponseCode)) { Pending.Add(Report); + return; } - else + --Outstanding; + if (!Report.PersistedPath.IsEmpty()) { - --Outstanding; + // Delivered or permanently rejected: either way the file must not be sent again. + IFileManager::Get().Delete(*Report.PersistedPath, false, false, true); } } diff --git a/Source/Aptabase/Private/AptabaseErrorQueue.h b/Source/Aptabase/Private/AptabaseErrorQueue.h index 7b47de2..6b7f75e 100644 --- a/Source/Aptabase/Private/AptabaseErrorQueue.h +++ b/Source/Aptabase/Private/AptabaseErrorQueue.h @@ -14,6 +14,12 @@ class FAptabaseErrorQueue void StartSession(const FAptabaseErrorContext& InContext); void EndSession(); bool Enqueue(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal); + /** + * Queues a report captured earlier, such as a crash persisted by a previous run. The report keeps + * its own session and capture-time context; only the host and key come from the current session. + * Not deduplicated: reports from different sessions are distinct even when their text matches. + */ + bool EnqueueReport(FAptabaseErrorReport Report); TArray TakeBatch(); void Complete(const FAptabaseErrorReport& Report, bool bWasSuccessful, int32 ResponseCode); static bool ShouldRetry(bool bWasSuccessful, int32 ResponseCode); diff --git a/Source/Aptabase/Private/AptabaseErrorReport.cpp b/Source/Aptabase/Private/AptabaseErrorReport.cpp index 88ec911..c99e793 100644 --- a/Source/Aptabase/Private/AptabaseErrorReport.cpp +++ b/Source/Aptabase/Private/AptabaseErrorReport.cpp @@ -21,6 +21,34 @@ FAptabaseErrorReport FAptabaseErrorReport::Create(const FString& Message, const return Report; } +bool FAptabaseErrorReport::FromJsonObject(const FJsonObject& Json, FAptabaseErrorReport& OutReport) +{ + FAptabaseErrorReport Report; + if (!Json.TryGetStringField(TEXT("errorType"), Report.ErrorType) || !Json.TryGetStringField(TEXT("errorMessage"), Report.ErrorMessage) || + !Json.TryGetStringField(TEXT("timestamp"), Report.Timestamp) || !Json.TryGetStringField(TEXT("severity"), Report.Severity) || !Json.TryGetStringField(TEXT("kind"), Report.Kind) || + Report.ErrorType.IsEmpty() || Report.Timestamp.IsEmpty()) + { + return false; + } + Json.TryGetStringField(TEXT("stackTrace"), Report.StackTrace); + Json.TryGetStringField(TEXT("sessionId"), Report.Context.SessionId); + Json.TryGetStringField(TEXT("osName"), Report.Context.OsName); + Json.TryGetStringField(TEXT("osVersion"), Report.Context.OsVersion); + Json.TryGetStringField(TEXT("appVersion"), Report.Context.AppVersion); + Json.TryGetStringField(TEXT("sdkVersion"), Report.Context.SdkVersion); + Json.TryGetBoolField(TEXT("isDebug"), Report.Context.bIsDebug); + Report.ErrorType = Report.ErrorType.Left(100); + Report.ErrorMessage = Report.ErrorMessage.Left(5000); + Report.StackTrace = Report.StackTrace.Left(10000); + Report.Context.SessionId = Report.Context.SessionId.Left(100); + Report.Context.OsName = Report.Context.OsName.Left(30); + Report.Context.OsVersion = Report.Context.OsVersion.Left(100); + Report.Context.AppVersion = Report.Context.AppVersion.Left(50); + Report.Context.SdkVersion = Report.Context.SdkVersion.Left(40); + OutReport = MoveTemp(Report); + return true; +} + TSharedRef FAptabaseErrorReport::ToJsonObject() const { TSharedRef Json = MakeShared(); diff --git a/Source/Aptabase/Private/AptabaseErrorReport.h b/Source/Aptabase/Private/AptabaseErrorReport.h index cd755e7..dc703b9 100644 --- a/Source/Aptabase/Private/AptabaseErrorReport.h +++ b/Source/Aptabase/Private/AptabaseErrorReport.h @@ -22,6 +22,12 @@ struct FAptabaseErrorReport { static FAptabaseErrorReport Create(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal, const FAptabaseErrorContext& Context); + /** + * Rebuilds a report from a body produced by ToJsonObject, for reports persisted by the crash + * reporter. Credentials are not part of the body; the caller supplies the current host and key. + */ + static bool FromJsonObject(const FJsonObject& Json, FAptabaseErrorReport& OutReport); + FString ErrorType; FString ErrorMessage; FString StackTrace; @@ -29,6 +35,8 @@ struct FAptabaseErrorReport FString Severity; FString Kind; FAptabaseErrorContext Context; + /** File this report was loaded from, deleted once the report is delivered or rejected. Not serialized. */ + FString PersistedPath; TSharedRef ToJsonObject() const; uint64 GetFingerprint() const; diff --git a/Source/Aptabase/Private/AptabaseSettings.h b/Source/Aptabase/Private/AptabaseSettings.h index e2c3db1..c309f93 100644 --- a/Source/Aptabase/Private/AptabaseSettings.h +++ b/Source/Aptabase/Private/AptabaseSettings.h @@ -58,8 +58,9 @@ class APTABASE_API UAptabaseSettings : public UDeveloperSettings float DebugSendInterval = 2.0f; /** * Report fatal errors (asserts, Fatal logs and crashes handled by the engine's error handler) that - * occur during an active session. The report is sent synchronously from the error handler on a - * best-effort basis. Non-fatal Error logs are never reported automatically. + * occur during an active session. The report is written to Saved/Aptabase/Crashes from the error handler + * and sent at the next session start (Windows also attempts an immediate send). Non-fatal Error logs + * are never reported automatically. */ UPROPERTY(Config, EditAnywhere, Category = "Aptabase Error Reporting") bool bEnableCrashReporting = false; diff --git a/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp index da044e0..2ddd1b7 100644 --- a/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp +++ b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp @@ -2,7 +2,11 @@ #include #include +#include #include +#include +#include +#include #include "AptabaseCrashReporter.h" #include "AptabaseErrorQueue.h" @@ -233,7 +237,11 @@ bool FAptabaseCrashReportTest::RunTest(const FString& Parameters) { // Fatal log / assert as written to GErrorHist: heading, location, message, blank line, call stack. const auto Assert = FAptabaseCrashReporter::CreateReport( - TEXT("Assertion failed: Ptr != nullptr [File:D:/Game/Source/Player.cpp] [Line: 42] \r\nPlayer has no pawn\r\n\r\n0x00007ff6 Game.exe!APlayer::Tick()\r\n0x00007ff7 Game.exe!AActor::TickActor()"), + TEXT( + "Assertion failed: Ptr != nullptr [File:D:/Game/Source/Player.cpp] [Line: 42] \r\nPlayer has no pawn\r\n\r\n0x00007ff6 Game.exe!APlayer::Tick()\r\n0x00007ff7 Game.exe!AActor::TickActor()" + ), + TEXT(""), + TEXT(""), TestContext() ); TestEqual(TEXT("Assert type"), Assert.ErrorType, FString(TEXT("AssertionFailed"))); @@ -243,27 +251,141 @@ bool FAptabaseCrashReportTest::RunTest(const FString& Parameters) TestEqual(TEXT("Crash kind"), Assert.Kind, FString(TEXT("crash"))); TestEqual(TEXT("Session context"), Assert.Context.SessionId, TestContext().SessionId); - const auto Fatal = FAptabaseCrashReporter::CreateReport(TEXT("Fatal error: [File:Main.cpp] [Line: 7] \nOut of memory\n\n[Callstack] 0x1 Game!Main()"), TestContext()); + const auto Fatal = FAptabaseCrashReporter::CreateReport(TEXT("Fatal error: [File:Main.cpp] [Line: 7] \nOut of memory\n\n[Callstack] 0x1 Game!Main()"), TEXT(""), TEXT(""), TestContext()); TestEqual(TEXT("Fatal type"), Fatal.ErrorType, FString(TEXT("FatalError"))); TestEqual(TEXT("Fatal message"), Fatal.ErrorMessage, FString(TEXT("Fatal FatalError: [File:Main.cpp] [Line: 7] \nOut of memory"))); TestEqual(TEXT("Fatal stack"), Fatal.StackTrace, FString(TEXT("[Callstack] 0x1 Game!Main()"))); // Crash description without the blank line still splits at the first frame. - const auto Crash = FAptabaseCrashReporter::CreateReport(TEXT("Unhandled Exception: EXCEPTION_ACCESS_VIOLATION reading address 0x0\n0x00007ff6 Game.exe!Foo()"), TestContext()); + const auto Crash = FAptabaseCrashReporter::CreateReport(TEXT("Unhandled Exception: EXCEPTION_ACCESS_VIOLATION reading address 0x0\n0x00007ff6 Game.exe!Foo()"), TEXT(""), TEXT(""), TestContext()); TestEqual(TEXT("Exception type"), Crash.ErrorType, FString(TEXT("UnhandledException"))); TestEqual(TEXT("Exception message"), Crash.ErrorMessage, FString(TEXT("Fatal UnhandledException: EXCEPTION_ACCESS_VIOLATION reading address 0x0"))); TestEqual(TEXT("Exception stack"), Crash.StackTrace, FString(TEXT("0x00007ff6 Game.exe!Foo()"))); // Unknown formats are reported verbatim under a generic type; a location-only heading is not a type. - const auto Plain = FAptabaseCrashReporter::CreateReport(TEXT("[File:X.cpp] [Line: 1] something broke"), TestContext()); + const auto Plain = FAptabaseCrashReporter::CreateReport(TEXT("[File:X.cpp] [Line: 1] something broke"), TEXT(""), TEXT(""), TestContext()); TestEqual(TEXT("Generic type"), Plain.ErrorType, FString(TEXT("FatalError"))); TestEqual(TEXT("Verbatim message"), Plain.ErrorMessage, FString(TEXT("Fatal FatalError: [File:X.cpp] [Line: 1] something broke"))); TestTrue(TEXT("No stack"), Plain.StackTrace.IsEmpty()); - const auto Empty = FAptabaseCrashReporter::CreateReport(TEXT(""), TestContext()); + const auto Empty = FAptabaseCrashReporter::CreateReport(TEXT(""), TEXT(""), TEXT(""), TestContext()); TestEqual(TEXT("Empty history still yields a valid report"), Empty.ErrorMessage, FString(TEXT("Fatal FatalError: Fatal error without details"))); TestEqual(TEXT("Empty history keeps the generic type"), Empty.ErrorType, FString(TEXT("FatalError"))); return true; } +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseCrashReportApplePlatformTest, "Aptabase.Errors.CrashReportApplePlatform", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseCrashReportApplePlatformTest::RunTest(const FString& Parameters) +{ + // On Apple platforms the crash context overwrites GErrorHist with the call stack before the error + // handler runs; the description survives only as the message the error device logged. + const TCHAR* Stack = + TEXT("0x15c18e30 libUnrealEditor-Engine.dylib!FTimerUnifiedDelegate::Execute() const [UnknownFile]) \n0x15c1c514 libUnrealEditor-Engine.dylib!FTimerManager::Tick(float) [UnknownFile]) "); + const auto Fatal = FAptabaseCrashReporter::CreateReport( + Stack, TEXT("Fatal error: [File:Game.cpp] [Line: 77] \r\nIntentional test crash\r\n"), TEXT("SIGSEGV: invalid attempt to access memory at address 0x3"), TestContext() + ); + TestEqual(TEXT("Type from logged message"), Fatal.ErrorType, FString(TEXT("FatalError"))); + TestEqual(TEXT("Message from logged message"), Fatal.ErrorMessage, FString(TEXT("Fatal FatalError: [File:Game.cpp] [Line: 77] \nIntentional test crash"))); + TestEqual(TEXT("Whole history is the stack"), Fatal.StackTrace, FString(Stack).TrimStartAndEnd()); + + const auto Assert = FAptabaseCrashReporter::CreateReport( + Stack, TEXT("Assertion failed: false [File:Game.cpp] [Line: 3] \nMust not happen"), TEXT("SIGSEGV: invalid attempt to access memory at address 0x3"), TestContext() + ); + TestEqual(TEXT("Assert type from logged message"), Assert.ErrorType, FString(TEXT("AssertionFailed"))); + TestEqual(TEXT("Assert message from logged message"), Assert.ErrorMessage, FString(TEXT("Fatal AssertionFailed: false [File:Game.cpp] [Line: 3] \nMust not happen"))); + + // A real crash logs nothing before the handler: the signal description is all that is known. + const auto Signal = FAptabaseCrashReporter::CreateReport(Stack, TEXT(""), TEXT("SIGSEGV: invalid attempt to access memory at address 0x0"), TestContext()); + TestEqual(TEXT("Signal type"), Signal.ErrorType, FString(TEXT("SIGSEGV"))); + TestEqual(TEXT("Signal message"), Signal.ErrorMessage, FString(TEXT("Fatal SIGSEGV: invalid attempt to access memory at address 0x0"))); + TestEqual(TEXT("Signal stack"), Signal.StackTrace, FString(Stack).TrimStartAndEnd()); + + // A history with its own description takes precedence over the logged message. + const auto Windows = FAptabaseCrashReporter::CreateReport( + TEXT("Fatal error: [File:Main.cpp] [Line: 7] \nOut of memory\n\n0x1 Game!Main()"), TEXT("Fatal error: something else"), TEXT("EXCEPTION_ACCESS_VIOLATION"), TestContext() + ); + TestEqual(TEXT("History description wins"), Windows.ErrorMessage, FString(TEXT("Fatal FatalError: [File:Main.cpp] [Line: 7] \nOut of memory"))); + + const auto Nothing = FAptabaseCrashReporter::CreateReport(Stack, TEXT(""), TEXT(""), TestContext()); + TestEqual(TEXT("Stack without any description"), Nothing.ErrorMessage, FString(TEXT("Fatal FatalError: Fatal error without details"))); + TestEqual(TEXT("Stack without any description keeps the stack"), Nothing.StackTrace, FString(Stack).TrimStartAndEnd()); + return true; +} + +IMPLEMENT_SIMPLE_AUTOMATION_TEST(FAptabaseCrashReportPersistenceTest, "Aptabase.Errors.CrashReportPersistence", EAutomationTestFlags::EditorContext | EAutomationTestFlags::EngineFilter) + +bool FAptabaseCrashReportPersistenceTest::RunTest(const FString& Parameters) +{ + const FAptabaseErrorReport Original = FAptabaseCrashReporter::CreateReport(TEXT("Fatal error: [File:Main.cpp] [Line: 7] \nOut of memory\n\n0x1 Game!Main()"), TEXT(""), TEXT(""), TestContext()); + FAptabaseErrorReport Restored; + TestTrue(TEXT("Round trip parses"), FAptabaseErrorReport::FromJsonObject(*Original.ToJsonObject(), Restored)); + TestEqual(TEXT("Round trip type"), Restored.ErrorType, Original.ErrorType); + TestEqual(TEXT("Round trip message"), Restored.ErrorMessage, Original.ErrorMessage); + TestEqual(TEXT("Round trip stack"), Restored.StackTrace, Original.StackTrace); + TestEqual(TEXT("Round trip timestamp"), Restored.Timestamp, Original.Timestamp); + TestEqual(TEXT("Round trip severity"), Restored.Severity, Original.Severity); + TestEqual(TEXT("Round trip kind"), Restored.Kind, Original.Kind); + TestEqual(TEXT("Round trip session"), Restored.Context.SessionId, Original.Context.SessionId); + TestEqual(TEXT("Round trip OS"), Restored.Context.OsName, Original.Context.OsName); + TestEqual(TEXT("Round trip app version"), Restored.Context.AppVersion, Original.Context.AppVersion); + TestEqual(TEXT("Round trip SDK version"), Restored.Context.SdkVersion, Original.Context.SdkVersion); + TestTrue(TEXT("Round trip debug flag"), Restored.Context.bIsDebug); + TestTrue(TEXT("Credentials are not restored from the body"), Restored.Context.AppKey.IsEmpty() && Restored.Context.ApiUrl.IsEmpty()); + FJsonObject Incomplete; + Incomplete.SetStringField(TEXT("errorType"), TEXT("X")); + TestFalse(TEXT("Incomplete body rejected"), FAptabaseErrorReport::FromJsonObject(Incomplete, Restored)); + + const FString Directory = FPaths::Combine(FPaths::ProjectIntermediateDir(), TEXT("AptabaseTests"), FGuid::NewGuid().ToString()); + IFileManager& FileManager = IFileManager::Get(); + FileManager.MakeDirectory(*Directory, true); + FString Body; + FJsonSerializer::Serialize(Original.ToJsonObject(), TJsonWriterFactory<>::Create(&Body)); + for (int32 Index = 0; Index < FAptabaseCrashReporter::MaxPersistedReports + 2; ++Index) + { + FFileHelper::SaveStringToFile(Body, *FPaths::Combine(Directory, FString::Printf(TEXT("%d-session.json"), 1000 + Index))); + } + const FString Corrupt = FPaths::Combine(Directory, TEXT("2000-session.json")); + FFileHelper::SaveStringToFile(TEXT("{not json"), *Corrupt); + const FString Unrelated = FPaths::Combine(Directory, TEXT("notes.txt")); + FFileHelper::SaveStringToFile(TEXT("keep"), *Unrelated); + + TArray Loaded = FAptabaseCrashReporter::LoadPendingReports(Directory); + TestEqual(TEXT("Newest reports loaded up to the cap"), Loaded.Num(), FAptabaseCrashReporter::MaxPersistedReports); + TestFalse(TEXT("Corrupt file deleted"), FileManager.FileExists(*Corrupt)); + TestFalse(TEXT("Oldest file beyond the cap deleted"), FileManager.FileExists(*FPaths::Combine(Directory, TEXT("1000-session.json")))); + TestTrue(TEXT("Unrelated files untouched"), FileManager.FileExists(*Unrelated)); + TestEqual(TEXT("Nothing loaded from an empty path"), FAptabaseCrashReporter::LoadPendingReports(FString()).Num(), 0); + if (Loaded.Num() > 1) + { + TestTrue(TEXT("Loaded file recorded"), FileManager.FileExists(*Loaded[0].PersistedPath)); + TestEqual(TEXT("Loaded report keeps its session"), Loaded[0].Context.SessionId, TestContext().SessionId); + + auto NewContext = TestContext(); + NewContext.SessionId = TEXT("new session"); + NewContext.AppKey = TEXT("A-DEV-9999999999"); + NewContext.ApiUrl = TEXT("https://another-host.example"); + FAptabaseErrorQueue Queue; + TestFalse(TEXT("No pending reports before session"), Queue.EnqueueReport(Loaded[0])); + Queue.StartSession(NewContext); + TestTrue(TEXT("Pending report accepted"), Queue.EnqueueReport(Loaded[0])); + TestTrue(TEXT("Identical pending report from another file is not deduplicated"), Queue.EnqueueReport(Loaded[1])); + const auto Batch = Queue.TakeBatch(); + if (!TestEqual(TEXT("Both pending reports queued"), Batch.Num(), 2)) + { + return false; + } + TestEqual(TEXT("Crashed session retained"), Batch[0].Context.SessionId, TestContext().SessionId); + TestEqual(TEXT("Current key used"), Batch[0].Context.AppKey, NewContext.AppKey); + TestEqual(TEXT("Current host used"), Batch[0].Context.ApiUrl, NewContext.ApiUrl); + Queue.Complete(Batch[0], false, 503); + TestTrue(TEXT("File kept while retrying"), FileManager.FileExists(*Batch[0].PersistedPath)); + Queue.Complete(Batch[0], true, 202); + TestFalse(TEXT("File deleted after delivery"), FileManager.FileExists(*Batch[0].PersistedPath)); + Queue.Complete(Batch[1], true, 400); + TestFalse(TEXT("File deleted after permanent rejection"), FileManager.FileExists(*Batch[1].PersistedPath)); + } + FileManager.DeleteDirectory(*Directory, false, true); + return true; +} #endif From 892dd5ebc41d2fe187c795cad2609ef70ba383d0 Mon Sep 17 00:00:00 2001 From: Bogdan Ivanov Date: Wed, 23 Sep 2026 06:11:29 +0300 Subject: [PATCH 4/4] fix: remove duplicate EnqueueReport and update crash persistence docs The error dispatcher declared and defined EnqueueReport twice, which does not compile. README.md and llms.txt still described crash reports as sent synchronously and never persisted; they now match the persist-then-send-on-next-launch behaviour. Co-Authored-By: Claude Fable 5.1 --- README.md | 4 ++-- Source/Aptabase/Private/AptabaseErrorDispatcher.cpp | 5 ----- Source/Aptabase/Private/AptabaseErrorDispatcher.h | 2 -- llms.txt | 4 ++-- 4 files changed, 4 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0fe98c5..8d43796 100644 --- a/README.md +++ b/README.md @@ -132,10 +132,10 @@ Errors and crashes that happen before `StartSession()` or after `EndSession()` a ### Delivery -- Manual reports are sent asynchronously, one per request. Capturing an error schedules an immediate send on the game thread; `FlushEvents()` and the normal send timer also flush errors. Crash reports bypass the queue and are sent synchronously from the error handler. +- Manual reports are sent asynchronously, one per request. Capturing an error schedules an immediate send on the game thread; `FlushEvents()` and the normal send timer also flush errors. Crash reports are written to disk from the error handler and queued for sending at the next session start, as described above. - Failed requests are retained for a later flush on connection errors or HTTP 408, 429, and 5xx. Other responses, including HTTP 403 (monthly quota exhausted), are not retried. - The queue holds up to 25 outstanding reports, including requests in progress. New reports are dropped when full. Each unique combination of kind, type, message, and stack is reported once per session, up to 100 unique reports. -- Retries retain their original session and system context. Reports are stored in memory only and can be lost when the process exits. Ending a session initiates a final flush without waiting for delivery. +- Retries retain their original session and system context. Manual reports are stored in memory only and can be lost when the process exits; crash reports are persisted until delivered or permanently rejected. Ending a session initiates a final flush without waiting for delivery. - Error text can contain application data. Only include information you intend to send to Aptabase. See [testing instructions](Docs/testing.md) for the Unreal automation suite. diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp index 868e9bf..4d202c2 100644 --- a/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp @@ -53,11 +53,6 @@ bool FAptabaseErrorDispatcher::EnqueueReport(FAptabaseErrorReport Report) return Queue.EnqueueReport(MoveTemp(Report)); } -bool FAptabaseErrorDispatcher::EnqueueReport(FAptabaseErrorReport Report) -{ - return Queue.EnqueueReport(MoveTemp(Report)); -} - void FAptabaseErrorDispatcher::Flush() { check(IsInGameThread()); diff --git a/Source/Aptabase/Private/AptabaseErrorDispatcher.h b/Source/Aptabase/Private/AptabaseErrorDispatcher.h index d7e33b5..dec7d4e 100644 --- a/Source/Aptabase/Private/AptabaseErrorDispatcher.h +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.h @@ -15,8 +15,6 @@ class FAptabaseErrorDispatcher : public TSharedFromThis