Debug Symbols Uploading
Learn how the Unreal Engine SDK handles debug symbols upload.
Sentry requires debug information files to symbolicate crashes. The Unreal Engine SDK provides an automated upload functionality for those symbol files that rely on the sentry-cli. This is done automatically, so running the sentry-cli manually isn't required. The symbol upload happens during the execution of PostBuildSteps, as specified in the Sentry.uplugin file. The sentry-cli executables for Windows, macOS, and Linux are included as part of the Unreal Engine SDK package. They can also be downloaded manually via the settings menu if the plugin was installed from the UE Marketplace.
For Android, debug symbols upload is handled by Sentry Android Gradle Plugin. By default, it bumps Gradle version to 7.5 automatically, however one can fallback to using its legacy version in case compatibility issues with other third-party plugins arise.
The automated debug symbols upload is disabled by default and requires configuration. To configure it, navigate to Project Settings > Plugins > Sentry, then enable "Upload debug symbols automatically".
Alternatively, debug symbol upload can be enabled by setting the SENTRY_UPLOAD_SYMBOLS_AUTOMATICALLY environment variable to True. This can be especially helpful in CI/CD environments where manual configuration is impractical.
Sentry will upload debug symbols only for build configurations and target types that are enabled in the "Misc" section of the plugin settings.
The sentry-cli require you to specify the organization and project to work with as well as a token to authenticate with Sentry. The Unreal Engine SDK provides two ways to configure these settings - either by using a properties file (default) or environment variables.
To configure the sentry-cli using properties file enter the Auth Token, Organization Slug, and Project Name. Note, that the Unreal Engine SDK automatically creates a sentry.properties file at the root of your project directory to store the configuration. This configuration file should never be made publicly available.
The sentry-cli can be configured by setting the following environment variables which will be automatically picked up during the debug symbol upload if the properties file is not found:
export SENTRY_ORG=example-org
export SENTRY_PROJECT=example-project
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
To upload debug symbols to Sentry manually, run sentry-cli through the command line. You can either use the provided executables from within the package, or follow the sentry-cli documentation to make it available globally. To upload debug symbols run the following command:
sentry-cli --auth-token sntrys_YOUR_TOKEN_HERE debug-files upload --org example-org --project example-project PATH_TO_SYMBOLS
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").