Skip to content

Error reporting: Track Error API and opt-in crash reporting - #21

Merged
ivnbogdan merged 4 commits into
mainfrom
feat/error-reporting
Sep 27, 2026
Merged

ivnbogdan merged 4 commits into
mainfrom
feat/error-reporting

Conversation

@ivnbogdan

Copy link
Copy Markdown
Contributor

Summary

Adds structured error reporting to the Unreal SDK (plugin version 0.2.0 → 0.3.0).

  • UAptabaseBlueprintLibrary::TrackError and the Track Error Blueprint node for handled and fatal error reports. Reports carry capture-time session, timestamp, OS, app/SDK version, severity, kind and debug mode, truncated to the server limits.
  • Opt-in crash reporting (bEnableCrashReporting, off by default). Fatal errors that reach the engine's error handler during an active session (asserts, Fatal logs, LowLevelFatalError, native exceptions/signals) are built into a report from GErrorHist, written to Saved/Aptabase/Crashes, and sent at the next session start under the crashed session's ID. Windows also attempts an immediate send with a 3 s timeout, since the HTTP thread keeps running there. The newest 10 pending reports are kept.
  • Delivery: one POST /api/v0/error per report. Network failures and HTTP 408/429/5xx are retried on later flushes; other 4xx (including 403 quota exhaustion) are discarded. Queue bounded to 25 outstanding reports, deduplicated up to 100 unique errors per session.
  • Provider hardening: StartSession() is idempotent while a session is active; in-flight event requests are cancelled and unbound when the provider is destroyed; responses without a body are guarded.
  • Docs: README error-reporting section, llms.txt, CHANGELOG.md, and Docs/testing.md.

Test plan

  • CI compile passes (this PR is the first build of the branch; the last commit fixes a duplicate EnqueueReport declaration/definition).
  • Run the Aptabase.Errors automation suite in an editor build — see Docs/testing.md. Covers JSON contract and field limits, retry codes, session context across sessions, deduplication, queue capacity, concurrent capture, GErrorHist parsing (Windows and Apple formats), and crash-report persistence/loading.
  • Manual end-to-end against a local HTTP server as SH host: event → /api/v0/events, Track Error → /api/v0/error; verify 202 accepted, 400/403 not retried, 408/429/500 retried.
  • Manual crash check from a packaged/-game build: file appears under Saved/Aptabase/Crashes, is sent on the next launch and deleted after 2xx/4xx, survives an offline launch.

🤖 Generated with Claude Code

ivnbogdan and others added 4 commits September 9, 2026 14:22
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
@ivnbogdan
ivnbogdan merged commit fa99cfe into main Sep 27, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant