Common Terms
1 Exceptions
An exception is a crash, ANR, or error that happens when an app is running.
2 Crash
A crash is when an app stops functioning properly and exits during use.
3 ANR
An ANR is an "Application Not Responding" prompt when the app is in use. It's on Android only.
4 Errors
An error is an actively reported exception, error or script (C#, Lua, JS, etc.) error.
5 Occurrence Count
An exception occurred and was recorded and reported is counted as one occurrence.
6 Unique Device Identifier (Device ID)
The marker used to uniquely identify a device is generated by the SDK by default and remains unchanged and effective until the application is uninstalled.
CrashSight uses Device ID to identify devices, i.e., if there are X event reports with the same Device ID, then those X reports will result in +X number of event occurrences, but +1 number of devices affected. Access and event reports come with Device ID information. The following is the default way of generating Device ID in CrashSight SDK on some popular platforms.
| platform | default way of generating Device ID |
|---|---|
| Android | Generate UUID on first boot |
| iOS | IDFV |
| Windows | MAC address |
7 Event Report
When the CrashSight SDK's Event Report mechanism is triggered (such as a crash is automatically caught, see CrashSight Product Introduction for more details), CrashSight will automatically collect the information and report it.
8 Access
When the CrashSight SDK is initialized, a starting event report will be performed immediately and it is called access. The data generated by the access can be used to count the number of starts.
9 Online Device
Each device that has network connection or has been reported once is considered a online device. In a certain time range, a device that repeats network behavior is only considered one online device. (The device is deduplicated according to the unique device identifier)
10 Affected Device
A device that has had an exception is counted as an affected device. In a certain time range, a device that has had multiple exceptions is only counted as one affected device. (The device is deduplicated according to the unique device identifier)
11 Device Exception Rate
The ratio between the number of affected devices and online devices.
12 Exception Count Rates
The ratio of the number of occurrences to the number of network connections. (Applicable to some personalized projects, the others are not considered)
13 Launch Count
Each time the application is restarted after fully exiting is counted as one launch. (The SDK determines the total launch count specifically by launch report + exception report carrying the launch count to be cumulative)
14 Today's Device Exception Rate
The ratio of the number of exception-influenced devices to the number of online devices within the current day.
15 First Report Time
The time at which the issue was first reported to CrashSight.
16 Cumulative Affected Devices
The total number of affected devices from the time the issue was first reported to the system until the current time.
17 Cumulative Occurrences
The total number of occurrences from the time the Issue was first reported to the system until the current time.
18 Hour/Cumulative
The hourly window ranges from the current hour's 00:00 to 59:59. The cumulative window ranges from 00:00:00 to 23:59:59 of the current day.
19 Real Device/Emulator
Real Device: A real mobile physical device. Emulator: A emulator that can run on a personal computer and simulate the Android mobile system. (Most emulators will generate a new unique device identifier each time the app is launched, and cloud gaming devices also have this characteristic and will be marked as emulators).
20 Data Update Time
The update time of backend refresh statistical result data (The data update is an asynchronous backend update, the crash trend is updated about every 10 minutes by default).
21 Issue ID
After an exception is reported, it will be classified (the same exceptions are classified into one set, known as one Issue), the unique UUID of the corresponding issue is called the issue ID, which corresponds one-to-one with the Issue.
22 Report ID
A unique uuid generated when an exception is reported, called the report ID, which corresponds one-to-one with this report.
23 Access address when crashed
The address actually accessed by the program when an invalid memory access occurs. CrashSight can report the address accessed by the program when it crashes. Generally, the invalid memory is 0x0 when cuased by access to a null pointer, and is a large address when cuased by access to a wild pointer.
24 Client report ID
CrashSight SDK will generate a random UUID when handling a crash/error and report it together with the crash/error. This UUID is called the client report ID. The client report ID is the unique identifier of each report and can be used to search and locate the reported information. Developers can search for "expuid" in the client's logs to find the client report ID. Also, developers can search for the crash/error with the client report ID in "Advanced Search" page.
25 Secondary reporting
When a crash occurs, CrashSight will try to immediately report crash information to the server. However, due to various force majeure factors (such as user forced killing program, network errors, etc.), the processing and reporting of crash information may not be completed immediately. At the next startup, CrashSight will check whether there is any unreported crash records, and if so, it will attemp to upload the crash records. This process is called secondary reporting. It is worth noting that the crash information reported again may sometimes be missing, because the last crash information may not be completly processed.
26 Symbol Table
CrashSight needs symbol table to symbolicate the stack. To upload the symbol table, please refer to Symbol Table Tool Usage Introduction.
In order to ensure data security, CrashSight will not ask you to upload the original symbol table file (so, dsym, pdb, etc.) directly, but use our symbol table tool to extract a stif file and then upload it.
Each symbol table has a unique UUID, if the uploaded symbol table UUID is the same as the previous one, CrashSight considers this symbol table to be a duplicate and will use the new symbol table to replace the old one (in other words, if you uploaded the wrong symbol table, you can use this mechanism to fix the error). When symbolicate the stack, CrashSight will prioritize matching the symbol table using the UUID, and if the match fails, it will use the version number + the library name to find the symbol table.
When uploading Android symbol table, please make sure your so file comes with debugging information. You can simply judge by the size of the stif file, if the generated stif file is very small (<=1kb), you may have used an so without debugging information to generate the symbol table. Such a symbol table will not be able to symbolicate the stack successfully. For the method to get the so with debug information, please refer to Symbol table file format for each platform, and the generating method in unity and unreal engine.
27 Search Dimension
A rich set of issue filters is available on the CrashSight page, and the following are implications for the optional search dimensions.
| search dimension | explanation | search dimension | explanation |
|---|---|---|---|
| Issue Last Report Time | The time when the issue was last reported | Issue First Report Time | Time when the issue was first reported |
| Issue First Report Version | The version number when the issue was first reported | Issue Category | CrashSight’s classification of exception reports, such as Native crashes, C# errors, etc. |
| Exception Category | Crash, ANR or Error | Issue Tag | Custom tags that can be set on the Issue List page |
| Issue Status | The status of issue, which can be configured on the "Issue List" page | Bug Form Linked? | Whether the issue is linked to a bug form on TAPD or Jira, which can be configured on the "Issue List" page |
| Issue Assignee | Issue assignee, which can be configured on the "Issue List" page | Version | The version number extracted by CrashSight SDK, which can be set through the interface |
| Upload Time | Issue upload time | Occur Time | Issue occur time |
| App Package Name/Bundle ID | Android package name, or iOS Bundle ID | Distribution Channel | Application distribution channels can be set through the interface |
| Issue ID | The issue ID is displayed in the issue list. Reports of one issue have the same issue ID. | Crash ID | Crash ID generated by the server. Each report has a unique crash ID. |
| Client Report ID | The report ID generated by the client when reporting. It can be viewed by searching for "expuid" in the log or in the report details. | User ID | Used to identify the user, which can be set through the interface. The default is "unknown" |
| Device ID | Used to identify the device, see Device ID for details | Error Name | Error Name |
| Error Message | Error Message | Original Device Model | The model extracted from the system API |
| App Bits | 32-bit or 64-bit | OS Version | OS Version |
| Error Process | Error Process Name | Error Thread | Error Thread Name |
| App Run Time | Length of app running time | Is Simulator | Whether the issue happens on simulator |
| Is System Exit | Whether CrashSight backend matches to system exit features | ROM | System ROM name (Android only) |
| Custom Key | User-defined keywords, see Customized Data for details | Error Stack | The stack of the error thread |
| Error Stack(Before Retrace) | Original stack before symbolicate |
28 System Exit Keywords
In some cases, the app will crash on exit, which is imperceptible to the user, so developers does not prioritize attention to such crashes.
CrashSight determines these types of crashes by identifying system exit keywords; they are not counted in the overview and are listed separately in the TOP issue rankings.
CrashSight recognizes crashes in the stack that match the following keywords as system exits:
| Android system exit keywords | Note |
|---|---|
| CleanupEngine | Exit function in Unity engine |
| Runtime.getRuntime().exit | Java system library function |
| System.exit | Java system library function |
| UnityCleanup | Exit function in Unity engine |
| iOS system exit keywords | Note |
|---|---|
| applicationWillTerminate | Exiting for user kill process manually |
| CleanupEngine | Exit function in Unity engine |
| FEngineLoop::Exit | Exit function in Unreal engine |
| StaticExit | Exit function in Unreal engine |
| terminateWithSuccess | Non-public API in iOS system library |
| The application did not terminate cleanly but no crash occured | CrashSight SDK detects App Unknown Exit |
| UIAlertManager hideAlertsForTermination | Non-public API in iOS system library, not used after iOS 11 |
| UIApplication _handleApplicationDeactivationWithScene:shouldForceExit:transitionContext:completion | Non-public API in iOS system library, not used after iOS 11 |
| UIApplication _handleApplicationDectivationWithScene:shouldForceExit:transitionContext:completion | Non-public API in iOS system library, not used after iOS 11 |
| UIApplication _terminateWithStatus | Non-public API in iOS system library |
| UnityAppController applicationWillTerminate | Exit function in Unity engine |
| UnityCleanup | Exit function in Unity engine |
| _exitapp (exitgame.mm | Non-system library exit function |
| _exitApp (exitGame.mm | Non-system library exit function |
| __cxa_finalize_ranges | API in the iOS system library, see source code. |
29 Stack Backtracing
Stack backtracing is a technique for describing the sequence of function calls during program execution. When a program runs, function calls will form a sequence of frames on a stack in memory. Each frame contains contextual information about a particular function call, such as local variables, parameters, and return addresses. Stack back provides a way to view these frames during program execution to understand the history and sequence of function calls.
CrashSight performs stack backtracing on different platforms via either libunwind or minidump, and the principles of the two backtracing methods are described below.
29.1 libunwind backtracing
The libunwind backtrace is performed in the crash handler function. When a crash occurs, it needs to be executed immediately in the current process of the current device. libunwind backtracing is handled as follows:
- Based on the value of the pc or lr register, access the stack memory and traverse each frame in turn, with each frame corresponding to a line of the stack.
This step allows you to get the execution address of each stack line. - Find the corresponding load segment according to the address.
This step gets the name of the loaded library and the path to the library file. - Read the local library file.
This step gets the UUID and architecture of the library file, and the function name if the library contains symbols. - String together the execution address, library file path, UUID, architecture and function name (if any).
CrashSight Android SDK uses libunwind for backtracing by default. iOS SDK also implements a set of backtracing mechanism with almost the same principle.
29.2 minidump backtracing
minidump backtracing relies on the dump file generated by minidump. When a crash occurs, the exception handler needs to write the stack memory information to the dump file immediately; with the dump file, the backtracing process can be executed at any time and on any device. minidump backtracing process is as follows:
When the crash occurs on the client:
- create the dump file, which contains the stack memory information, memory map information and register information when the crash occurs.
After the crash information is uploaded, on the server:
- read the stack memory information in the dump file and traverse the stack frames in order according to the CFI, with each frame corresponding to one row of the stack.
This step allows you to get the execution address of each stack row. - Find the load segment according to the address and retrieve the corresponding memory mapping information.
This step retrieves the name, UUID, and architecture of the loaded library. - splice the execution address, library name, UUID and architecture into a string.
CrashSight Windows SDK uses minidump to report crash information by default, Android SDK also supports generating minidump (this feature needs to be enabled manually).
29.3 Comparison of the two backtrace methods
Some of the major differences between the two backtrace methods are summarized in the following table:
| difference item | libunwind | minidump |
|---|---|---|
| System library information | Since you can directly access the local library files, you can get the path, architecture, and buildID of the system libraries, which is the same as other libraries. | Only the address and library name can be retrieved. |
| Non-crash thread stack | Only trace back to the stack of the crashed thread. | The stack scan dumps all the information of the thread stack, so it can trace back to the stack of other non-crash threads. |
| The ability to backtrace on stack exceptions | Each stack frame backtracing depends on the previous frame, so backtracing to the abnormal stack frame will be interrupted. | The dump file has complete stack memory information, even if there is an exception in the stack, you can get the information of subsequent stack frames |