Debug Information Files
Debug information files allow Sentry to extract stack traces and provide more
information about crash reports for most compiled platforms. sentry-cli
can be
used to validate and upload debug information files. For more general
information, refer to Debug Information Files.
Permissions
The sentry-cli
requires an Auth Token to be authenticated with a set of Permissions & Scopes so that Debug Information Files can be uploaded. To do this, you must have either a project:releases
or project:write
Scope.
Source maps, while also being debug information files, are handled differently in Sentry. For more information see Source Maps in sentry-cli.
Checking Files
Not all debug information files can be used by Sentry. To see if they are usable
or not, you can use the sentry-cli difutil check
command:
sentry-cli difutil check mylibrary.so.debug
Debug Info File Check
Type: elf debug companion
Contained debug identifiers:
> 924e148f-3bb7-06a0-74c1-36f42f08b40e (x86_64)
Contained debug information:
> symtab, debug
Usable: yes
This will report the debug identifiers of the debug information file as well as if it passes basic requirements for Sentry.
Finding Files
If you see in Sentry's UI that debug information files are missing, but you are
not sure how to locate them, you can use the sentry-cli difutil find
command
to look for them:
sentry-cli difutil find <identifier>
Additionally, sentry-cli debug-files upload
can automatically search for files in a
folder or ZIP archive.
Creating Source Bundles
To get inline source context in stack traces in the Sentry UI, sentry-cli
can
scan debug files for references to source code files, resolve them in the local
file system and bundle them up. The resulting source bundle is an archive
containing all source files referenced by a specific debug information file.
This is particularly useful when building and uploading debug information files
are detached. In this case, a source bundle can be created when building and can
be uploaded at any later point in time with sentry-cli debug-files upload
.
To create a source bundle, use the difutil bundle-sources
command on a list of
debug information files:
# on the build machine:
sentry-cli difutil bundle-sources /path/to/files...
# at any later time:
sentry-cli debug-files upload --type sourcebundle /path/to/bundles...
To create multiple source bundles for all debug information files, use the command on each file individually.
Alternatively, add the --include-sources
option to the debug-files upload
command,
which generates source bundles on the fly during the upload. This requires that
the upload is performed on the same machine as the application build:
sentry-cli debug-files upload --include-sources /path/to/files...
Uploading Files
Use the sentry-cli debug-files upload
command to upload debug information files to
Sentry. The command will recursively scan the provided folders or ZIP archives.
Files that have already been upload are skipped automatically.
We recommend uploading debug information files when publishing or releasing your application. Alternatively, files can be uploaded during the build process. See Debug Information Files for more information.
You need to specify the organization and project you are working with because debug information files work on projects. For more information about this refer to Working with Projects.
A basic debug file upload can be started with:
sentry-cli debug-files upload -o <org> -p <project> /path/to/files...
> Found 2 debug information files
> Prepared debug information files for upload
> Uploaded 2 missing debug information files
> File processing complete:
PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)
After the upload, Sentry analyzes the files to symbolicate future events. If you
want to send a native crash to Sentry to verify correct operation, ensure that
the debug files are listed in Project Settings > Debug Files. Alternatively,
specify --wait
in the CLI, which will block until server-side analysis is
complete:
sentry-cli debug-files upload -o <org> -p <project> --wait /path/to/files...
> Found 2 debug information files
> Prepared debug information files for upload
> Uploaded 2 missing debug information files
> File processing complete:
OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)
Upload Options
There are a few options you can supply to the upload command:
--wait
- Wait for server-side processing of uploaded files. By default,
debug-files upload
completes once the debug files have been uploaded to Sentry. After this, Sentry analyzes the files and makes them available for symbolication. It makes sense to specify--wait
to ensure that debug files are ready before sending crashes to Sentry. This may slow down the command and is not recommended for CI builds.
--no-upload
- Disables the actual upload. This runs all steps for the processing but does not trigger the upload (this also automatically disables reprocessing). This is useful if you just want to verify the setup or skip the upload in tests.
--no-unwind
- Do not scan for stack unwinding information. Specify this flag for builds with disabled FPO, or when stack walking occurs on the device. This usually excludes executables and libraries. They might still be uploaded, if they contain debug information.
--no-debug
- Do not scan for debug information. This will usually exclude debug companion files. They might still be uploaded, if they contain stack unwinding information.
--include-sources
- Scans the debug files for references to source code files. If referenced files
are available on the local file system, they are bundled and uploaded as a
source archive. This allows Sentry to resolve source context. Only specify
this command when uploading from the same machine as the build. Otherwise, use
difutil bundle-sources
to generate the bundle ahead of time.
--derived-data
- Search for dSYMs in the derived data folder. Xcode stores its build output in this default location.
--no-zips
- By default,
sentry-cli
will open and search ZIP archives for debug files. This is especially useful when downloading builds from iTunes Connect or prior build stages in a CI environment. Use this switch to disable if your search paths contain large ZIP archives without debug files to speed up the search.
--force-foreground
- This option forces the upload to happen in the foreground. This only affects uploads invoked from Xcode build steps. By default, the upload process will detach when started from Xcode and finish in the background. If you need to debug the upload process it might be useful to force the upload to run in the foreground.
--info-plist
- Overrides the search path for
Info.plist
, useful if it is located in a non-standard location.
--no-reprocessing
- This parameter prevents Sentry from triggering reprocessing right away. It can be useful under rare circumstances where you want to upload files in multiple batches and you want to ensure that Sentry does not start reprocessing before some optional dSYMs are uploaded. Note though that someone can still in the meantime trigger reprocessing from the UI.
--symbol-maps
- Resolve hidden symbols in iTunes Connect builds using BCSymbolMaps. This is needed to symbolicate crashes if symbols were not uploaded to Apple when publishing the app in the AppStore.
Symbol Maps
If you are hiding debug symbols from Apple, the debug files will not contain many useful symbols. In that case, the sentry-cli upload will warn you that it needs BCSymbolMaps:
sentry-cli debug-files upload ...
> Found 34 debug information files
> Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps)
In this case, you need the BCSymbolMaps that match your files. Typically, these
are generated by the Xcode build process. Supply the --symbol-maps
parameter
and point it to the folder containing the symbol maps:
sentry-cli debug-files upload --symbol-maps path/to/symbolmaps path/to/debug/symbols
Breakpad Files
In contrast to native debug files, Breakpad symbols discard a lot of information that is not required to process minidumps. Most notably, inline functions are not declared, such that Sentry is not able to display inline frames in stack traces.
If possible, upload native debug files such as dSYMs, PDBs or ELF files instead of Breakpad symbols.
ProGuard Mapping Upload
sentry-cli
can be used to upload ProGuard files to Sentry; however, in most
situations, you would use the Gradle
plugin to do that. Nevertheless, there may be
situations where you would upload ProGuard files manually. For instance,
when you only release some of the builds you're creating.
You need to specify the organization and project you are working with because ProGuard files work on projects. For more information about this refer to Working with Projects.
The upload-proguard
command is the one to use for uploading ProGuard files. It
takes the path to one or more ProGuard mapping files and will upload them to
Sentry.
sentry-cli upload-proguard \
app/build/outputs/mapping/{BuildVariant}/mapping.txt
Since the Android Sentry SDK needs to know the UUID of the mapping file, you need
to associate it with the upload. However, you first have to place that UUID into the AndroidManifest.xml
file:
<application>
<meta-data android:name="io.sentry.proguard-uuid" android:value="A_VALID_UUID" />
</application>
The same UUID needs to be used to upload the mapping file:
sentry-cli upload-proguard \
--uuid A_VALID_UUID \
app/build/outputs/mapping/{BuildVariant}/mapping.txt
After the upload, Sentry deobfuscates future events. To make sure that it worked, you can check Project Settings > ProGuard and see if the upload mapping files are listed.
Upload Options
--no-reprocessing
- This parameter prevents Sentry from triggering reprocessing right away. It can be useful under rare circumstances where you want to upload files in multiple batches and you want to ensure that Sentry does not start reprocessing before some optional dSYMs are uploaded. Note though that someone can still in the meantime trigger reprocessing from the UI.
--no-upload
- Disables the actual upload. This runs all steps for the processing but does not trigger the upload (this also automatically disables reprocessing). This is useful if you just want to verify the mapping files and write the ProGuard UUIDs into a properties file.
--require-one
- Requires at least one file to upload or the command will error.
JVM Source Bundles
If you're using a build tool we don't support, or you prefer not to use Sentry's build tool plugins, you'll need to upload source bundle files manually.
See the build tool plugins we currently support here:
You can also upload ProGuard files manually with sentry-cli
for any JVM-based language like
Java or Kotlin.
Before you can upload source files, you must configure the Sentry CLI with the organization and project you are uploading bundle files for. See the CLI docs on Working with Projects to learn how to do this.
Creating a Source Bundle
Run the debug-files bundle-jvm
command to create a source bundle for a
source directory.
sentry-cli debug-files bundle-jvm \
--output some/dir \
--debug-id A_VALID_UUID \
path/to/source/dir
You must provide the UUID of the source bundle for the Java/Android SDK to send. More details can be found in the Source Context docs for Java and the Source Context docs for Android.
Uploading a Source Bundle
The debug-files upload
command allows you to upload the source
bundle you created to Sentry.
sentry-cli debug-files upload \
--type jvm \
output/path/of/bundle-jvm/command
After the upload, Sentry will attach Source Context to future events.
To make sure these steps worked, check Project Settings > Debug Files in Sentry.io to see if the uploaded source bundle files are listed.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").