Live (retail) crash reporting
Overview
AccelByte Development Toolkit (ADT) can collect crashes from builds that players run after release, not only from internal development builds. ADT labels each crash with an Origin so you can tell them apart:
- Players: a live crash, from a released build or a retail console.
- Internal: a crash from development, QA, or a devkit.
How a crash reaches ADT, and what makes it a Players crash, depends on the platform.
| Platform | How the crash reaches ADT | When ADT labels it Players | More information |
|---|---|---|---|
| Windows and Linux (Unreal Engine) | Unreal Crash Report Client (CRC) sends it right after the crash. | The build was registered as a release candidate (RC) and prepared with the ADT CLI, or the build is set to Live in ADT Web. | Prepare and release a live build |
| macOS (Unreal Engine) | The ADT SDK sends it. | The build was registered as an RC and prepared with the ADT CLI. | Prepare and release a live build |
| PlayStation 5 | ADT collects it from Sony Crash Reporting. | The crash came from a retail console. | PlayStation 5 retail crash reporting |
| Xbox Series X|S and Xbox One (Microsoft Game Development Kit (GDK)) | The ADT SDK sends it the next time the game starts. | The build was registered as an RC and prepared with the ADT CLI. | Xbox consoles crash reporter integration guide |
Live crash reporting is not supported for Unity projects. The ADT CLI's build prepare command is available for Unreal Engine only, and the Unity SDK doesn't mark crashes as live.
This page covers Unreal Engine games on Windows, Linux, macOS, and Xbox, and how to monitor live crashes on every platform, including PlayStation 5. For the Xbox-specific setup, refer to the Xbox guide in the table above.
How ADT decides that a crash comes from players
ADT labels a crash Players, at the moment it's received, if either of the following is true:
- The crash was sent with the live flag (
Live=true). When you runbuild prepareon a build registered as an RC, the ADT CLI turns the flag on: it addsLive=trueto the crash URL on Windows and Linux, and setsLiveBuild=truefor the ADT SDK on macOS and Xbox. This doesn't depend on whether the build is set to Live in ADT Web. - The crash was sent to a crash URL that includes the build ID (Windows and Linux), and that build is set to Live in ADT Web.
ADT doesn't relabel crashes it has already received. If you set a build to Live later, crashes that arrived earlier keep their label.
Prerequisites
- ADT CLI 2.31.1 or later.
- The ADT Unreal SDK integrated into your project. To learn how, refer to ADT SDK integration.
- For Windows and Linux: Unreal's Crash Report Client configured to send crashes to ADT. To learn how, refer to Configure the Unreal CRC.
- A game version in ADT. To learn how, refer to Manage game versions.
Prepare and release a live build
Repeat these steps for every build you release, including patches. The build ID is part of the build's crash configuration, so each released build needs its own registration.
1. Register the build as a release candidate
Run build register with the --release-candidate flag:
.\BlackBoxCLI.exe build register --namespace <Namespace> --apikey <APIKey> --game-project <GameProjectPath> --game-engine <GameEnginePath> --platform-name <Platform> --platform-arch x64 --release-candidate
The CLI registers the build with the RC release status and writes its build ID and version ID to your project's Config/BlackBox.ini.
2. Set the crash URL (Windows and Linux)
macOS and Xbox builds send crashes through the ADT SDK and don't use this crash URL. For these platforms, skip this step and continue with step 3.
For Windows and Linux, run crash-url set while the build is still an RC:
.\BlackBoxCLI.exe crash-url set --namespace <Namespace> --apikey <APIKey> --game-engine <GameEnginePath>
Because the current build is an RC, the CLI writes a crash URL that includes the version ID and build ID:
https://blackbox.accelbyte.io/data/public/namespaces/<Namespace>/versions/<VersionID>/builds/<BuildID>/crashreport/<APIKey>
- Run this step after step 1 and before you set the build to Live. If the current build isn't an RC, the CLI writes the regular development URL instead, without any warning.
- The CLI writes the URL to the Crash Report Client configuration of your engine installation (
<GameEnginePath>\Engine\Programs\CrashReportClient\Config\DefaultEngine.ini). Every project that you package with this engine on this machine uses the new URL.
3. Prepare the build
Run build prepare:
.\BlackBoxCLI.exe build prepare --namespace <Namespace> --apikey <APIKey> --game-project <GameProjectPath> --game-engine <GameEnginePath>
For an RC build, the CLI:
- Keeps the ADT SDK enabled in
Config/BlackBox.ini. - Sets
LiveBuild=trueinConfig/BlackBox.ini. The ADT SDK uses it to send crashes with the live flag on macOS and Xbox. - Adds
Live=trueto the crash URL in the engine's Crash Report Client configuration (Windows and Linux).
If the engine path isn't configured, the CLI logs Engine path is not configured, Live=true not added to the crash reporter's DataRouterUrl and skips the last change. If the crash URL in the engine's Crash Report Client configuration isn't an ADT crash URL, the CLI logs DataRouterUrl is not an ADT crash URL, Live=true not added and also skips it.
For a build that isn't an RC, build prepare sets LiveBuild=false.
Because the ADT SDK stays enabled, your live build includes the same ADT SDK components as a development build, such as the crash video helper and the Issue Reporter.
With ADT CLI versions older than 2.31.1, build prepare turns the ADT SDK off for RC builds and doesn't add the live flag. Crashes from these builds are only labeled Players after you set the build to Live in ADT Web.
4. Package the build and upload symbols
- Package your game. For Windows and Linux, include the Crash Report Client in the package. For Shipping builds, include debug files so that you can upload symbols. To learn more, refer to Manage your PDB Files.
- Upload the symbols with the ADT CLI
uploadcommand. You don't need to upload the game binaries to ADT to get call stacks for live crashes.
The packaged game contains your API key, in the crash URL or in Config/BlackBox.ini.
5. Release the build and set it to Live
After you release the build to players, for example on Steam or the Epic Games Store, set it to Live in ADT Web. This step:
- Changes the build's release status from RC to Live.
- Counts that build's Windows and Linux crashes against the live daily crash limit instead of the development limit, if they're sent to a crash URL that includes the build ID. macOS and Xbox crashes always count against the development limit, even after you set the build to Live.
- Shows the Show filter on the build's Crash Reporter tab.
You can't revert a build from Live. Only RC builds can be set to Live.
ADT Web lets you set an RC build to Live from two places:
From the build list
- In ADT Web, go to the Versions page.
- Click the version that contains your RC build.
- Click the ellipsis (three-dot) menu on the build with the RC flag, then click Set this build to Live.
- In the Release Confirmation dialog, click Yes. The build flag changes from RC to Live.
From the build page
- In ADT Web, go to the Versions page.
- Click the version that contains your RC build.
- Click the build name to open the build page.
- Click Set to Live, then click Yes in the Release Confirmation dialog. The build flag changes to Live.
Monitor live crashes
On the Crashes page
- In ADT Web, go to Crashes.
- Use the Origin filter to show crashes with the Players origin, crashes with the Internal origin, or All Origins. The Origin column shows how many crashes in each crash group came from players and how many were internal.
If the Players filter shows no crashes, the page tells you whether your PlayStation 5 crash collection from Sony is not connected, connected but with nothing received yet, or stopped. You can see the connection status in Game Settings > Retail Crashes. To learn more, refer to PlayStation 5 retail crash reporting.
On a crash's details
Open a crash. On the General tab, the Origin row shows the label and what it is based on:
| Platform | Players | Internal |
|---|---|---|
| Windows, Linux, macOS | Live build (see the note below) | Build not set to Live, or Editor for editor builds |
| PlayStation 5 | Retail console, based on the hardware type that Sony reports | Devkit or test kit |
| Xbox | Retail console, based on the build (see the note below) | Devkit or test kit, based on the build |
- For Windows, Linux, and macOS, the Origin row shows Live build for every Players crash. This includes crashes sent with the live flag from a prepared RC build that isn't set to Live in ADT Web yet. It shows Build not set to Live for every other crash, except crashes from editor builds.
- For Xbox, ADT doesn't detect the console hardware type. The Origin row shows Retail console for every crash from a build that was registered as an RC and prepared, including crashes from a devkit. It shows Devkit or test kit for every other build, including crashes from a retail console.
In a build
- In ADT Web, go to the Versions page.
- Click the version that contains your live build, then click the build name.
- Open the Crash Reporter tab. For a build set to Live, each crash group has a LIVE or DEV badge, and you can use the Show filter to show Live crashes only.
Daily crash limit
By default, each namespace can receive up to 1,000 live crashes and 1,000 development crashes per day. The limits reset at 00:00 UTC. When a limit is reached, ADT rejects further crashes in that pipeline until the next reset.
The Players label and the live limit are separate. A crash labeled Players doesn't always count against the live limit. The table below shows which limit each kind of crash counts against.
| Crashes | Limit they count against |
|---|---|
| Windows and Linux crashes sent to a crash URL with a build ID, for a build set to Live | Live |
| All other crashes sent by the Crash Report Client or the ADT SDK. This includes Xbox and macOS crashes labeled Players, and Windows and Linux crashes labeled Players from an RC build that isn't set to Live yet. | Development |
| PlayStation 5 crashes collected from Sony | Not counted |
To learn more, refer to Crash limit management.
Limitations
- Unity projects aren't supported.
- Each released build must be registered, prepared, and packaged with its own build ID.
- Crashes keep the label they had when ADT received them.
crash-url setchanges the crash URL for every project packaged with that engine installation.