Skip to content

Crashlytics reference

At a glance

  • Crashlytics.crashlytics(): log(message), set_custom_value(key, value), set_custom_keys(values), set_user_id(id), record_exception(exception), record_exception_model(model), record_error(error, user_info), install_excepthook(*, threads), uninstall_excepthook(), did_crash_during_previous_execution(), collection_enabled, check_for_unsent_reports(cb), check_and_update_unsent_reports(cb), send_unsent_reports(), delete_unsent_reports()
  • ExceptionModel(name, reason, stack_trace), ExceptionModel.from_exception(exception), StackFrame(symbol, file, line), CrashlyticsReport (report_id, date_created, has_crash, log, set_custom_value, set_custom_keys, set_user_id)

pyios_firebase.crashlytics

Firebase Crashlytics: crash reports, and Python exceptions as non-fatal issues.

from pyios_firebase.crashlytics import Crashlytics

crashlytics = Crashlytics.crashlytics()
crashlytics.install_excepthook()      # uncaught Python exceptions are reported
crashlytics.set_user_id(uid)
crashlytics.log("opened the checkout")

try:
    pay()
except PaymentError as e:
    crashlytics.record_exception(e)   # a non-fatal issue, with the Python stack

Native crashes are caught by the SDK itself. A Python exception that nobody catches does not crash the app by itself, so it would never be reported: install_excepthook reports it (with its Python stack frames) before the usual handling runs.

Reports are sent on the next launch. To see readable native stack traces, upload the dSYMs (the Crashlytics run script in Xcode). Crashlytics does not report while a debugger is attached.

Needs the FirebaseCrashlytics framework.

Classes:

Name Description
StackFrame

One frame of an ExceptionModel's stack trace.

ExceptionModel

