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.

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 #794

Merged
merged 7 commits into from
Apr 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
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.
MSNev marked this conversation as resolved.
Show resolved Hide resolved

**[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`.
lmolkova marked this conversation as resolved.
Show resolved Hide resolved

MSNev marked this conversation as resolved.
Show resolved Hide resolved
| 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
MSNev marked this conversation as resolved.
Show resolved Hide resolved
- 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:
MSNev marked this conversation as resolved.
Show resolved Hide resolved
# 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
Loading