Rework device events (#1880)

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>

.chloggen/1880.yaml

@@ -0,0 +1,8 @@
+change_type: breaking
+component: mobile
+note: Rework `device.app.lifecycle` mobile event.
+issues: [1880]
+subtext: |
+  The `device.app.lifecycle` event has been reworked to use attributes instead
+  of event body fields. The `ios.app.state` and `android.app.state` attributes
+  have been reintroduced to the attribute registry.

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -60,6 +60,7 @@ body:
         - area:heroku
         - area:host
         - area:http
+        - area:ios
         - area:jvm
         - area:k8s
         - area:linux

.github/ISSUE_TEMPLATE/change_proposal.yaml

@@ -52,6 +52,7 @@ body:
         - area:heroku
         - area:host
         - area:http
+        - area:ios
         - area:jvm
         - area:k8s
         - area:linux

docs/attributes-registry/android.md

@@ -12,17 +12,30 @@ The Android platform on which the Android application is running.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
+| <a id="android-app-state" href="#android-app-state">`android.app.state`</a> | string | This attribute represents the state of the application. [1] | `created` | ![Development](https://img.shields.io/badge/-development-blue) |
 | <a id="android-os-api-level" href="#android-os-api-level">`android.os.api_level`</a> | 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` | ![Development](https://img.shields.io/badge/-development-blue) |
 
+**[1] `android.app.state`:** 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.
+
+---
+
+`android.app.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 |
+|---|---|---|
+| `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. | ![Development](https://img.shields.io/badge/-development-blue) |
+| `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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-blue) |
+
 ## Deprecated Android Attributes
 
 This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="android-state" href="#android-state">`android.state`</a> | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `device.app.lifecycle`. |
+| <a id="android-state" href="#android-state">`android.state`</a> | string | Deprecated. Use `android.app.state` instead. [2] | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Renamed to `android.app.state` |
 
-**[1] `android.state`:** 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] `android.state`:** 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

@@ -3,15 +3,40 @@
 
 # iOS
 
