Update the device.app.lifecycle event description and constraints (#794)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>

.chloggen/device_app_lifecycle.yaml

@@ -0,0 +1,26 @@
+# 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: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: device.app.lifecycle
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: >
+  Reformat and update the `device.app.lifecycle` event description adds constraints for the possible values of
+  the `android.state` and `ios.state`.
+
+# 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: [794]
+
+# (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: >
+  Removes the `ios.lifecycle.events` and `android.lifecycle.events` attributes from the global registry and adds
+  constraints for the possible values of the `android.state` and `ios.state` attributes.

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -46,7 +46,6 @@ body:
         - area:heroku
         - area:host
         - area:http
-        - area:ios
         - area:k8s
         - area:log
         - area:messaging

.github/ISSUE_TEMPLATE/change_proposal.yaml

@@ -39,7 +39,6 @@ body:
         - area:heroku
         - area:host
         - area:http
-        - area:ios
         - area:k8s
         - area:log
         - area:messaging

.github/ISSUE_TEMPLATE/new-conventions.yaml

@@ -48,7 +48,6 @@ body:
         - area:heroku
         - area:host
         - area:http
-        - area:ios
         - area:k8s
         - area:log
         - area:messaging

.gitignore

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

.vscode/settings.json

@@ -11,7 +11,7 @@
     },
     "yaml.schemas": {
         "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.24.0/semantic-conventions/semconv.schema.json": [
-            "model/**/*.yaml",
+            "model/**/*.yaml"
         ]
     },
     "json.schemaDownload.enable": true

docs/attributes-registry/android.md

@@ -3,23 +3,24 @@
 <!-- toc -->
 
 - [Android Attributes](#android-attributes)
-- [Android Lifecycle Event Attributes](#android-lifecycle-event-attributes)
+- [Deprecated Android Attributes](#deprecated-android-attributes)
 
 <!-- tocstop -->
 
 ## Android Attributes
+
 <!-- semconv registry.android(omit_requirement_level) -->
 | Attribute  | Type | Description  | Examples  | Stability |
 |---|---|---|---|---|
 | `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 
-## Android Lifecycle Event Attributes
+## Deprecated Android Attributes
 
-<!-- semconv registry.android.lifecycle.events(omit_requirement_level) -->
+<!-- semconv registry.android.deprecated(omit_requirement_level) -->
 | Attribute  | Type | Description  | Examples  | Stability |
 |---|---|---|---|---|
-| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `android.state` | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[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.
 

docs/attributes-registry/ios.md

@@ -5,16 +5,16 @@
 
 <!-- toc -->
 
-- [iOS Lifecycle Event Attributes](#ios-lifecycle-event-attributes)
+- [Deprecated iOS Attributes](#deprecated-ios-attributes)
 
 <!-- tocstop -->
 
-## iOS Lifecycle Event Attributes
+## Deprecated iOS Attributes
 
-<!-- semconv registry.ios.lifecycle.events(omit_requirement_level) -->
+<!-- semconv registry.ios.deprecated(omit_requirement_level) -->
 | Attribute  | Type | Description  | Examples  | Stability |
 |---|---|---|---|---|
-| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `active` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `ios.state` | string | Deprecated use the `device.app.lifecycle` event definition including `ios.state` as a payload field instead. [1] | `active` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Moved to a payload field of `device.app.lifecycle`. |
 
 **[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.
 

docs/mobile/events.md

@@ -9,8 +9,7 @@ events on mobile platforms. All mobile events MUST use a namespace of
 <!-- toc -->
 
 - [Lifecycle instrumentation](#lifecycle-instrumentation)
-  - [iOS](#ios)
+  - [Event details](#event-details)
-  - [Android](#android)
 
 <!-- tocstop -->
 
@@ -21,39 +20,35 @@ 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
+The following table describes the payload fields that MUST
+be used to describe the state of the application at the time of the event.
 
-<!-- semconv ios.lifecycle.events(full) -->
+The `android.state` and `ios.state` fields are mutually exclusive and MUST
+NOT be used together, each field MUST be used with its corresponding
+`os.name` [resource semantic convention](/docs/resource/os.md) value.
+
+### Event details
+
+<!-- semconv device.app.lifecycle(full) -->
 The event name MUST be `device.app.lifecycle`.
 
-| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
-|---|---|---|---|---|---|
-| [`ios.state`](../attributes-registry/ios.md) | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `active` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-
-**[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` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
-
-| Value  | Description | Stability |
-|---|---|---|
-| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 <!-- endsemconv -->
 
-### Android
+<!-- Manually adding the markdown table until the body definition is available in the build tools -->
-
+| Body Field | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
-<!-- semconv android.lifecycle.events(full) -->
-The event name MUST be `device.app.lifecycle`.
-
-| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`android.state`](../attributes-registry/android.md) | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | `Conditionally Required`: if and only if `os.name` is `android` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [2] | `active` | `Conditionally Required`: if and only if `os.name` is `ios` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[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` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |
@@ -61,6 +56,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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-<!-- endsemconv -->
+
+`ios.state` MUST be one of the following:
+
+| Value  | Description | Stability |
+|---|---|---|
+| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- end of manually added table -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

model/logs/mobile-events.yaml

@@ -1,17 +1,76 @@
 groups:
-  - id: ios.lifecycle.events
+  - id: device.app.lifecycle
+    stability: experimental
     type: event
     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.
-    attributes:
+    note: >
-      - ref: ios.state
+      This event identifies the fields that are common to all lifecycle events for android and iOS using
-        requirement_level: "required"
+      the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are
-  - id: android.lifecycle.events
+      mutually exclusive.
-    type: event
+    # Future Note: When the build tools support this definition please uncomment and validate the details
-    name: device.app.lifecycle
+    # included here and what has been added to the manual markdown table
-    brief: >
+    # body:
-      This event represents an occurrence of a lifecycle transition on the Android platform.
+    #   fields:
-    attributes:
+    #     - id: ios.state
-      - ref: android.state
+    #       stability: experimental
-        requirement_level: required
+    #       requirement_level:
+    #         conditional_required: if and only if `os.name` is `ios`
+    #       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.
+    #       brief: >
+    #         This attribute represents the state the application has transitioned into at the occurrence of the event.
+    #       type:
+    #         allow_custom_values: false
+    #         members:
+    #           - id: active
+    #             value: 'active'
+    #             brief: >
+    #               The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.
+    #           - id: inactive
+    #             value: 'inactive'
+    #             brief: >
+    #               The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.
+    #           - id: background
+    #             value: 'background'
+    #             brief: >
+    #               The app is now in the background.
+    #               This value is associated with UIKit notification `applicationDidEnterBackground`.
+    #           - id: foreground
+    #             value: 'foreground'
+    #             brief: >
+    #               The app is now in the foreground.
+    #               This value is associated with UIKit notification `applicationWillEnterForeground`.
+    #           - id: terminate
+    #             value: 'terminate'
+    #             brief: >
+    #               The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.
+    #     - id: android.state
+    #       stability: experimental
+    #       requirement_level:
+    #         conditional_required: if and only if `os.name` is `android`
+    #       brief: >
+    #         This attribute represents the state the application has transitioned into at the occurrence of the event.
+    #       note: >
+    #         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.
+    #       type:
+    #         allow_custom_values: false
+    #         members:
+    #           - id: created
+    #             value: 'created'
+    #             brief: >
+    #               Any time before Activity.onResume() or, if the app has no Activity, Context.startService()
+    #               has been called in the app for the first time.
+    #           - id: background
+    #             value: 'background'
+    #             brief: >
+    #               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.
+    #           - id: foreground
+    #             value: 'foreground'
+    #             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.

model/registry/android.yaml

@@ -13,37 +13,3 @@ groups:
           (`os.version`) of the android operating system. More information can be found
           [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels).
         examples: ['33', '32']
-  - id: registry.android.lifecycle.events
-    prefix: android
-    type: attribute_group
-    brief: >
-        This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform.
-    attributes:
-      - id: state
-        stability: experimental
-        brief: >
-          This attribute represents the state the application has transitioned into at the occurrence of the event.
-        note: >
-          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.
-        type:
-          allow_custom_values: true
-          members:
-            - id: created
-              value: 'created'
-              brief: >
-                Any time before Activity.onResume() or, if the app has no Activity, Context.startService()
-                has been called in the app for the first time.
-              stability: experimental
-            - id: background
-              value: 'background'
-              brief: >
-                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.
-              stability: experimental
-            - id: foreground
-              value: 'foreground'
-              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.
-              stability: experimental

model/registry/deprecated/android.yaml

@@ -0,0 +1,36 @@
+groups:
+  - id: registry.android.deprecated
+    prefix: android
+    type: attribute_group
+    brief: >
+        This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform.
+    attributes:
+      - id: state
+        stability: experimental
+        brief: >
+          Deprecated use the `device.app.lifecycle` event definition including
+          `android.state` as a payload field instead.
+        note: >
+          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.
+        type:
+          allow_custom_values: true
+          members:
+            - id: created
+              value: 'created'
+              brief: >
+                Any time before Activity.onResume() or, if the app has no Activity, Context.startService()
+                has been called in the app for the first time.
+              stability: experimental
+            - id: background
+              value: 'background'
+              brief: >
+                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.
+              stability: experimental
+            - id: foreground
+              value: 'foreground'
+              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.
+              stability: experimental

model/registry/deprecated/ios.yaml

@@ -1,5 +1,5 @@
 groups:
-  - id: registry.ios.lifecycle.events
+  - id: registry.ios.deprecated
     prefix: ios
     type: attribute_group
     brief: >
@@ -7,11 +7,13 @@ groups:
     attributes:
       - id: state
         stability: experimental
+        deprecated: "Moved to a payload field of `device.app.lifecycle`."
         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.
         brief: >
-          This attribute represents the state the application has transitioned into at the occurrence of the event.
+          Deprecated use the `device.app.lifecycle` event definition including
+          `ios.state` as a payload field instead.
         type:
           allow_custom_values: true
           members: