Facilitate Your iOS Crash Log Translation For Numerous Builds
Symbolication
A process of translating crash stack traces into readable function names and line numbers in source code to understand why an app crashes. (Apple Documentation)
Let’s face it, most of us might have wished the same thing, hoping the app that we create will work smoothly without any issue. But, the hard truth is when developing an app, in this case, iOS applications, we will find crashes, either in the app that has been released to the App Store or in the one that is still in development. And when someone finds it, we will try to reproduce the issue in the Xcode until we find out that silly block of code that causes it. In the worst case, we cannot replicate the crash, resulting in the panic starting to seep in.
Now, you might be wondering, “Why don’t we use third-party tools? Crashlytics is built just for this”. Well, that’s true and not true. We implement Crashlytics for the Tokopedia iOS app released to the App Store. But, we don’t use that for the development environment since we generate lots of builds in a day, and most Crashlytics’ features are unnecessary for the development environment. Therefore, in iOS Tokopedia, we decided to improve our crash debugging process by creating a crash translation service that focuses on the development environment.
Let’s Get Started
When a crash occurs in an iOS app, the operating system will generate a file that contains an encoded crash log. This log is called a .ips file. We can retrieve it from the device where the app is crashed by following these steps. This is an example of what the .ips file looks like.
Yay! Now, we are one step closer to dealing with this crash. But wait, we can’t read these hexadecimal blocks 🤔. We need to translate this file first before we can read it. Translating a .ips file is like opening a treasure chest with two different keys, and we need a particular person to open it. You can refer to this illustration below to have a better visualization.
1. Device Symbol
A device symbol is a set of information used to translate the operating system’s frameworks, such as the UIKitCore and libswiftCore.dylib shown in the previous encoded crash log.
We can collect a device symbol by connecting the device to the Mac. The symbols are specific for each operating system and the CPU architecture of the device. Therefore, if the crash occurs on an iPhone running iOS 15.0, we will need to use a device symbol for iOS 15.0 to translate the encoded log. By the way, let me share a secret here 🤫. To save some space, we just need to keep the device symbol of the latest patch version of that iOS version. For example, iOS 15.0 is released multiple times as iOS 15.0.0, 15.0.1, and 15.0.2. In this case, we just need to store the device symbol from iOS 15.0.2 and we can use it to translate all of the crashes that occur on an iPhone that runs on iOS 15.0.
2. dSYM (Debug Symbol File)
A dSYM file contains a set of symbols needed to translate your application’s framework, such as the TokopediaDebug library shown in the encoded crash log.
These symbols are generated and are downloadable when you upload your app to the App Store Connect or from your application distribution system (CI/CD). In addition, a dSYM file is unique for each build of the app uploaded. Therefore, we need to store the dSYM file from every build for this translation purpose.
3. Symbolicatecrash
Symbolicatecrash is a command that will translate the .ips file by combining it with the suitable dSYM and device symbol. This command can be accessed inside the Xcode through this path.
Xcode.app/Contents/SharedFrameworks/DVTFoundation.framework/Versions/A/Resources/In iOS Tokopedia, we bundle it to a single bash script so that we can execute it as a single command through a terminal. Once we successfully perform this magical process, voila! Now, as shown in the snippet below, we can read the crash log and determine its root cause.
It is important to note that each component needed to translate a .ips file must be suitable. We will get a partially translated crash log instead if any of them is incorrect. For example, if we provide a wrong device symbol, it will result in untranslated operating system frameworks, like the snippet here.
The same thing will happen if the dSYM file is incorrect, in which the app frameworks will not translate, like this one.
And in the worst possible scenario, the .ips file is not translated at all.
Where To Go From Here
Now, we know how to translate a .ips file into a readable crash log, which will help us in our debugging process. But, can we go even further? The answer is definitely yes! In iOS Tokopedia, we decided to build this flow as a service to hasten our debugging process, especially in the development environment. Then, we connect it to our app distribution system so that whenever a new development build is created, its dSYM file will automatically be uploaded.
This service allows people to upload their encoded crash logs, and they will receive the readable stack trace as a result. Therefore, if someone finds a crash on a particular development build, they only need to upload the .ips file and share the translated one with the developers directly, without manually obtaining and uploading the dSYM file for each build. As a result, developers can focus more on fixing the root cause instead of replicating the crash.
In iOS Tokopedia, we call this the Symboligator service. Why Symboligator, you said? Well, that’s something we cannot share 😉 (psst, trust me, it is irrelevant). You can have a deeper look at that service through this link.
Let’s Wrap It Up
Crashes during app development are something that we can’t avoid, but we can certainly try to minimize them by finding and understanding the root cause. Having clear information on how the crash occurs will save us more time on the debugging process, and we can focus more on fixing the issue. By utilizing the tools at hand, we might be able to create a crash log translation service that fits our needs.
Credits
Last but not least, a big shout-out to these peeps, Edho Prasetyo and Gavrila Tiominar Sianturi, that have been relentlessly working together on this service. Also, special thanks to Digital Khrisna and Ambar Dwi Septian for the constant guidance and feedback throughout the whole process 🍻.
As always, we have an opening at Tokopedia.
We are an Indonesian technology company with a mission to democratize commerce through technology and help everyone achieve more.
Find your Dream Job with us in Tokopedia!
https://www.tokopedia.com/careers/
