open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the device.app.lifecycle event description and constraints (#794) 

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
This commit is contained in:
Nev 2024-04-22 09:41:54 -07:00 committed by GitHub
parent 7f6876de7d
commit b6bc365b76
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 181 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
.chloggen/device_app_lifecycle.yaml Normal file
View File

@ -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
.github/ISSUE_TEMPLATE/bug_report.yaml vendored
View File

@ -46,7 +46,6 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:k8s
- area:log
- area:messaging

1
.github/ISSUE_TEMPLATE/change_proposal.yaml vendored
View File

@ -39,7 +39,6 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:k8s
- area:log
- area:messaging

1
.github/ISSUE_TEMPLATE/new-conventions.yaml vendored
View File

@ -48,7 +48,6 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:k8s
- area:log
- area:messaging

1
.gitignore vendored
View File

@ -7,6 +7,7 @@
.project
.settings
bin
.vs
# NetBeans
/.nb-gradle

2
.vscode/settings.json vendored
View File

@ -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

9
docs/attributes-registry/android.md
View File

@ -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.

8
docs/attributes-registry/ios.md
View File

@ -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.

59
docs/mobile/events.md
View File

@ -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 -->
@ -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.
<!-- semconv ios.lifecycle.events(full) -->
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.
### Event details
<!-- semconv device.app.lifecycle(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) |
**[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` 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 |
|---|---|---|
| `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 |
@ -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) |
<!-- 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
model/logs/mobile-events.yaml
View File

@ -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
model/registry/android.yaml
View File

@ -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

36
model/registry/deprecated/android.yaml Normal file
View File

@ -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

6
model/registry/ios.yaml → model/registry/deprecated/ios.yaml
View File

@ -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: