From b6bc365b7689df96d97682a164318f44e0cd3bd8 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Mon, 22 Apr 2024 09:41:54 -0700 Subject: [PATCH] Update the device.app.lifecycle event description and constraints (#794) Co-authored-by: Liudmila Molkova --- .chloggen/device_app_lifecycle.yaml | 26 +++++++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 - .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 - .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 - .gitignore | 1 + .vscode/settings.json | 2 +- docs/attributes-registry/android.md | 9 ++- docs/attributes-registry/ios.md | 8 +- docs/mobile/events.md | 57 +++++++------- model/logs/mobile-events.yaml | 85 +++++++++++++++++---- model/registry/android.yaml | 34 --------- model/registry/deprecated/android.yaml | 36 +++++++++ model/registry/{ => deprecated}/ios.yaml | 6 +- 13 files changed, 180 insertions(+), 87 deletions(-) create mode 100644 .chloggen/device_app_lifecycle.yaml create mode 100644 model/registry/deprecated/android.yaml rename model/registry/{ => deprecated}/ios.yaml (88%) diff --git a/.chloggen/device_app_lifecycle.yaml b/.chloggen/device_app_lifecycle.yaml new file mode 100644 index 0000000000..18fdf8a931 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index c78207d5fe..896738c60c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 355217d372..ca2933bc38 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index c4dd0faedb..1c1afe1779 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.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 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/.vscode/settings.json b/.vscode/settings.json index ec636cc19b..7741a3e1f5 100644 --- a/.vscode/settings.json +++ b/.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 diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md index f2ca703769..971f390749 100644 --- a/docs/attributes-registry/android.md +++ b/docs/attributes-registry/android.md @@ -3,23 +3,24 @@ - [Android Attributes](#android-attributes) -- [Android Lifecycle Event Attributes](#android-lifecycle-event-attributes) +- [Deprecated Android Attributes](#deprecated-android-attributes) ## Android Attributes + | 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) | -## Android Lifecycle Event Attributes +## Deprecated Android Attributes - + | 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. diff --git a/docs/attributes-registry/ios.md b/docs/attributes-registry/ios.md index e8aea69f54..b867deac8e 100644 --- a/docs/attributes-registry/ios.md +++ b/docs/attributes-registry/ios.md @@ -5,16 +5,16 @@ -- [iOS Lifecycle Event Attributes](#ios-lifecycle-event-attributes) +- [Deprecated iOS Attributes](#deprecated-ios-attributes) -## iOS Lifecycle Event Attributes +## Deprecated iOS Attributes - + | 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)
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. diff --git a/docs/mobile/events.md b/docs/mobile/events.md index b02760674b..06a6907ef4 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -9,8 +9,7 @@ events on mobile platforms. All mobile events MUST use a namespace of - [Lifecycle instrumentation](#lifecycle-instrumentation) - - [iOS](#ios) - - [Android](#android) + - [Event details](#event-details) @@ -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. - -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) | +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. -**[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. +### Event details -`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. + +The event name MUST be `device.app.lifecycle`. -| 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) | -### Android - - -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 | + +| Body Field | 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) | - + +`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) | + [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 6664bd1edb..4b1d956b21 100644 --- a/model/logs/mobile-events.yaml +++ b/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. - attributes: - - ref: ios.state - requirement_level: "required" - - id: android.lifecycle.events - type: event - name: device.app.lifecycle - brief: > - This event represents an occurrence of a lifecycle transition on the Android platform. - attributes: - - ref: android.state - requirement_level: required + This event represents an occurrence of a lifecycle transition on Android or iOS platform. + note: > + This event identifies the fields that are common to all lifecycle events for android and iOS using + the `android.state` and `ios.state` fields. The `android.state` and `ios.state` attributes are + mutually exclusive. + # Future Note: When the build tools support this definition please uncomment and validate the details + # included here and what has been added to the manual markdown table + # body: + # fields: + # - id: ios.state + # stability: experimental + # 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. diff --git a/model/registry/android.yaml b/model/registry/android.yaml index bddc74a09a..cfdcac8a46 100644 --- a/model/registry/android.yaml +++ b/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 diff --git a/model/registry/deprecated/android.yaml b/model/registry/deprecated/android.yaml new file mode 100644 index 0000000000..97e9bd1e7a --- /dev/null +++ b/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 diff --git a/model/registry/ios.yaml b/model/registry/deprecated/ios.yaml similarity index 88% rename from model/registry/ios.yaml rename to model/registry/deprecated/ios.yaml index 1bfe30f325..acc1a9f1f9 100644 --- a/model/registry/ios.yaml +++ b/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: