Manage your PDB Files

Last updated on 24 July, 2023 6:26 AM

Upload the debug symbol in Windows

To get a call stack from your crash dump, the AccelByte Development Toolkit (ADT) backend needs the debug symbol information from your game or application. To get this information, upload the debug symbols, which are .pdb files and executables or .exe files in Windows, to the ADT backend.

To upload the files, perform these tasks, in this order:

1. Extract the CrashReportClient.pak to a temporary folder.
2. Modify the CrashReportClient.ini file from the temporary folder.
3. Repack the CrashReportClient.pak.
4. Parse the .pdb files for symbols and zip them.
5. Archive the .exe and .pdb file to the shipping folder in a single zip file.
6. Upload the .exe and .pdb zip files to the ADT backend, as shown below.

Without Inline Configuration

BlackBoxCLI.exe upload

With Inline Configuration

BlackBoxCLI.exe upload --apikey asdf1234 --namespace myawesomegame --game-project D:\path\to\myawesomegame --game-engine D:\UnrealEngine\UE4.25 --game-archive D:\path\to\packaged\awesomegame --platform-name windows --platform-arch x64

Use the ADT CLI to upload the build's debug symbol

You can use the ADT CLI to upload the debug symbol for the editor and packaged builds. Upload them both the same way, but with an additional --editor-build argument for the editor.

Without inline configuration

BlackBoxCLI.exe upload --editor-build

It takes a few minutes to compress and upload your .pdb and .exe files to ADT's backend. When the upload finishes, the results are similar to the example below.

BlackBoxCLI.exe upload
Build ID: af59abac-f560-47b5-bf47-416128d8e282
Try to open Game Config File DefaultEngine.ini ("D:\\blackbox-sdk\\SampleGame\\Config\\DefaultEngine.ini")
Registering build...OK
Zipping executable and pdb...
Compressing: AccelMania-Win64-DebugGame.exe [113965/113965] kB
Compressing: AccelMania-Win64-DebugGame.pdb [145764/145764] kB
Dump Symbol...
Compressing: AccelMania-Win64-DebugGame.sym [73980/73980] kB
Upload executable and pdb...
Preparing to upload PDB files...
Uploading...
Sent: 71525/71525 KB
Upload Successful...
Preparing to upload Breakpad symbol...
Uploading...
Sent: 7307/7307 KB
Upload Successful...
Updating Crash Reporter Client...OK
Success!

You can also use these options to parse the game's executable file and upload the filtered .pdb contents to the ADT backend.

Options	Include	Exclude	Description
-h,--help	-	-	Print help message and exit
-d,--dump-path	-	-	Specify where to dump the output JSON file. If you don't specify a path, the system won't create the dump file.
-I,--game-build-stamp	-	--upload-only	Specify the game build stamp
-u,--upload-only	--dump-path	--game-build-stamp	Skip the PDB parsing phase and go straight to upload, assuming JSON already exists.
-Z,--zip-file-location	-	-	Path to a zip file for upload. This option expects a prepared zip file.
-E, --editor-build			Upload the PDB for editor build. This option collects all the Unreal Editor's PDB files and uploads the information to ADT's backend.
--platform-arch			The platform arch of the game debug symbols to upload (e.g x64)
--platform-name			The platform name of the game debug symbols to upload, such as Windows, xsx, xboxonegdk, PS5

Upload the Linux debug symbol for Unreal 5

To upload the Linux debug symbol for Unreal 5, you need an extra configuration in your game. Add the following config field and section to the DefaultEngine.ini file of your game:

[/Script/LinuxPlatform.LinuxTargetSettings]
bPreservePSYM=True

caution

After you add this configuration file, clean any build artifacts, which are usually in the intermediate directory, before you try to build a Linux game or errors result.

Once you are ready to build your Linux game, upload the Linux debug symbol by calling the upload command for Unreal 5:

With inline configuration

BlackBoxCLI.exe upload --apikey asdf1234 --namespace myawesomegame --game-project D:\path\to\myawesomegame --game-engine D:\UnrealEngine\UE4.25 --game-archive D:\path\to\packaged\awesomegame --platform-name linux-server --platform-arch x64

Filter the PDB Symbols [Deprecated]

caution

We deprecated this command.

When you need to find a keyword for your project, filtering PDB symbols can be useful. Follow these steps to learn how to do this.

BlackBoxCLI.exe filter add compiland include keyword1 keyword2 keyword3

1. Make sure you separate the keywords with spaces to create a valid command chain, as follows:

BlackBoxCLI.exe filter add compiland include FAvengersSDK

2. Use the following command to see whether the current filter is active:

BlackBoxCLI.exe filter list

3. The output should be:

compiland:
  include:
    [Aa]vengers
    [Aa]ccel[Mm]ania
function:
  include:
    [Tt]ick
public:
  exclude:
    public:
    static
    struct
    const
    [Cc]lass
    enum
    void
    vftable
  include:
    AccelMania
    Avengers

caution

We deprecated this command.

Once you filter the PDB symbols, dump them to your local machine, then change them into a JSON file. Parse the game executable file to use the dump command as shown below.

To dump the PDB symbol into the JSON file, execute this command.

BlackBoxCLI.exe dump -d <file output>

In this example, we dump the PDB symbol into a JSON file named mydumpedinfo.json.

BlackBoxCLI.exe dump -d .\mydumpedinfo.json

Options	Description
-h,--help	Print help message and exit
-f,--pdb-file-name	Specify PDB file to upload
-d,--dump-path	Specify the location to dump the output JSON file to
-I,--game-build-stamp	Specify game build stamp
-p,--print	Print the parsing result to the console screen