+- [iOS Attributes](#ios-attributes)
+- [Deprecated iOS Attributes](#deprecated-ios-attributes)
+
+## iOS Attributes
+
+This group describes iOS-specific attributes.
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| <a id="ios-app-state" href="#ios-app-state">`ios.app.state`</a> | string | This attribute represents the state of the application. [1] | `active`; `inactive`; `background` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `ios.app.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
+
+---
+
+`ios.app.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`. | ![Development](https://img.shields.io/badge/-development-blue) |
+| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Development](https://img.shields.io/badge/-development-blue) |
+| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Development](https://img.shields.io/badge/-development-blue) |
+| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Development](https://img.shields.io/badge/-development-blue) |
+| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Development](https://img.shields.io/badge/-development-blue) |
+
 ## Deprecated iOS Attributes
 
 The iOS platform on which the iOS application is running.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="ios-state" href="#ios-state">`ios.state`</a> | string | Deprecated use the `device.app.lifecycle` event definition including `ios.state` as a payload field instead. [1] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Moved to a payload field of `device.app.lifecycle`. |
+| <a id="ios-state" href="#ios-state">`ios.state`</a> | string | Deprecated. use the `ios.app.state` instead. [2] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Renamed to `ios.app.state` |
 
-**[1] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
+**[2] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
 
 ---
 

docs/general/session.md

@@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#event-sessionstar
 
 ## Session Events
 
-## Event: `session.start`
+### Event: `session.start`
 
 <!-- semconv event.session.start -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@@ -70,7 +70,7 @@ When the `session.start` event contains both `session.id` and `session.previous_
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-## Event: `session.end`
+### Event: `session.end`
 
 <!-- semconv event.session.end -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->

docs/mobile/events.md

@@ -39,20 +39,20 @@ This event represents an occurrence of a lifecycle transition on Android or iOS
 
 The event body fields MUST be used to describe the state of the application at the time of the event.
 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).
-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` value.
+The `android.app.state` and `ios.app.state` fields are mutually exclusive and MUST NOT be used together, each field MUST be used with its corresponding `os.name` value.
 
-**Body fields:**
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
-
-| Body Field  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| `android.state` | enum | 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` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`android.app.state`](/docs/attributes-registry/android.md) | string | This attribute represents the state of the application. [1] | `created` | `Conditionally Required` if and only if `os.name` is `android` | ![Development](https://img.shields.io/badge/-development-blue) |
-| `ios.state` | enum | 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` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`ios.app.state`](/docs/attributes-registry/ios.md) | string | This attribute represents the state of the application. [2] | `active`; `inactive`; `background` | `Conditionally Required` if and only if `os.name` is `ios` | ![Development](https://img.shields.io/badge/-development-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.
+**[1] `android.app.state`:** 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), and from which the `OS terminology` column values are derived.
+**[2] `ios.app.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
 
-`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.
+---
+
+`android.app.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 |
 |---|---|---|
@@ -60,7 +60,9 @@ The `android.state` and `ios.state` fields are mutually exclusive and MUST NOT b
 | `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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-blue) |
 
-`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.
+---
+
+`ios.app.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 |
 |---|---|---|

model/android/deprecated/registry-deprecated.yaml

@@ -7,10 +7,8 @@ groups:
     attributes:
       - id: android.state
         stability: development
-        deprecated: "Replaced by `device.app.lifecycle`."
+        deprecated: "Renamed to `android.app.state`"
-        brief: >
+        brief: Deprecated. Use `android.app.state` instead.
-          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.

model/android/registry.yaml

@@ -13,3 +13,31 @@ 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: android.app.state
+        stability: development
+        brief: >
+          This attribute represents the state of the application.
+        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.
+        examples: [ "created" ]
+        type:
+          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: development
+            - 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: development
+            - 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: development

model/device/events.yaml

@@ -13,81 +13,13 @@ groups:
       [resource semantic convention](/docs/resource/os.md) to identify the
       mobile operating system (e.g. Android, iOS).
 
-      The `android.state` and `ios.state` fields are mutually exclusive and MUST
+      The `android.app.state` and `ios.app.state` fields are mutually
-      NOT be used together, each field MUST be used with its corresponding
+      exclusive and MUST NOT be used together, each field MUST be
-      `os.name` value.
+      used with its corresponding `os.name` value.
-    body:
+    attributes:
-      id: device_lifecycle_state
+      - ref: ios.app.state
-      type: map
-      requirement_level: required
-      stability: development
-      fields:
-        - id: ios.state
-          stability: development
         requirement_level:
           conditionally_required: if and only if `os.name` is `ios`
-          note: >
+      - ref: android.app.state
-            The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate),
-            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.
-          examples: ["active"]
-          type: enum
-          members:
-            - id: active
-              value: 'active'
-              brief: >
-                The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.
-              stability: development
-            - id: inactive
-              value: 'inactive'
-              brief: >
-                The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.
-              stability: development
-            - id: background
-              value: 'background'
-              brief: >
-                The app is now in the background.
-                This value is associated with UIKit notification `applicationDidEnterBackground`.
-              stability: development
-            - id: foreground
-              value: 'foreground'
-              brief: >
-                The app is now in the foreground.
-                This value is associated with UIKit notification `applicationWillEnterForeground`.
-              stability: development
-            - id: terminate
-              value: 'terminate'
-              brief: >
-                The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.
-              stability: development
-        - id: android.state
-          stability: development
         requirement_level:
           conditionally_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.
-          examples: ["created"]
-          type: enum
-          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: development
-            - 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: development
-            - 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: development

model/ios/deprecated/registry-deprecated.yaml

@@ -7,13 +7,11 @@ groups:
     attributes:
       - id: ios.state
         stability: development
-        deprecated: "Moved to a payload field of `device.app.lifecycle`."
+        deprecated: "Renamed to `ios.app.state`"
+        brief: Deprecated. use the `ios.app.state` instead.
         note: >
           The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate),
           and from which the `OS terminology` column values are derived.
-        brief: >
-          Deprecated use the `device.app.lifecycle` event definition including
-          `ios.state` as a payload field instead.
         type:
           members:
             - id: active

model/ios/registry.yaml

@@ -0,0 +1,43 @@
+groups:
+  - id: registry.ios
+    type: attribute_group
+    display_name: iOS Attributes
+    brief: >
+      This group describes iOS-specific attributes.
+    attributes:
+      - id: ios.app.state
+        stability: development
+        brief: >
+          This attribute represents the state of the application.
+        note: >
+          The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate),
+          and from which the `OS terminology` column values are derived.
+        type:
+          members:
+            - id: active
+              value: 'active'
+              brief: >
+                The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.
+              stability: development
+            - id: inactive
+              value: 'inactive'
+              brief: >
+                The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.
+              stability: development
+            - id: background
+              value: 'background'
+              brief: >
+                The app is now in the background.
+                This value is associated with UIKit notification `applicationDidEnterBackground`.
+              stability: development
+            - id: foreground
+              value: 'foreground'
+              brief: >
+                The app is now in the foreground.
+                This value is associated with UIKit notification `applicationWillEnterForeground`.
+              stability: development
+            - id: terminate
+              value: 'terminate'
+              brief: >
+                The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.
+              stability: development

schema-next.yaml

@@ -2,6 +2,13 @@ file_format: 1.1.0
 schema_url: https://opentelemetry.io/schemas/next
 versions:
   next:
+    all:
+      changes:
+        # https://github.com/open-telemetry/semantic-conventions/pull/1880
+        - rename_attributes:
+            attribute_map:
+              android.state: android.app.state
+              io.state: ios.app.state
     metrics:
       changes:
         - rename_metrics: