Skip to content

Mobile crash event #3441

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
LikeTheSalad wants to merge 3 commits into from
Closed

Mobile crash event #3441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a4f59e4
Adding device.crash event
LikeTheSalad Feb 16, 2026
ee88769
Adding changelog entry
LikeTheSalad Feb 16, 2026
1dbc3d9
Updating changelog entry
LikeTheSalad Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/mobile-crash.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: enhancement

# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: device

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add new `device.crash` event for mobile application crashes.

# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [3441]

# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:
40 changes: 40 additions & 0 deletions docs/mobile/mobile-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ events on mobile platforms. All mobile events MUST use a namespace of

- [Lifecycle instrumentation](#lifecycle-instrumentation)
- [Event: `device.app.lifecycle`](#event-deviceapplifecycle)
- [Crash instrumentation](#crash-instrumentation)
- [Event: `device.crash`](#event-devicecrash)

<!-- tocstop -->

Expand Down Expand Up @@ -76,4 +78,42 @@ The `android.app.state` and `ios.app.state` fields are mutually exclusive and MU
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Crash instrumentation

This section defines how to apply semantic conventions when instrumenting
application crashes on mobile platforms.

### Event: `device.crash`
Copy link
Copy Markdown
Contributor

@kamphaus kamphaus Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the event called device.crash and not something like mobile.app.crash?
Does device.crash imply a fatal error of the device OS and not of a mobile app?

Copy link
Copy Markdown
Contributor

@thompson-tomo thompson-tomo Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, app.exception would be an even better naming option which would complement #3426 etc

Copy link
Copy Markdown
Contributor Author

@LikeTheSalad LikeTheSalad Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the event called device.crash and not something like mobile.app.crash?
Does device.crash imply a fatal error of the device OS and not of a mobile app?

I agree, app.exception would be an even better naming option which would complement #3426 etc

It's a good point. I believe we've used device.crash in OTel Android for a while due to historic reasons, as in the beginning of events there was an "event.domain" attribute, which we set to "device" back then, whereas the "event.name" was only "crash", but then the domain attribute was removed so we merged the 2 and got to "device.crash". But without that context, it certainly sounds as though we say that the whole device has crashed. Events have changed a lot since, so I'm not opposed to changing it. Now, regarding the proposed names in this thread:

  • mobile.app.crash
  • app.exception

I would like to keep some consistency with existing mobile-related event names, and iiuc none nowadays start with mobile.*. Also, "exception" is a broad term, and a mobile crash is an important event on its own for Android devs, so it should keep reading "crash" in its name.

With that in mind, and after taking a look at existing mobile-related events, I think we have a couple of options:

  • device.app.crash (consistent with the current "device.app.lifecycle" one).
  • app.crash (consistent with multiple "app.*" events, such as "app.screen.click" and "app.jank").

Copy link
Copy Markdown
Contributor

@kamphaus kamphaus Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

device.app.crash sounds good to me.

For app.crash I'm wondering if it is also applicable to other types of applications (eg. web apps).
Would we also define app.exception (eg. for recording non-fatal errors) and would this cause some duplication for fatal errors?

Copy link
Copy Markdown
Contributor Author

@LikeTheSalad LikeTheSalad Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For app.crash I'm wondering if it is also applicable to other types of applications (eg. web apps).

I'm curious about it too. Maybe @martinkuba or @david-luna could help?

Would we also define app.exception (eg. for recording non-fatal errors) and would this cause some duplication for fatal errors?

I'm not sure about it. In my experience so far, non-fatal exceptions have always been part of some bigger task where they were expected, such as an HTTP call that failed, for example, where we set the exception with plain "exception.*" attrs. If no task expects an exception and it reaches the app's exception handler, then we get a crash. Because of it, I cannot see the need to define an event for "standalone-non-fatal" exceptions for mobile apps.

Copy link
Copy Markdown
Contributor

@thompson-tomo thompson-tomo Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I much rather use the app namespace instead of device.

Would we also define app.exception (eg. for recording non-fatal errors) and would this cause some duplication for fatal errors?

We Could use an attribute on app.exception to distinguish between fatal & non-fatal exceptions?

Copy link
Copy Markdown
Contributor Author

@LikeTheSalad LikeTheSalad Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We Could use an attribute on app.exception to distinguish between fatal & non-fatal exceptions?

Could you mention some use cases where a standalone-non-fatal exception event might be needed for mobile apps?

Copy link
Copy Markdown
Contributor

@thompson-tomo thompson-tomo Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An example would be the app passes user input/form data to a third party library which throws a validation exception. Having this as an app.exception allows us to recomend the screen etc which triggered the exception.

Copy link
Copy Markdown
Contributor Author

@LikeTheSalad LikeTheSalad Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the example. I haven't bumped into a similar use case yet, but it's not unlikely, and if there's no other namespace for the third-party library, then it's feasible.

In that case, and given how important it is in Android development to talk about crashes, I'd prefer to have 2 event names, one "[device.]app.crash" and one "[device.]app.exception", which seem descriptive enough to avoid relying on flags to distinguish similar yet dramatically different events in terms of priorities and the visibility they need.

Copy link
Copy Markdown
Contributor Author

@LikeTheSalad LikeTheSalad Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your inputs @kamphaus and @thompson-tomo. @bidetofevil has volunteered to create a broader, more precise definition for app crashes across multiple PRs, starting with this one, which covers the basics already covered here and also defines a better name (app.crash) for it. If you're interested in continuing to follow this event, please take a look at that other PR.


<!-- semconv event.device.crash -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

The event name MUST be `device.crash`.

This event represents a crash of a mobile application.

A crash is defined as an unhandled error or exception that causes the application to terminate unexpectedly. This event SHOULD be recorded when the application detects a fatal condition that will result in the application being terminated.

**Attributes:**

| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The exception message. [1] | `Division by zero`; `Can't convert 'int' object to str implicitly` |
| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. [2] | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. [3] | `java.net.ConnectException`; `OSError` |

**[1] `exception.message`:** The exception message associated with the crash.

**[2] `exception.stacktrace`:** The stacktrace of the exception that caused the crash.

**[3] `exception.type`:** The type of the exception that caused the crash.

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
25 changes: 25 additions & 0 deletions model/device/events.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,28 @@ groups:
- ref: android.app.state
requirement_level:
conditionally_required: if and only if `os.name` is `android`

- id: event.device.crash
stability: development
type: event
name: device.crash
brief: >
This event represents a crash of a mobile application.
note: >
A crash is defined as an unhandled error or exception that causes the
application to terminate unexpectedly. This event SHOULD be recorded
when the application detects a fatal condition that will result in
the application being terminated.
attributes:
- ref: exception.type
requirement_level: recommended
note: >
The type of the exception that caused the crash.
- ref: exception.message
requirement_level: recommended
note: >
The exception message associated with the crash.
- ref: exception.stacktrace
requirement_level: recommended
note: >
The stacktrace of the exception that caused the crash.
Loading