diff --git a/.chloggen/mobile-crash.yaml b/.chloggen/mobile-crash.yaml new file mode 100644 index 0000000000..f141f2c962 --- /dev/null +++ b/.chloggen/mobile-crash.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: 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: diff --git a/docs/mobile/mobile-events.md b/docs/mobile/mobile-events.md index d5b55babfa..a3addd7499 100644 --- a/docs/mobile/mobile-events.md +++ b/docs/mobile/mobile-events.md @@ -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) @@ -76,4 +78,42 @@ The `android.app.state` and `ios.app.state` fields are mutually exclusive and MU +## Crash instrumentation + +This section defines how to apply semantic conventions when instrumenting +application crashes on mobile platforms. + +### Event: `device.crash` + + + + + + +**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. + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/device/events.yaml b/model/device/events.yaml index 0cf59e7042..4ae5c2b400 100644 --- a/model/device/events.yaml +++ b/model/device/events.yaml @@ -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.