Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the device.app.lifecycle event description and constraints #673

Closed
wants to merge 1 commit into from
Closed

Update the device.app.lifecycle event description and constraints #673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
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
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ release.

### Fixes

- Reformat and update the `device.app.lifecycle` event description adds
constraints for the possible values of the `android.state` and `ios.state`.
([#673](https://github.com/open-telemetry/semantic-conventions/pull/673))

## v1.24.0 (2023-12-15)

### Breaking
Expand Down
59 changes: 36 additions & 23 deletions docs/mobile/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ events on mobile platforms. All mobile events MUST use a namespace of
<!-- toc -->

- [Lifecycle instrumentation](#lifecycle-instrumentation)
* [iOS](#ios)
* [Android](#android)
* [Event Name](#event-name)
* [Event Payload (Log Body)](#event-payload-log-body)

<!-- tocstop -->

Expand All @@ -21,46 +21,59 @@ 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
### Event name

<!-- semconv ios.lifecycle.events -->
<!-- semconv device.app.lifecycle(full) -->
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just curious what does the (full) part means?

The event name MUST be `device.app.lifecycle`.

| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `active` | Required |

**[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` MUST be one of the following:

| Value | Description |
|---|---|
| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. |
| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. |
| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. |
| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. |
| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. |
<!-- endsemconv -->

### Android
### Event payload (Log Body)

<!-- semconv android.lifecycle.events -->
The event name MUST be `device.app.lifecycle`.
Payload attributes MUST be used to describe the state of the application at the
time of the event. The following table describes the payload attributes that MUST
be used to describe the state of the application at the time of the event.

The `android.state` and `ios.state` attributes are mutually exclusive and MUST
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are some native mobile apps where there are two platforms at play. For instance, Unity apps are written in a cross-platform way and can be deployed on both iOS and Android, in which case we want to convey that it's a Unity app and the event is firing in a specific platform.

If we have this mutual exclusivity, how can we represent that? I can see at least two options:

  • Allow duplication of states, and rely on the fact that an event can't both be iOS and Android at the same time, but could potentially be one of each, and then also be Unity, React Native, Kotlin Multiplatform, etc.
  • Have a separate (optional) attribute that represents the framework used to generate the app, and keep the actual OS state mutually exclusive.

BTW, this may be beyond the scope of this change - if so, I can submit another pull request to add this.

NOT be used together, each attribute MUST be used with it's corresponding
`os.name` [resource semantic convention](/docs/resource/os.md) value. For
example, if the `os.name` attribute is set to `android` then the
`android.state` attribute MUST be used and the `ios.state` attribute MUST NOT
be used. If the `os.name` attribute is set to `ios` then the `ios.state`
attribute MUST be used and the `android.state` attribute MUST NOT be used.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is the way it was before, although after reading this paragraph, it seems to me that it might not be necessary to prepend the OS name (either android. or ios.) to the state attr name, given that the os.name attr must be present anyway, rendering the OS prefixes in state redundant in my opinion.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the desire to have the prefix due to the fact that we want to allow a separate list of valid values for each?


<!-- semconv device.app.lifecycle.payload(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | Required |
| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | See below |
| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [2] | `active` | See below |

**[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` MUST be one of the following:

| Value | Description |
|---|---|
| `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. |
| `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. |
| `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. |

`ios.state` MUST be one of the following:

| Value | Description |
|---|---|
| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. |
| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. |
| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. |
| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. |
| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. |
<!-- endsemconv -->

[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
33 changes: 18 additions & 15 deletions model/logs/mobile-events.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,20 @@
groups:
- id: ios.lifecycle.events
- id: device.app.lifecycle
type: event
prefix: ios
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.
note: >
This events identifies the fields that are common to all lifecycle events for android and iOS using
the `android.state` and `ios.state` attributes. The `android.state` and `ios.state` attributes are
mutually exclusive.

- id: device.app.lifecycle.payload
type: attribute_group
brief: >
This defines the content of the Log Body for the device.app.lifecycle event.
attributes:
- id: state
requirement_level: "required"
- id: ios.state
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.
Expand Down Expand Up @@ -37,16 +44,8 @@
- id: terminate
value: 'terminate'
brief: >
The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.
- id: android.lifecycle.events
type: event
prefix: android
name: device.app.lifecycle
brief: >
This event represents an occurrence of a lifecycle transition on the Android platform.
attributes:
- id: state
requirement_level: required
The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.

Check failure on line 47 in model/logs/mobile-events.yaml

View workflow job for this annotation

GitHub Actions / yamllint 

[trailing-spaces] trailing spaces
- id: android.state
brief: >
This attribute represents the state the application has transitioned into at the occurrence of the event.
note: >
Expand All @@ -70,3 +69,7 @@
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.
constraints:
- any_of:
- "ios.state"
- "android.state"

Check failure on line 75 in model/logs/mobile-events.yaml

View workflow job for this annotation

GitHub Actions / yamllint 

[new-line-at-end-of-file] no new line character at the end of file
Loading