Update the device.app.lifecycle event description

.gitignore

@@ -7,6 +7,7 @@
 .project
 .settings
 bin
+.vs
 
 # NetBeans
 /.nb-gradle

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

docs/mobile/events.md

@@ -9,8 +9,8 @@ events on mobile platforms. All mobile events MUST use a namespace of
 <!-- toc -->
 
 - [Lifecycle instrumentation](#lifecycle-instrumentation)
-  * [iOS](#ios)
-  * [Android](#android)
+  * [Event Name](#event-name)
+  * [Event Payload (Log Body)](#event-payload-log-body)
 
 <!-- tocstop -->
 
@@ -21,46 +21,59 @@ 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
 
-<!-- semconv ios.lifecycle.events -->
+<!-- semconv device.app.lifecycle(full) -->
 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`. |
 <!-- endsemconv -->
 
-### Android
+### Event payload (Log Body)
 
-<!-- semconv android.lifecycle.events -->
-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.
+
+<!-- semconv device.app.lifecycle.payload(full) -->
 | 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 |
 |---|---|
 | `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`. |
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

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"