Crash Symbols
Turn raw crash addresses back into function names and line numbers. Upload the symbol files your builds produce, per platform and build, and follow each symbolication run in its log.
What crash symbolication is
A crash arrives from a release build, and release builds ship without the names of their functions. The stack trace Countly receives is a list of addresses and offsets, which says nothing about which line of your code failed. Symbolication turns those addresses back into function names, file names, and line numbers, using the symbol files your build produced.
Crash Symbols, under Manage, is where those files live. The Symbols tab holds every symbol file uploaded for the project, labeled by platform and build. The Symbolication logs tab records every run, with its status and the lines the symbolication server wrote while it worked. Symbol files belong to one project, picked in the scope bar.
Symbolication itself starts from a crash, not from here. Once a crash has a matching symbol file, its detail page in Crashes offers to symbolicate it.
How a crash finds its symbol file
A symbol file is matched to a crash by platform and by build, and the match on build works one way for iOS and another way for everything else.
For an iOS crash, the match is on build id: the file whose Build equals one of the ids of the binaries in the crash. For every other platform, the match is on app version: the file whose Build equals the version the crash was reported from. Two platform details matter here. A native C or C++ crash on Android looks for a file filed under Android native, not Android. A JavaScript crash always looks under JavaScript, whatever the browser reported as its platform.
When more than one file fits, the most recently uploaded one is used. When none fits, the crash detail page shows no Symbolicate action at all, so a missing action means a missing or mislabeled file rather than a broken server.
The two families also finish differently. JavaScript symbolication completes while you wait and the stack trace re-renders at once. Native mobile symbolication is queued as a background job, and its progress appears on the Symbolication logs tab.
Use Cases
Upload symbols for a release
A release is going out, and you want its crashes readable from the first report.
- Open Manage > Crash Symbols and check that the scope bar names the right project.
- Choose Add symbol file.
- Pick the Platform. For crashes from native Android code, that is Android native, not Android.
- Enter the Build. For iOS this is the build id of the binary; for everything else it is the app version as your app reports it. One file can cover several builds: separate them with commas.
- Choose the file. Every platform takes one file per entry, except JavaScript, which takes up to 10 files in one upload.
- Add a Note if the file needs one, then Upload.
Symbolicate a crash
A crash group shows raw addresses, and you want the real stack trace.
- Check the Symbols tab for a file whose platform and build match the crash. iOS matches on build id; every other platform matches on app version.
- Open the crash in Crashes. When a matching file exists, the crash detail page offers Symbolicate.
- Run it. A JavaScript crash re-renders symbolicated straight away. A native mobile crash is queued, and a notice tells you symbolication is being processed.
- For a queued run, open the Symbolication logs tab. The run appears as Started, moves to In progress, and ends as Success or Errored.
Find out why a run failed
You symbolicated a crash, nothing changed, and you want to know why.
- Open Symbolication logs. Runs are listed newest first, and the table refreshes on its own every 30 seconds while the tab is open, so there is nothing to reload.
- Filter Status to Errored, or Platform to the one you care about.
- Expand the row. The log content is what the symbolication server wrote during the run, and the reason it stopped is in there.
- To send it on, use the table's download to export the logs. The export carries the log lines, not just the summary columns.
FAQs
Why is there no Symbolicate action on my crash?
No uploaded symbol file matches it. The action appears only when a file exists under the crash's platform whose build fits: the build id for iOS, the app version for everything else.
I uploaded the file and the action still does not appear.
Check the build first. An iOS entry is matched on the crash's build ids; every other platform is matched on the app version the crash reported. Then check the platform: a native Android crash looks under Android native, and a JavaScript crash always looks under JavaScript.
Symbolication said it was being processed, but the crash has not changed.
Native mobile symbolication is queued as a background job. Open the Symbolication logs tab, find the run, and expand it. The table refreshes every 30 seconds, so a run that has just started can take a moment to show.
Can one file cover several builds?
Yes. Separate the builds with commas in the Build field, and the entry matches a crash from any of them.
What is the Note for?
Anything the next person managing these files should know. The search on the Symbols tab looks in it, so a note like the release name makes an entry easy to find later.