iOS Error Reporting#
Overview#
This document introduces the Flashcat iOS RUM SDK's error capture mechanism, including application crashes, App Hangs, Watchdog terminations, manual error reporting, and dSYM symbol file uploads.Error Types#
Flashcat iOS RUM can monitor the following types of errors:Application Crashes#
The SDK automatically captures unhandled exceptions and fatal signals, including:Uncaught Swift/Objective-C exceptions
Fatal signals (such as SIGSEGV, SIGABRT)
App Hangs#
When the main thread is blocked beyond a specified threshold, the SDK detects and reports App Hang events, helping you identify performance issues affecting user experience.Watchdog Terminations#
iOS's Watchdog mechanism terminates applications that are unresponsive for extended periods. The SDK can detect these terminations and report them as crash events.Custom Errors#
In addition to automatically captured errors, you can manually report custom errors using the RUM SDK to track specific issues such as business logic errors.Add Crash Reporting Module#
To enable crash reporting, you need to add the FlashcatCrashReporting module.Swift Package Manager#
When adding package dependencies in Xcode, include the following modules:FlashcatRUM: RUM functionality module
FlashcatCrashReporting: Crash reporting module
Initialize Crash Reporting#
Enable crash reporting after SDK initialization:It's recommended to initialize the SDK and crash reporting as early as possible in application(_:didFinishLaunchingWithOptions:) to ensure crashes during app launch are captured.
Enable App Hang Tracking#
Set the appHangThreshold parameter in the RUM configuration:App Hang Threshold Description#
| Threshold | Description |
|---|
0.25 | 250 milliseconds, detect minor freezes |
1.0 | 1 second, detect noticeable freezes |
nil | Disable App Hang detection (default) |
Setting too low a threshold may generate excessive reports; adjust based on your application's actual requirements.
If an App Hang causes the application to be terminated by Watchdog, the event will be marked as a crash.
Enable Watchdog Termination Tracking#
Watchdog Termination Detection Conditions#
The SDK will classify the previous app termination as a Watchdog termination when all the following conditions are met:The app was not force-quit by the user
No crash or fatal error occurred during the previous run
The app was in the foreground and responding to events
Manual Error Reporting#
Through the addError API, you can manually report handled exceptions, custom errors, or other errors not automatically captured.Example: Reporting Errors#
Error Source Types#
| Source | Description |
|---|
.source | Source error |
.network | Network error |
.webview | WebView error |
.console | Console error |
.custom | Custom error |
Example: Reporting Error Objects#
Get Symbolicated Stack Traces#
Crash report stacks are memory addresses by default. By uploading dSYM symbol files, these addresses can be converted to readable function names, file names, and line numbers.What is a dSYM File#
dSYM (Debug Symbol) files contain the application's debug symbol information, used to map memory addresses in crash stacks to source code locations.Step 2: Upload dSYM Files#
.zip archives containing multiple dSYMs
Integrate dSYM Upload in CI/CD#
Xcode Build Phase Script#
Add a Run Script in your Xcode project's Build Phases:Fastlane Integration#
Add an upload step in your Fastfile:dSYM for Bitcode Applications#
If your application has Bitcode enabled, Apple will recompile the app during App Store processing, generating new dSYM files. You need to download these dSYMs from App Store Connect and upload them.Download Bitcode dSYM#
2.
Navigate to your app > Activity > Select a build version
dSYM File Limitations#
Each dSYM file size is limited to 2 GB
Only crashes from real devices support symbolication; crashes from simulators are not supported
Track Background Events#
By default, only crashes that occur while a view is active are tracked. If you want to track crashes when the app is in the background, enable background event tracking:Tracking background events may generate additional sessions, which could affect billing. If you have questions, please contact the Flashcat support team.
Limitations and Considerations#
Crash Detection Limitations#
SDK initialization timing: Crashes can only be detected after the SDK and CrashReporting.enable() are called. Initialize as early as possible.
Debugger interference: When the Xcode debugger is attached, crashes are captured by the debugger instead of the SDK. Test crash reporting without the debugger attached.
Crash report upload timing: Crash reports are uploaded on the next app launch, so you need to restart the app after a crash to see the report.
Symbolication Limitations#
Only crashes from real devices support symbolication; simulator crashes are not supported.
Each release version requires uploading the corresponding dSYM files.
If using Bitcode, download and upload regenerated dSYMs from App Store Connect.
App Hang Detection Limitations#
App Hang detection only works when the app is in the foreground.
Detection accuracy depends on the threshold setting; too low a threshold may produce many false positives.
Test Verification#
Verify Crash Reporting#
1.
Run the app without the debugger attached: Stop the app from Xcode, then launch directly from the device.
3.
Restart the app: After the crash occurs, restart the app from the device and wait for the SDK to upload the crash report.
4.
View the report: Check the crash report in the Flashcat console's Error Tracking module.
Verify App Hang#
1.
Execute a time-consuming operation on the main thread:
2.
After triggering, try to interact with the app.
3.
Check if the Flashcat console received an App Hang report.
Verify Symbolication#
1.
Ensure the corresponding version's dSYM file has been uploaded.
2.
Trigger a crash and view the report.
3.
Confirm the stack shows function names, file names, and line numbers instead of raw memory addresses.
Error Data Structure#
Each error record contains the following properties:| Property | Type | Description |
|---|
error.source | string | Error source (such as source, network, custom) |
error.type | string | Error type (such as NSException, Signal) |
error.message | string | Error message |
error.stack | string | Error stack trace |
error.is_crash | boolean | Whether it's a crash |
context | Object | Custom context information, passed through addError's attributes |
Best Practices#
1.
Initialize SDK early: Call Flashcat.initialize() and CrashReporting.enable() as early as possible in application(_:didFinishLaunchingWithOptions:).
2.
Upload corresponding dSYM files for each release version
Integrate dSYM upload in your CI/CD pipeline
If using Bitcode, promptly download and upload dSYMs from App Store Connect
3.
Set reasonable App Hang thresholds: Set appropriate thresholds based on your app's performance requirements to avoid excessive false positives.
4.
Enrich error context: Attach business-related context information (such as user ID, operation type) when manually reporting errors.
5.
Disconnect debugger during testing: Ensure the Xcode debugger is not attached when verifying crash reporting functionality.
Next Steps#
微信扫码交流