A non-fatal issue to record: a name, a reason and a stack trace (most

CrashlyticsReport

An unsent report, from check_and_update_unsent_reports. Add logs

Crashlytics

Crashlytics. Get it with Crashlytics.crashlytics().

StackFrame dataclass

StackFrame(symbol: str, file: str, line: int)

One frame of an ExceptionModel's stack trace.

Methods:

Name Description
to_native

A FIRStackFrame.

Attributes:

Name Type Description
symbol str

The function, for example "checkout.pay".

file str

The source file.

line int

The line number.

symbol instance-attribute

symbol: str

The function, for example "checkout.pay".

file instance-attribute

file: str

The source file.

line instance-attribute

line: int

The line number.

to_native

to_native() -> ObjCObject

A FIRStackFrame.

ExceptionModel dataclass

ExceptionModel(
    name: str,
    reason: str,
    stack_trace: list[StackFrame] = list(),
)

A non-fatal issue to record: a name, a reason and a stack trace (most recent call first). record_exception builds one from a Python exception.

Methods:

Name Description
from_exception

An ExceptionModel from a Python exception and its traceback.

to_native

A FIRExceptionModel.

Attributes:

Name Type Description
name str

The issue's title, for example the exception class name.

reason str

The message.

stack_trace list[StackFrame]

The frames, most recent call first.

name instance-attribute

name: str

The issue's title, for example the exception class name.

reason instance-attribute

reason: str

The message.

stack_trace class-attribute instance-attribute

stack_trace: list[StackFrame] = field(default_factory=list)

The frames, most recent call first.

from_exception classmethod

from_exception(exception: BaseException) -> ExceptionModel

An ExceptionModel from a Python exception and its traceback.

Chained exceptions (raise ... from ...) are added to the reason.

Parameters:

Name Type Description Default
exception BaseException

the exception.

required

to_native

to_native() -> ObjCObject

A FIRExceptionModel.

CrashlyticsReport

CrashlyticsReport(native: ObjCObject)

An unsent report, from check_and_update_unsent_reports. Add logs and keys to it before sending.

Parameters:

Name Type Description Default
native ObjCObject

the native FIRCrashlyticsReport.

required

Methods:

Name Description
log

Add a log line to the report.

set_custom_value

Set a key on the report.

set_custom_keys

Set several keys on the report.

set_user_id

Set the user ID on the report.

Attributes:

Name Type Description
native ObjCObject

The FIRCrashlyticsReport.

report_id str

The report's ID.

date_created datetime | None

When the report was made (UTC).

has_crash bool

True if the report has a crash (not only non-fatal issues).

native property

native: ObjCObject

The FIRCrashlyticsReport.

report_id property

report_id: str

The report's ID.

date_created property

date_created: datetime | None

When the report was made (UTC).

has_crash property

has_crash: bool

True if the report has a crash (not only non-fatal issues).

log

log(message: str) -> None

Add a log line to the report.

Parameters:

Name Type Description Default
message str

the text.

required

set_custom_value

set_custom_value(key: str, value: Any) -> None

Set a key on the report.

Parameters:

Name Type Description Default
key str

the key.

required
value Any

a str, number or bool (anything else is shown as its str); None removes it.

required

set_custom_keys

set_custom_keys(values: Mapping[str, Any]) -> None

Set several keys on the report.

Parameters:

Name Type Description Default
values Mapping[str, Any]

keys to values (as for set_custom_value).

required

set_user_id

set_user_id(user_id: str | None) -> None

Set the user ID on the report.

Parameters:

Name Type Description Default
user_id str | None

the ID, or None.

required

Crashlytics

Crashlytics(native: ObjCObject)

Crashlytics. Get it with Crashlytics.crashlytics().

Parameters:

Name Type Description Default
native ObjCObject

the native FIRCrashlytics.

required

Methods:

Name Description
crashlytics

The shared Crashlytics.

log

Add a line to the logs sent with the next crash or non-fatal issue

set_custom_value

Set a key shown with the reports (up to 64 keys).

set_custom_keys

Set several keys at once.

set_user_id

Set the user ID shown with the reports (your own ID; never personal

record_exception

Record a Python exception as a non-fatal issue, with its Python

record_exception_model

Record a non-fatal issue you built yourself (for example an error

record_error

Record an NSError (or a Firebase error from a callback) as a

install_excepthook

Report Python exceptions that nobody catches, as non-fatal issues.

uninstall_excepthook

Undo install_excepthook (if nothing replaced the hooks since).

did_crash_during_previous_execution

True if the app crashed (natively) the last time it ran.

check_for_unsent_reports

Whether there are reports waiting (with collection off). Call this

check_and_update_unsent_reports

The newest unsent report, to add keys and logs before sending (with

send_unsent_reports

Send the waiting reports (with collection off, after the user agreed).

delete_unsent_reports

Delete the waiting reports (with collection off, if the user declined).

Attributes:

Name Type Description
native ObjCObject

The FIRCrashlytics.

collection_enabled bool

Whether reports are sent automatically. Setting it is kept across

native property

native: ObjCObject

The FIRCrashlytics.

collection_enabled property writable

collection_enabled: bool

Whether reports are sent automatically. Setting it is kept across launches. To start with it off (for example until the user agrees), set FirebaseCrashlyticsCollectionEnabled to NO in Info.plist and send with send_unsent_reports.

crashlytics classmethod

crashlytics() -> Crashlytics

The shared Crashlytics.

log

log(message: str) -> None

Add a line to the logs sent with the next crash or non-fatal issue (the last 64 kB are kept).

Parameters:

Name Type Description Default
message str

the text.

required

set_custom_value

set_custom_value(key: str, value: Any) -> None

Set a key shown with the reports (up to 64 keys).

Parameters:

Name Type Description Default
key str

the key.

required
value Any

a str, number or bool (anything else is shown as its str); None removes it.

required

set_custom_keys

set_custom_keys(values: Mapping[str, Any]) -> None

Set several keys at once.

Parameters:

Name Type Description Default
values Mapping[str, Any]

keys to values (as for set_custom_value).

required

set_user_id

set_user_id(user_id: str | None) -> None

Set the user ID shown with the reports (your own ID; never personal data).

Parameters:

Name Type Description Default
user_id str | None

the ID, or None to remove it.

required

record_exception

record_exception(exception: BaseException) -> None

Record a Python exception as a non-fatal issue, with its Python stack frames.

Parameters:

Name Type Description Default
exception BaseException

the exception (usually the one you caught).

required

record_exception_model

record_exception_model(model: ExceptionModel) -> None

Record a non-fatal issue you built yourself (for example an error from another language runtime).

Parameters:

Name Type Description Default
model ExceptionModel

the issue.

required

record_error

record_error(
    error: Any, user_info: Mapping[str, Any] | None = None
) -> None

Record an NSError (or a Firebase error from a callback) as a non-fatal issue. Issues are grouped by domain and code.

Parameters:

Name Type Description Default
error Any

an NSError, or a FirebaseError from a callback.

required
user_info Mapping[str, Any] | None

more information to attach.

None

Raises:

Type Description
TypeError

error is a Python exception (use record_exception) or another type.

install_excepthook

install_excepthook(*, threads: bool = True) -> None

Report Python exceptions that nobody catches, as non-fatal issues.

The previous sys.excepthook (and threading.excepthook) still run after the report. Safe to call more than once.

Parameters:

Name Type Description Default
threads bool

also report exceptions that end a threading.Thread.

True

uninstall_excepthook

uninstall_excepthook() -> None

Undo install_excepthook (if nothing replaced the hooks since).

did_crash_during_previous_execution

did_crash_during_previous_execution() -> bool

True if the app crashed (natively) the last time it ran.

check_for_unsent_reports

check_for_unsent_reports(
    callback: Callable[[bool], None],
) -> None

Whether there are reports waiting (with collection off). Call this or check_and_update_unsent_reports once per launch, then send_unsent_reports or delete_unsent_reports.

Parameters:

Name Type Description Default
callback Callable[[bool], None]

gets True if there are.

required

Raises:

Type Description
RuntimeError

a check was already made in this launch.

check_and_update_unsent_reports

check_and_update_unsent_reports(
    callback: Callable[[CrashlyticsReport | None], None],
) -> None

The newest unsent report, to add keys and logs before sending (with collection off). Once per launch, like check_for_unsent_reports.

Parameters:

Name Type Description Default
callback Callable[[CrashlyticsReport | None], None]

gets a CrashlyticsReport, or None if there is none.

required

Raises:

Type Description
RuntimeError

a check was already made in this launch.

send_unsent_reports

send_unsent_reports() -> None

Send the waiting reports (with collection off, after the user agreed).

delete_unsent_reports

delete_unsent_reports() -> None

Delete the waiting reports (with collection off, if the user declined).