From a8ef157d74ded6af93a8cdce894c5c66e42ff34b Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Fri, 26 Jan 2024 09:58:40 -0800 Subject: [PATCH] Update the device.app.lifecycle event description --- .gitignore | 1 + CHANGELOG.md | 4 +++ docs/mobile/events.md | 59 +++++++++++++++++++++-------------- model/logs/mobile-events.yaml | 33 +++++++++++--------- 4 files changed, 59 insertions(+), 38 deletions(-) diff --git a/.gitignore b/.gitignore index c9508b6a86..fdb9989733 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ .project .settings bin +.vs # NetBeans /.nb-gradle diff --git a/CHANGELOG.md b/CHANGELOG.md index 86d2bb5ec2..fc47a5c5b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,10 @@ release. ### Fixes +- Reformat and update the `device.app.lifecycle` event description adds + constraints for the possible values of the `android.state` and `ios.state`. + ([#673](https://github.com/open-telemetry/semantic-conventions/pull/673)) + ## v1.24.0 (2023-12-15) ### Breaking diff --git a/docs/mobile/events.md b/docs/mobile/events.md index 70a5d6fdc3..b537b1f059 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -9,8 +9,8 @@ events on mobile platforms. All mobile events MUST use a namespace of - [Lifecycle instrumentation](#lifecycle-instrumentation) - * [iOS](#ios) - * [Android](#android) + * [Event Name](#event-name) + * [Event Payload (Log Body)](#event-payload-log-body) @@ -21,39 +21,42 @@ application lifecycle. This event is meant to be used in conjunction with `os.name` [resource semantic convention](/docs/resource/os.md) to identify the mobile operating system (e.g. Android, iOS). -### iOS +### Event name - + The event name MUST be `device.app.lifecycle`. -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `active` | Required | - -**[1]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. - -`ios.state` MUST be one of the following: - -| Value | Description | -|---|---| -| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | -| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | -| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | -| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | -| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | -### Android +### Event payload (Log Body) - -The event name MUST be `device.app.lifecycle`. +Payload attributes MUST be used to describe the state of the application at the +time of the event. The following table describes the payload attributes that MUST +be used to describe the state of the application at the time of the event. +The `android.state` and `ios.state` attributes are mutually exclusive and MUST +NOT be used together, each attribute MUST be used with it's corresponding +`os.name` [resource semantic convention](/docs/resource/os.md) value. For +example, if the `os.name` attribute is set to `android` then the +`android.state` attribute MUST be used and the `ios.state` attribute MUST NOT +be used. If the `os.name` attribute is set to `ios` then the `ios.state` +attribute MUST be used and the `android.state` attribute MUST NOT be used. + + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | Required | +| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | See below | +| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [2] | `active` | See below | **[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. +**[2]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* `ios.state` +* `android.state` + `android.state` MUST be one of the following: | Value | Description | @@ -61,6 +64,16 @@ The event name MUST be `device.app.lifecycle`. | `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | | `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. | | `foreground` | Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. | + +`ios.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | +| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | +| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | +| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | +| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/logs/mobile-events.yaml b/model/logs/mobile-events.yaml index d6f49e70c5..9a5cc8c6ab 100644 --- a/model/logs/mobile-events.yaml +++ b/model/logs/mobile-events.yaml @@ -1,13 +1,20 @@ groups: - - id: ios.lifecycle.events + - id: device.app.lifecycle type: event - prefix: ios name: device.app.lifecycle brief: > - This event represents an occurrence of a lifecycle transition on the iOS platform. + This event represents an occurrence of a lifecycle transition on Android or iOS platform. + note: > + This events identifies the fields that are common to all lifecycle events for android and iOS using + the `android.state` and `ios.state` attributes. The `android.state` and `ios.state` attributes are + mutually exclusive. + + - id: device.app.lifecycle.payload + type: attribute_group + brief: > + This defines the content of the Log Body for the device.app.lifecycle event. attributes: - - id: state - requirement_level: "required" + - id: ios.state note: > The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. @@ -37,16 +44,8 @@ groups: - id: terminate value: 'terminate' brief: > - The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. - - id: android.lifecycle.events - type: event - prefix: android - name: device.app.lifecycle - brief: > - This event represents an occurrence of a lifecycle transition on the Android platform. - attributes: - - id: state - requirement_level: required + The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + - id: android.state brief: > This attribute represents the state the application has transitioned into at the occurrence of the event. note: > @@ -70,3 +69,7 @@ groups: brief: > Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. + constraints: + - any_of: + - "ios.state" + - "android.state" \ No newline at end of file