Skip to content

Commit

Permalink
Update the device.app.lifecycle event description
Browse files Browse the repository at this point in the history
- Update to manually generated markdown
  • Loading branch information
MSNev committed Mar 6, 2024
1 parent 19f2ba7 commit 3b23f05
Show file tree
Hide file tree
Showing 4 changed files with 126 additions and 94 deletions.
22 changes: 22 additions & 0 deletions .chloggen/device_app_lifecycle.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# 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: bug_fix

# 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:
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
62 changes: 36 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,57 @@ 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
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.

<!-- semconv ios.lifecycle.events -->
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 |
The `android.state` and `ios.state` attributes are mutually exclusive and MUST
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.

**[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` MUST be one of the following:
<!-- semconv device.app.lifecycle(full) -->
The event name MUST be `device.app.lifecycle`.

| 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

<!-- semconv android.lifecycle.events -->
The event name MUST be `device.app.lifecycle`.

| Attribute | Type | Description | Examples | Requirement Level |
<!-- Manually adding the markdown table until the body definition is available in the build tools -->
| Body Field | 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. |
<!-- endsemconv -->

`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`. |
<!-- end of manually added table -->

[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
135 changes: 67 additions & 68 deletions model/logs/mobile-events.yaml
Original file line number Diff line number Diff line change
@@ -1,72 +1,71 @@
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.
attributes:
- id: state
requirement_level: "required"
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.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
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.
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.
# body:
# fields:
# - 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.
# 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
# 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.
# constraints:
# - any_of:
# - "ios.state"
# - "android.state"

0 comments on commit 3b23f05

Please sign in to comment.