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..a2578e0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +## 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. 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. +- `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 new file mode 100644 index 0000000..17eddd8 --- /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, 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. + +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 7b43caf..8d43796 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,63 @@ 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 crash reporting + +Enable **Project Settings → Analytics → Aptabase → Enable Crash Reporting** before starting the session, or add this to `Config/DefaultAptabase.ini`: + +```ini +[/Script/Aptabase.AptabaseSettings] +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 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 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`. + +### 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 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. 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. + ## 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..284095e 100644 --- a/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp +++ b/Source/Aptabase/Private/AptabaseAnalyticsProvider.cpp @@ -9,10 +9,13 @@ #include #include #include +#include #include #include +#include "AptabaseCrashReporter.h" #include "AptabaseData.h" +#include "AptabaseErrorDispatcher.h" #include "AptabaseLog.h" #include "AptabaseSettings.h" #include "ExtendedAnalyticsEventAttribute.h" @@ -21,6 +24,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 +51,29 @@ namespace } } // namespace +FAptabaseAnalyticsProvider::FAptabaseAnalyticsProvider() : ErrorDispatcher(MakeShared()) +{ +} + +FAptabaseAnalyticsProvider::~FAptabaseAnalyticsProvider() +{ + CrashReporter.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& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal) +{ + ErrorDispatcher->TrackError(Message, ErrorType, StackTrace, bFatal); +} + void FAptabaseAnalyticsProvider::RecordExtendedEvent(const FString& EventName, const TArray& Attributes) { RecordEventInternal(EventName, Attributes); @@ -51,6 +81,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 +102,37 @@ 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->bEnableCrashReporting) + { + // 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; } void FAptabaseAnalyticsProvider::EndSession() { + CrashReporter.Reset(); + ErrorDispatcher->EndSession(); if (BatchEventTimerHandle.IsValid()) { if (const UGameInstance* GameInstance = GetCurrentGameInstance()) @@ -116,6 +176,7 @@ void FAptabaseAnalyticsProvider::FlushEvents() } BatchedEvents.Empty(); + ErrorDispatcher->Flush(); } void FAptabaseAnalyticsProvider::SetUserID(const FString& InUserID) @@ -198,12 +259,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; @@ -251,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/AptabaseAnalyticsProvider.h b/Source/Aptabase/Private/AptabaseAnalyticsProvider.h index fc2e93a..621c905 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 FAptabaseCrashReporter; /** * 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& Message, const FString& ErrorType, 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 CrashReporter; + TArray EventRequests; }; diff --git a/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp b/Source/Aptabase/Private/AptabaseBlueprintLibrary.cpp new file mode 100644 index 0000000..8094887 --- /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(ErrorMessage, ErrorType, StackTrace, bFatal); + } + } +} diff --git a/Source/Aptabase/Private/AptabaseCrashReporter.cpp b/Source/Aptabase/Private/AptabaseCrashReporter.cpp new file mode 100644 index 0000000..3b7ea91 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseCrashReporter.cpp @@ -0,0 +1,238 @@ +#include "AptabaseCrashReporter.h" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +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); +} + +FAptabaseCrashReporter::~FAptabaseCrashReporter() +{ + FCoreDelegates::OnHandleSystemError.Remove(SystemErrorHandle); + FCoreDelegates::OnShutdownAfterError.Remove(ShutdownAfterErrorHandle); + if (GLog) + { + GLog->RemoveOutputDevice(&LoggedMessage); + } +} + +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(); + + FString Message; + FString StackTrace; + if (LooksLikeStackFrame(History)) + { + 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) + { + 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(); + } + } + if (Message.IsEmpty() && LoggedMessage && LoggedMessage[0] != 0) + { + Message = FString(LoggedMessage).Replace(TEXT("\r\n"), TEXT("\n")).TrimStartAndEnd(); + } + if (Message.IsEmpty() && ExceptionDescription && ExceptionDescription[0] != 0) + { + Message = FString(ExceptionDescription).TrimStartAndEnd(); + } + + // "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); +} + +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 + // 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. + 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 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); + // 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. + 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(); + 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 new file mode 100644 index 0000000..153863f --- /dev/null +++ b/Source/Aptabase/Private/AptabaseCrashReporter.h @@ -0,0 +1,77 @@ +#pragma once + +#include +#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 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 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; + + /** 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 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 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 new file mode 100644 index 0000000..4d202c2 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.cpp @@ -0,0 +1,127 @@ +#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& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal) +{ + if (!Queue.Enqueue(Message, ErrorType, StackTrace, bFatal) || bFlushScheduled.exchange(true)) + { + return; + } + + // Coalesce bursts from any thread into one game-thread task; HTTP requests are only started there. + TWeakPtr WeakThis = AsShared(); + AsyncTask( + ENamedThreads::GameThread, + [WeakThis]() + { + if (const auto Dispatcher = WeakThis.Pin()) + { + Dispatcher->bFlushScheduled = false; + Dispatcher->Flush(); + } + } + ); +} + +bool FAptabaseErrorDispatcher::EnqueueReport(FAptabaseErrorReport Report) +{ + return Queue.EnqueueReport(MoveTemp(Report)); +} + +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..dec7d4e --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorDispatcher.h @@ -0,0 +1,31 @@ +#pragma once + +#include + +#include "AptabaseErrorQueue.h" +#include + +/** 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& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal); + /** Queues a previously captured report (see FAptabaseErrorQueue::EnqueueReport); call Flush to send it. */ + bool EnqueueReport(FAptabaseErrorReport Report); + 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/AptabaseErrorQueue.cpp b/Source/Aptabase/Private/AptabaseErrorQueue.cpp new file mode 100644 index 0000000..8f46953 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorQueue.cpp @@ -0,0 +1,86 @@ +#include "AptabaseErrorQueue.h" + +#include +#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& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal) +{ + FScopeLock Lock(&Mutex); + if (!bActive || Outstanding >= MaxPendingReports || Seen.Num() >= MaxUniqueErrorsPerSession) + { + return false; + } + + FAptabaseErrorReport Report = FAptabaseErrorReport::Create(Message, ErrorType, StackTrace, bFatal, Context); + const uint64 Fingerprint = Report.GetFingerprint(); + if (Seen.Contains(Fingerprint)) + { + return false; + } + Seen.Add(Fingerprint); + Pending.Add(MoveTemp(Report)); + ++Outstanding; + 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); + 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); + return; + } + --Outstanding; + if (!Report.PersistedPath.IsEmpty()) + { + // Delivered or permanently rejected: either way the file must not be sent again. + IFileManager::Get().Delete(*Report.PersistedPath, false, false, true); + } +} + +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..6b7f75e --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorQueue.h @@ -0,0 +1,34 @@ +#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& 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); + +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..c99e793 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorReport.cpp @@ -0,0 +1,87 @@ +#include "AptabaseErrorReport.h" + +#include + +FAptabaseErrorReport FAptabaseErrorReport::Create(const FString& Message, const FString& ErrorType, const FString& StackTrace, bool bFatal, 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") : 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; +} + +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(); + 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..dc703b9 --- /dev/null +++ b/Source/Aptabase/Private/AptabaseErrorReport.h @@ -0,0 +1,43 @@ +#pragma once + +#include + +class FJsonObject; + +/** Context copied on the game thread at session start; safe to use from any thread, including the error handler. */ +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& 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; + FString Timestamp; + 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 4c94374..c309f93 100644 --- a/Source/Aptabase/Private/AptabaseSettings.h +++ b/Source/Aptabase/Private/AptabaseSettings.h @@ -56,6 +56,14 @@ class APTABASE_API UAptabaseSettings : public UDeveloperSettings */ UPROPERTY(Config, EditAnywhere, Category = "Aptabase Analytics", meta = (Unit = "s")) 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 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; 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..2ddd1b7 --- /dev/null +++ b/Source/Aptabase/Private/Tests/AptabaseErrorReportingTests.cpp @@ -0,0 +1,391 @@ +#if WITH_DEV_AUTOMATION_TESTS + +#include +#include +#include +#include +#include +#include +#include + +#include "AptabaseCrashReporter.h" +#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("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"))); + 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("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"))); + 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, 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(""), 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(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; +} + +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("Offline"), TEXT("NetworkError"), TEXT("original stack"), 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("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(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("Overflow"), TEXT("Error"), TEXT(""), 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("Overflow"), TEXT("Error"), TEXT(""), 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("test"), TEXT("Error"), TEXT(""), false)); + Queue.StartSession(TestContext()); + for (int32 Index = 0; Index < FAptabaseErrorQueue::MaxUniqueErrorsPerSession; ++Index) + { + TestTrue(TEXT("Unique report accepted"), Queue.Enqueue(FString::FromInt(Index), TEXT("Error"), TEXT(""), 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("Over cap"), TEXT("Error"), TEXT(""), false)); + Queue.EndSession(); + 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("0"), TEXT("Error"), TEXT(""), 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(FString::FromInt(Index), TEXT("WorkerError"), TEXT(""), false); + } + } + )); + } + 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; +} + +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()" + ), + TEXT(""), + TEXT(""), + 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()"), 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()"), 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"), 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(""), 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 diff --git a/Source/Aptabase/Public/AptabaseBlueprintLibrary.h b/Source/Aptabase/Public/AptabaseBlueprintLibrary.h new file mode 100644 index 0000000..73012d0 --- /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 = FString(TEXT("Error")), const FString& StackTrace = FString(), bool bFatal = false); +}; diff --git a/llms.txt b/llms.txt index f237063..9ab8bc3 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 crash reports. 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 | +| 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. @@ -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 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. The error handler writes the crash report to `Saved/Aptabase/Crashes` and the next session start sends it under the crashed session's ID; the newest 10 pending reports are kept. On Windows the handler also attempts an immediate send with a 3 second timeout. 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 manual reports live in memory only; crash reports are persisted on disk until delivered or permanently rejected. + ## Platform Notes - Supports all platforms supported by Unreal Engine 5