ELF Symbol Upload
sentry-cli can upload ELF symbols generated on various Linux distributions to
Sentry to allow symbolication of Linux and Android app crashes. ELF stands for
Executable and Linkable Format, the file format used for binaries on Linux.
Unlike other platforms, there is no standardized container for debug symbols.
They are part of the binary (executable or library) and stripped when generating
release builds due to their size. However, there is a way to retain them in a
separate file (either in a different location or with
# There is an executable called "binary" in the CWD objcopy --only-keep-debug binary binary.debug strip -g binary objcopy --add-gnu-debuglink=binary.debug binary
Shared libraries installed via package managers usually provide their debugging
information in separate
*-dev packages and put it in locations like
/usr/local/debug/.... To receive symbolicated stack traces from those
libraries, make sure to also upload their symbols in addition to your app’s
upload-dif to upload ELF symbols and specify the
elf type. The command
will recurively scan the provided folders or ZIP archives. If you stripped debug
information into separate files, this uploads both the stripped executable and
the debug information file to achieve highest stack trace quality. This is
particularly helpful for release builds with frame pointer omission (FPO).
All recent compilers and linkers generate a unique build ID and even retain it
while stripping binaries.
sentry-cli uses this identifier to associate symbols
with crash events. If this ID is missing for some reason, invoke
before stripping so that
sentry-cli can compute a stable identifier from the
unstripped file including debug information.
$ sentry-cli upload-dif -t elf . > Found 2 debug information files > Prepared debug information files for upload > Uploaded 2 missing debug information files > File processing complete: OK c0bcc3f1-9827-fe65-3058-404b2831d9e6 (binary; x86_64 executable) OK c0bcc3f1-9827-fe65-3058-404b2831d9e6 (binary.debug; x86_64 debug companion)
There are a few options you can supply for the upload process
Exclude executables and libraries from the upload and search for debug files only. Activate this setting if debug information has been stripped and moved into separate files. This can lead to poor stack traces for release builds.
Exclude files containing only stripped debugging information. Use this option when uploading unstripped binaries to avoid using the wrong files when searching folders and archives.
By default, sentry-cli will open and search ZIP archives for files. Use this switch to disable if your search paths contain large ZIP archives without debug information files to speed up the search.
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.