Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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/basic-crash-event.yaml
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: 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:
68 changes: 68 additions & 0 deletions docs/app/app-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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`
Expand Down
30 changes: 18 additions & 12 deletions docs/registry/attributes/app.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
47 changes: 47 additions & 0 deletions model/app/events.yaml
Original file line number Diff line number Diff line change
@@ -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
Comment on lines +45 to +46
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Should this also be removed given we removed service.name via ff0fe1c & we already have app.build_id?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Build IDs aren't often used to track different version. There's also no sem-ver so you can only tell if one is different than the other, whereas version gives you a lot richer information. This is almost always preferred when folks are tagging telemetry from mobile apps as a point of code differentiation.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Yes but that meaning/understanding is only possible when you know what it corresponds to. In the case here we already removed service.name hence we don't know what it is for.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The removal of service.name was because it was relatively low value and there's an unrelated issue that prevented the MD from being generated property (it contains text with a broken reference link when ported to this event). But the idea that there could be a different service.version still exists even if we don't explicitly say it was from an async recording of the event. In fact, it is still an important attribute - to know a crash came in a version that is different than the one producing the event.

- ref: session.id
requirement_level: recommended
- id: event.app.screen.click
stability: development
type: event
Expand Down
12 changes: 12 additions & 0 deletions model/app/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading