Readable Stack Traces

Debug information files allow Sentry to extract stack traces and provide additional information about crash reports. In order to get readable stack traces in Sentry when your game crashes, you need to export your project using an export template that contains debug information. For the official builds, Godot Engine only provides templates without debug symbols. This guide covers how to create such templates and use them to export your project with full debug information available in Sentry.

To get debug information, we need to compile export templates with debug symbols produced. You'll need SCons build tool, Python, and a C++ compiler for your target platform installed.

Getting Godot Source

Start in a terminal with Git available. Clone Godot Engine repository and switch to your preferred version tag (or branch):

git clone https://github.com/godotengine/godot
cd godot
git checkout 4.3-stable

Compiling Templates

To compile the Godot release export template with debug symbols, run the following command:

scons platform=windows target=template_release production=yes debug_symbols=yes separate_debug_symbols=yes

If all goes well, the export template files should appear as the result of the build process in the bin/ directory inside the Godot source tree. When using MSVC on Windows, you will find .exe files alongside .pdb files, which contain debug information.

Exporting Project

Now you can export your project using your custom template. In the Godot Export dialog window, follow these steps:

1. Select or add an export preset.
2. Enable the Advanced Options toggle.
3. In the Options tab, under Custom Template -> Release, assign your custom template executable file.

This will configure your project to use the custom export template with the debug symbols you compiled earlier.

You should now be able to export your project using this template. Just make sure to uncheck Export with Debug in the Export Project... dialog, as you will need to compile and use the template_debug for that option.

Uploading Debug Symbols

In order to see readable stack traces in Sentry, you also need to upload your debug symbols. The easiest way to do it is by using Sentry CLI tools. These tools allow you to upload the necessary debug information, making the stack traces useful for debugging.

Log in to Sentry via the CLI by running the following command:

sentry-cli login

It will prompt you to create an auth token in your web browser. Follow the instructions, generate the token, and then paste it into the command-line prompt when asked.

To upload debug symbols to Sentry using sentry-cli, run the following command:

sentry-cli debug-files upload --org <YOUR_ORGANIZATION> --project <YOUR_PROJECT> ./bin

Replace <YOUR_ORGANIZATION> and <YOUR_PROJECT> with your actual organization and project slugs or IDs. This will upload the files with debug information from the ./bin directory to Sentry.

Example output:

$ sentry-cli debug-files upload --org sentry-sdks --project sentry-godot ./bin
> Found 4 debug information files
> Prepared debug information files for upload
> Uploading completed in 7.429s
> Uploaded 4 missing debug information files
> File upload complete:

  UPLOADED 88b87add-d362-406c-b3b7-9f019072a7e0-1 (godot.windows.template_release.x86_64.console.exe; x86_64 executable)
  UPLOADED 88b87add-d362-406c-b3b7-9f019072a7e0-1 (godot.windows.template_release.x86_64.console.pdb; x86_64 debug companion)
  UPLOADED 07c660ac-3f72-4c75-8aca-1378240cc949-1 (godot.windows.template_release.x86_64.pdb; x86_64 debug companion)
  UPLOADED 07c660ac-3f72-4c75-8aca-1378240cc949-1 (godot.windows.template_release.x86_64.exe; x86_64 executable)

Congratulations! You're all set up. Your exported project should now produce symbolicated stack traces in Sentry.