From e70853397b73ca9cb85b1df45182b6a3e299c85e Mon Sep 17 00:00:00 2001 From: jason plumb <75337021+breedx-splk@users.noreply.github.com> Date: Tue, 18 Feb 2025 10:04:31 -0800 Subject: [PATCH] Rework device events (#1880) Co-authored-by: Trask Stalnaker Co-authored-by: Liudmila Molkova --- .chloggen/1880.yaml | 8 ++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + docs/attributes-registry/android.md | 17 +++- docs/attributes-registry/ios.md | 29 +++++- docs/general/session.md | 4 +- docs/mobile/events.md | 22 ++--- .../deprecated/registry-deprecated.yaml | 6 +- model/android/registry.yaml | 28 ++++++ model/device/events.yaml | 88 +++---------------- model/ios/deprecated/registry-deprecated.yaml | 6 +- model/ios/registry.yaml | 43 +++++++++ schema-next.yaml | 7 ++ 13 files changed, 158 insertions(+), 102 deletions(-) create mode 100644 .chloggen/1880.yaml create mode 100644 model/ios/registry.yaml diff --git a/.chloggen/1880.yaml b/.chloggen/1880.yaml new file mode 100644 index 000000000..7b7c64874 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 585224e32..4edc8d969 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index a04b1977c..b9e963a44 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.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 diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md index b232e3061..2de21274a 100644 --- a/docs/attributes-registry/android.md +++ b/docs/attributes-registry/android.md @@ -12,17 +12,30 @@ The Android platform on which the Android application is running. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `android.app.state` | string | This attribute represents the state of the application. [1] | `created` | ![Development](https://img.shields.io/badge/-development-blue) | | `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` | ![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 | |---|---|---|---|---| -| `android.state` | 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)
Replaced by `device.app.lifecycle`. | +| `android.state` | string | Deprecated. Use `android.app.state` instead. [2] | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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. --- diff --git a/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md index ea4827d90..1b4a7045f 100644 --- a/docs/attributes-registry/ios.md +++ b/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 | +|---|---|---|---|---| +| `ios.app.state` | 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 | |---|---|---|---|---| -| `ios.state` | 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)
Moved to a payload field of `device.app.lifecycle`. | +| `ios.state` | string | Deprecated. use the `ios.app.state` instead. [2] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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. --- diff --git a/docs/general/session.md b/docs/general/session.md index bbdc6cf49..d39ffe185 100644 --- a/docs/general/session.md +++ b/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` @@ -70,7 +70,7 @@ When the `session.start` event contains both `session.id` and `session.previous_ -## Event: `session.end` +### Event: `session.end` diff --git a/docs/mobile/events.md b/docs/mobile/events.md index 717df593f..54bbb6854 100644 --- a/docs/mobile/events.md +++ b/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:** - -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +| Attribute | 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) | -| `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) | +| [`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.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 | |---|---|---| diff --git a/model/android/deprecated/registry-deprecated.yaml b/model/android/deprecated/registry-deprecated.yaml index e6c8007ab..38482b5fe 100644 --- a/model/android/deprecated/registry-deprecated.yaml +++ b/model/android/deprecated/registry-deprecated.yaml @@ -7,10 +7,8 @@ groups: attributes: - id: android.state stability: development - deprecated: "Replaced by `device.app.lifecycle`." - brief: > - Deprecated use the `device.app.lifecycle` event definition including - `android.state` as a payload field instead. + deprecated: "Renamed to `android.app.state`" + brief: Deprecated. Use `android.app.state` 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. diff --git a/model/android/registry.yaml b/model/android/registry.yaml index 2e13c93e1..eeefe9b6d 100644 --- a/model/android/registry.yaml +++ b/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 diff --git a/model/device/events.yaml b/model/device/events.yaml index dbb83031e..0cf59e704 100644 --- a/model/device/events.yaml +++ b/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 - NOT be used together, each field MUST be used with its corresponding - `os.name` value. - body: - id: device_lifecycle_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: > - 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 + 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. + attributes: + - ref: ios.app.state + requirement_level: + conditionally_required: if and only if `os.name` is `ios` + - ref: android.app.state + requirement_level: + conditionally_required: if and only if `os.name` is `android` diff --git a/model/ios/deprecated/registry-deprecated.yaml b/model/ios/deprecated/registry-deprecated.yaml index faf62ff2c..af6840861 100644 --- a/model/ios/deprecated/registry-deprecated.yaml +++ b/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 diff --git a/model/ios/registry.yaml b/model/ios/registry.yaml new file mode 100644 index 000000000..7771e1933 --- /dev/null +++ b/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 diff --git a/schema-next.yaml b/schema-next.yaml index 23675166b..14ddba0a2 100644 --- a/schema-next.yaml +++ b/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: