Definition for a basic end-user app crash event

.chloggen/basic-crash-event.yaml

@@ -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: app
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Defines a basic crash of an end-user facing app that requires a minimal amount of information.
+
+# 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: [3448]
+
+# (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:

docs/app/app-events.md

@@ -14,6 +14,8 @@ This document defines events related to client-side applications
 - [Click Events](#click-events)
   - [Event: `app.screen.click`](#event-appscreenclick)
   - [Event: `app.widget.click`](#event-appwidgetclick)
+- [Crash Event](#crash-event)
+  - [Event: `app.crash`](#event-appcrash)
 - [Jank Event](#jank-event)
   - [Event: `app.jank`](#event-appjank)
 - [Attributes](#attributes)
@@ -92,6 +94,72 @@ Use this event to indicate that visual application component has been clicked, t
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
+## Crash Event
+
+### Event: `app.crash`
+
+<!-- semconv event.app.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 `app.crash`.
+
+This event represents a termination of a user-facing application due to
+unrecoverable programming errors such as exceptions or signals that
+indicate an error has happened at a lower level.
+
+This event identifies the crash of an end-user facing app, a specific type
+of unexpected app termination defined in the `brief` section. It is intended
+to provide a basic schema that can be used for all crashes, but it existence
+does not preclude other, more narrow events to be defined with more extensive
+schemas to handle specific crash scenarios on specific platforms.
+Crash events can be produced asynchronously by another SDK instance, so it
+can contain attributes that are normally provided by the SDK Resource. The
+appearance of any of those attributes (e.g. app.build_id) means they should
+be used instead of the ones provided in the Resource.
+How the instrumentation will determine whether an instance of a crash has
+already been reported and how the necessary data will be retrieved is left up
+to the instrumentation. Providing enough data to dedupe is NOT REQUIRED.
+If `exception` attributes are used, it indicates that the exception represented
+by those attributes caused the crash. When used, these attributes SHOULD be
+usable for debugging without additional data not specified in the event
+(e.g. stacktrace already deobfuscated). If that is not the case, additional
+information like `app.build_id` SHOULD be provided to make the data useful for
+debugging, either derived from the Resource or as attributes in this event if
+they differ from what is defined there (in the asynchronous case).
+
+**Attributes:**
+
+| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- | --- |
+| [`session.id`](/docs/registry/attributes/session.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` |
+| [`app.build_id`](/docs/registry/attributes/app.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | Unique identifier for a particular build or compilation of the application. | `6cff0a7e-cefc-4668-96f5-1273d8b334d0`; `9f2b833506aa6973a92fde9733e6271f`; `my-app-1.0.0-code-123` |
+| [`app.crash.id`](/docs/registry/attributes/app.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | A unique identifier representing an instance of an end-user facing app crash. [1] | `083d3d2d-9a0e-47f8-be3d-bc3c5538ba38` |
+| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | The exception message. [2] | `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) | `Opt-In` | 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. | `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) | `Opt-In` | 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. | `java.net.ConnectException`; `OSError` |
+| [`os.name`](/docs/registry/attributes/os.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` |
+| [`os.version`](/docs/registry/attributes/os.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` |
+| [`service.version`](/docs/registry/attributes/service.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | The version string of the service component. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` |
+
+**[1] `app.crash.id`:** Its value COULD be meaningful and be used as a reference for other telemetry and metadata recorded by
+the same instrumentation (e.g. it is an ID generated by an external source that captured the crash).
+It COULD come from a source external to the instrumentation such that it can be used to look up additional
+data from other sources as well as facilitate deduplication.
+
+**[2] `exception.message`:**
+
+> [!WARNING]
+>
+> This attribute may contain sensitive information.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
 ## Jank Event
 
 ### Event: `app.jank`

docs/registry/attributes/app.md

@@ -12,18 +12,24 @@ Describes attributes related to client-side applications (e.g. web apps or mobil
 | Key | Stability | Value Type | Description | Example Values |
 | --- | --- | --- | --- | --- |
 | <a id="app-build-id" href="#app-build-id">`app.build_id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Unique identifier for a particular build or compilation of the application. | `6cff0a7e-cefc-4668-96f5-1273d8b334d0`; `9f2b833506aa6973a92fde9733e6271f`; `my-app-1.0.0-code-123` |
-| <a id="app-installation-id" href="#app-installation-id">`app.installation.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` |
-| <a id="app-jank-frame-count" href="#app-jank-frame-count">`app.jank.frame_count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | A number of frame renders that experienced jank. [2] | `9`; `42` |
+| <a id="app-crash-id" href="#app-crash-id">`app.crash.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | A unique identifier representing an instance of an end-user facing app crash. [1] | `083d3d2d-9a0e-47f8-be3d-bc3c5538ba38` |
+| <a id="app-installation-id" href="#app-installation-id">`app.installation.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | A unique identifier representing the installation of an application on a specific device [2] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` |
+| <a id="app-jank-frame-count" href="#app-jank-frame-count">`app.jank.frame_count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | A number of frame renders that experienced jank. [3] | `9`; `42` |
 | <a id="app-jank-period" href="#app-jank-period">`app.jank.period`</a> | ![Development](https://img.shields.io/badge/-development-blue) | double | The time period, in seconds, for which this jank is being reported. | `1.0`; `5.0`; `10.24` |
 | <a id="app-jank-threshold" href="#app-jank-threshold">`app.jank.threshold`</a> | ![Development](https://img.shields.io/badge/-development-blue) | double | The minimum rendering threshold for this jank, in seconds. | `0.016`; `0.7`; `1.024` |
 | <a id="app-screen-coordinate-x" href="#app-screen-coordinate-x">`app.screen.coordinate.x`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The x (horizontal) coordinate of a screen coordinate, in screen pixels. | `0`; `131` |
 | <a id="app-screen-coordinate-y" href="#app-screen-coordinate-y">`app.screen.coordinate.y`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The y (vertical) component of a screen coordinate, in screen pixels. | `12`; `99` |
-| <a id="app-screen-id" href="#app-screen-id">`app.screen.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | An identifier that uniquely differentiates this screen from other screens in the same application. [3] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `com.example.app.MainActivity`; `com.example.shop.ProductDetailFragment`; `MyApp.ProfileView`; `MyApp.ProfileViewController` |
-| <a id="app-screen-name" href="#app-screen-name">`app.screen.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of an application screen. [4] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` |
-| <a id="app-widget-id" href="#app-widget-id">`app.widget.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | An identifier that uniquely differentiates this widget from other widgets in the same application. [5] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `submit_order_1829` |
-| <a id="app-widget-name" href="#app-widget-name">`app.widget.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of an application widget. [6] | `submit`; `attack`; `Clear Cart` |
+| <a id="app-screen-id" href="#app-screen-id">`app.screen.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | An identifier that uniquely differentiates this screen from other screens in the same application. [4] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `com.example.app.MainActivity`; `com.example.shop.ProductDetailFragment`; `MyApp.ProfileView`; `MyApp.ProfileViewController` |
+| <a id="app-screen-name" href="#app-screen-name">`app.screen.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of an application screen. [5] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` |
+| <a id="app-widget-id" href="#app-widget-id">`app.widget.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | An identifier that uniquely differentiates this widget from other widgets in the same application. [6] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `submit_order_1829` |
+| <a id="app-widget-name" href="#app-widget-name">`app.widget.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of an application widget. [7] | `submit`; `attack`; `Clear Cart` |
 
-**[1] `app.installation.id`:** Its value SHOULD persist across launches of the same application installation, including through application upgrades.
+**[1] `app.crash.id`:** Its value COULD be meaningful and be used as a reference for other telemetry and metadata recorded by
+the same instrumentation (e.g. it is an ID generated by an external source that captured the crash).
+It COULD come from a source external to the instrumentation such that it can be used to look up additional
+data from other sources as well as facilitate deduplication.
+
+**[2] `app.installation.id`:** Its value SHOULD persist across launches of the same application installation, including through application upgrades.
 It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled.
 Additionally, users might be able to reset this value (e.g. by clearing application data).
 If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value.
@@ -41,12 +47,12 @@ For Android, examples of `app.installation.id` implementations include:
 
 More information about Android identifier best practices can be found in the [Android user data IDs guide](https://developer.android.com/training/articles/user-data-ids).
 
-**[2] `app.jank.frame_count`:** Depending on platform limitations, the value provided MAY be approximation.
+**[3] `app.jank.frame_count`:** Depending on platform limitations, the value provided MAY be approximation.
 
-**[3] `app.screen.id`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
+**[4] `app.screen.id`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
 
-**[4] `app.screen.name`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
+**[5] `app.screen.name`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
 
-**[5] `app.widget.id`:** A widget is an application component, typically an on-screen visual GUI element.
+**[6] `app.widget.id`:** A widget is an application component, typically an on-screen visual GUI element.
 
-**[6] `app.widget.name`:** A widget is an application component, typically an on-screen visual GUI element.
+**[7] `app.widget.name`:** A widget is an application component, typically an on-screen visual GUI element.

model/app/events.yaml

@@ -1,4 +1,51 @@
 groups:
+  - id: event.app.crash
+    stability: development
+    type: event
+    name: app.crash
+    brief: |
+      This event represents a termination of a user-facing application due to
+      unrecoverable programming errors such as exceptions or signals that
+      indicate an error has happened at a lower level.
+    note: |
+      This event identifies the crash of an end-user facing app, a specific type
+      of unexpected app termination defined in the `brief` section. It is intended
+      to provide a basic schema that can be used for all crashes, but it existence
+      does not preclude other, more narrow events to be defined with more extensive
+      schemas to handle specific crash scenarios on specific platforms.
+      Crash events can be produced asynchronously by another SDK instance, so it
+      can contain attributes that are normally provided by the SDK Resource. The
+      appearance of any of those attributes (e.g. app.build_id) means they should
+      be used instead of the ones provided in the Resource.
+      How the instrumentation will determine whether an instance of a crash has
+      already been reported and how the necessary data will be retrieved is left up
+      to the instrumentation. Providing enough data to dedupe is NOT REQUIRED.
+      If `exception` attributes are used, it indicates that the exception represented
+      by those attributes caused the crash. When used, these attributes SHOULD be
+      usable for debugging without additional data not specified in the event
+      (e.g. stacktrace already deobfuscated). If that is not the case, additional
+      information like `app.build_id` SHOULD be provided to make the data useful for
+      debugging, either derived from the Resource or as attributes in this event if
+      they differ from what is defined there (in the asynchronous case).
+    attributes:
+      - ref: app.build_id
+        requirement_level: opt_in
+      - ref: app.crash.id
+        requirement_level: opt_in
+      - ref: exception.type
+        requirement_level: opt_in
+      - ref: exception.message
+        requirement_level: opt_in
+      - ref: exception.stacktrace
+        requirement_level: opt_in
+      - ref: os.name
+        requirement_level: opt_in
+      - ref: os.version
+        requirement_level: opt_in
+      - ref: service.version
+        requirement_level: opt_in
+      - ref: session.id
+        requirement_level: recommended
   - id: event.app.screen.click
     stability: development
     type: event

model/app/registry.yaml

@@ -6,6 +6,18 @@ groups:
       Describes attributes related to client-side applications (e.g. web apps or mobile apps).
     stability: development
     attributes:
+      - id: app.crash.id
+        type: string
+        stability: development
+        brief: >
+          A unique identifier representing an instance of an end-user facing app crash.
+        note: |
+          Its value COULD be meaningful and be used as a reference for other telemetry and metadata recorded by
+          the same instrumentation (e.g. it is an ID generated by an external source that captured the crash).
+          It COULD come from a source external to the instrumentation such that it can be used to look up additional
+          data from other sources as well as facilitate deduplication.
+        examples:
+          - 083d3d2d-9a0e-47f8-be3d-bc3c5538ba38
       - id: app.installation.id
         type: string
         stability: development