Crashlytics¶
Crashlytics collects crash reports, groups them into issues, and shows which ones hurt the most users. pyios-firebase adds what a Python app needs most: Python exceptions as issues, with their Python stack frames.
from pyios_firebase.crashlytics import Crashlytics
crashlytics = Crashlytics.crashlytics()
crashlytics.install_excepthook() # uncaught Python exceptions become issues
crashlytics.set_user_id(uid)
Installation¶
- Add the
FirebaseCrashlyticsSwift package product (Installation). -
Add the dSYM upload run script, so native stack traces are readable. In Xcode: the target's Build Phases > + > New Run Script Phase:
with the input files
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}and${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}, and Debug Information Format set to DWARF with dSYM File. -
Open Crashlytics in the console.
App configuration¶
What the app's build needs for this product. To combine several products, list
them all in one products; see App configuration.
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]
[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseCrashlytics"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
# optional: keep reports on the device until the user agrees
[tool.kivy.ios.info_plist]
FirebaseCrashlyticsCollectionEnabled = false
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseCrashlytics. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target. - Build Settings > Debug Information Format: DWARF with dSYM File.
- Build Phases > + > New Run Script Phase:
"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run", with the input files${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}and${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}. - Optional, in Info:
FirebaseCrashlyticsCollectionEnabled=NO.
Note
kivyforge already makes Release builds with dSYMs (DEBUG_INFORMATION_FORMAT is dwarf-with-dsym for Release, dwarf for Debug, and kivyforge manages it: do not set it in build_settings). It has no setting for a custom build phase, so upload the dSYMs of a Release archive yourself: <DerivedData>/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/upload-symbols -gsp GoogleService-Info.plist -p ios <the archive's dSYMs folder>.
Python exceptions¶
A Python exception does not crash the app by itself: Kivy or Toga catches it, or it ends a thread. The native SDK never sees it. Report it:
try:
pay(order)
except PaymentError as e:
crashlytics.record_exception(e) # a non-fatal issue
show("Payment failed")
The issue is named after the exception's class (checkout.PaymentError),
with its message, the chained cause (raise ... from ...), and the Python
stack frames (function, file, line), newest first.
Uncaught exceptions¶
crashlytics.install_excepthook() # threads too, by default
crashlytics.install_excepthook(threads=False) # only the main thread
Every uncaught exception (sys.excepthook, and threading.excepthook) is
then recorded, with a log line, before the previous hook runs as usual.
KeyboardInterrupt and SystemExit are not reported. Safe to call more than
once; uninstall_excepthook() undoes it.
Kivy
Kivy catches exceptions in event handlers with its ExceptionManager, so
they never reach sys.excepthook. To report them too:
from kivy.base import ExceptionHandler, ExceptionManager
class ReportToCrashlytics(ExceptionHandler):
def handle_exception(self, exception):
Crashlytics.crashlytics().record_exception(exception)
return ExceptionManager.RAISE # or PASS, to keep the app running
ExceptionManager.add_handler(ReportToCrashlytics())
Other errors¶
crashlytics.record_error(error, {"screen": "checkout"}) # a FirebaseError from a callback, or an NSError
from pyios_firebase.crashlytics import ExceptionModel, StackFrame
crashlytics.record_exception_model( # from another runtime (Lua, JS...)
ExceptionModel("LuaError", "attempt to index a nil value", [StackFrame("update", "game.lua", 42)])
)
NSErrors are grouped by domain and code.
Context for the reports¶
crashlytics.log("Opened checkout") # the last 64 kB are kept
crashlytics.set_custom_value("cart_items", 3)
crashlytics.set_custom_keys({"screen": "checkout", "plan": "pro", "beta": True})
crashlytics.set_user_id(uid) # your ID; never personal data
Custom keys (up to 64) and logs are sent with the next crash or non-fatal
issue. Values are str, numbers or bool; anything else is sent as its
str.
Test it¶
Crashlytics does not report while the debugger is attached:
- Build and run, then stop the app in Xcode.
- Open it from the Home screen (no debugger).
-
Crash it on purpose:
-
Open the app again: the report is sent at launch. It appears in the console within minutes.
did_crash_during_previous_execution() is True at the launch after a crash.
Opt-in reporting¶
To send reports only when the user agrees, start with collection off:
FirebaseCrashlyticsCollectionEnabled = NO in Info.plist. Reports then
wait on the device:
def on_reports(found):
if found and ask_user("Send crash reports?"):
crashlytics.send_unsent_reports()
elif found:
crashlytics.delete_unsent_reports()
crashlytics.check_for_unsent_reports(on_reports) # runs on a background thread
Or get the newest report, to add keys and logs before sending:
def on_report(report):
if report is not None:
print(report.report_id, report.date_created, report.has_crash)
report.set_custom_keys({"consented": True})
crashlytics.send_unsent_reports()
crashlytics.check_and_update_unsent_reports(on_report)
Once per launch
The SDK answers only the first check of a launch; later ones get "no
report" whatever is waiting. pyios-firebase raises RuntimeError on a
second check instead of giving a misleading answer.
crashlytics.collection_enabled = True turns automatic sending on (kept
across launches).
Kivy and Python crashes¶
A crash in native code (an Objective-C exception, a segmentation fault) is a
real crash, reported with native frames. A Python exception that nobody
handles is not a crash: report it with install_excepthook or
record_exception, as above.