Skip to content

Commit

Permalink
Update the device.app.lifecycle event description and constraints (#794)
Browse files Browse the repository at this point in the history
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
  • Loading branch information
MSNev and lmolkova authored Apr 22, 2024
1 parent 7f6876d commit b6bc365
Show file tree
Hide file tree
Showing 13 changed files with 180 additions and 87 deletions.
26 changes: 26 additions & 0 deletions .chloggen/device_app_lifecycle.yaml
Original file line number Diff line number Diff line change
@@ -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.
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:k8s
- area:log
- area:messaging
Expand Down
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/change_proposal.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,6 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:k8s
- area:log
- area:messaging
Expand Down
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/new-conventions.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:k8s
- area:log
- area:messaging
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
.project
.settings
bin
.vs

# NetBeans
/.nb-gradle
Expand Down
2 changes: 1 addition & 1 deletion .vscode/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 5 additions & 4 deletions docs/attributes-registry/android.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
8 changes: 4 additions & 4 deletions docs/attributes-registry/ios.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
57 changes: 31 additions & 26 deletions docs/mobile/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ events on mobile platforms. All mobile events MUST use a namespace of
<!-- toc -->

- [Lifecycle instrumentation](#lifecycle-instrumentation)
- [iOS](#ios)
- [Android](#android)
- [Event details](#event-details)

<!-- tocstop -->

Expand All @@ -21,46 +20,52 @@ 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 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.
<!-- semconv device.app.lifecycle(full) -->
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) |
<!-- endsemconv -->

### Android

<!-- 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 |
<!-- 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 |
|---|---|---|---|---|---|
| [`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 |
|---|---|---|
| `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
85 changes: 72 additions & 13 deletions model/logs/mobile-events.yaml
Original file line number Diff line number Diff line change
@@ -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.
34 changes: 0 additions & 34 deletions model/registry/android.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading

0 comments on commit b6bc365

Please sign in to comment.