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

Rework device events (#1880) 

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
This commit is contained in:
jason plumb 2025-02-18 10:04:31 -08:00 committed by GitHub
parent 61132ad905
commit e70853397b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 158 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.chloggen/1880.yaml Normal file
View File

@ -0,0 +1,8 @@
change_type: breaking
component: mobile
note: Rework `device.app.lifecycle` mobile event.
issues: [1880]
subtext: |
The `device.app.lifecycle` event has been reworked to use attributes instead
of event body fields. The `ios.app.state` and `android.app.state` attributes
have been reintroduced to the attribute registry.

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

@ -60,6 +60,7 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:jvm
- area:k8s
- area:linux

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

@ -52,6 +52,7 @@ body:
- area:heroku
- area:host
- area:http
- area:ios
- area:jvm
- area:k8s
- area:linux

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

@ -12,17 +12,30 @@ The Android platform on which the Android application is running.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="android-app-state" href="#android-app-state">`android.app.state`</a> | string | This attribute represents the state of the application. [1] | `created` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="android-os-api-level" href="#android-os-api-level">`android.os.api_level`</a> | 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` | ![Development](https://img.shields.io/badge/-development-blue) |
**[1] `android.app.state`:** 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.
---
`android.app.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 |
|---|---|---|
| `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. | ![Development](https://img.shields.io/badge/-development-blue) |
| `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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-blue) |
## Deprecated Android Attributes
This document defines attributes that represents an occurrence of a lifecycle transition on the Android platform.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="android-state" href="#android-state">`android.state`</a> | string | Deprecated use the `device.app.lifecycle` event definition including `android.state` as a payload field instead. [1] | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `device.app.lifecycle`. |
| <a id="android-state" href="#android-state">`android.state`</a> | string | Deprecated. Use `android.app.state` instead. [2] | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Renamed to `android.app.state` |
**[1] `android.state`:** 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] `android.state`:** 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.
---

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

@ -3,15 +3,40 @@
# iOS
- [iOS Attributes](#ios-attributes)
- [Deprecated iOS Attributes](#deprecated-ios-attributes)
## iOS Attributes
This group describes iOS-specific attributes.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="ios-app-state" href="#ios-app-state">`ios.app.state`</a> | string | This attribute represents the state of the application. [1] | `active`; `inactive`; `background` | ![Development](https://img.shields.io/badge/-development-blue) |
**[1] `ios.app.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
---
`ios.app.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`. | ![Development](https://img.shields.io/badge/-development-blue) |
| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | ![Development](https://img.shields.io/badge/-development-blue) |
| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | ![Development](https://img.shields.io/badge/-development-blue) |
| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | ![Development](https://img.shields.io/badge/-development-blue) |
| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | ![Development](https://img.shields.io/badge/-development-blue) |
## Deprecated iOS Attributes
The iOS platform on which the iOS application is running.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="ios-state" href="#ios-state">`ios.state`</a> | string | Deprecated use the `device.app.lifecycle` event definition including `ios.state` as a payload field instead. [1] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Moved to a payload field of `device.app.lifecycle`. |
| <a id="ios-state" href="#ios-state">`ios.state`</a> | string | Deprecated. use the `ios.app.state` instead. [2] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Renamed to `ios.app.state` |
**[1] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
**[2] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
---

4
docs/general/session.md
View File

@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#event-sessionstar
## Session Events
## Event: `session.start`
### Event: `session.start`
<!-- semconv event.session.start -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
@ -70,7 +70,7 @@ When the `session.start` event contains both `session.id` and `session.previous_
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
## Event: `session.end`
### Event: `session.end`
<!-- semconv event.session.end -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->

22
docs/mobile/events.md
View File

@ -39,20 +39,20 @@ This event represents an occurrence of a lifecycle transition on Android or iOS
The event body fields MUST be used to describe the state of the application at the time of the event.
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).
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` value.
The `android.app.state` and `ios.app.state` fields are mutually exclusive and MUST NOT be used together, each field MUST be used with its corresponding `os.name` value.
**Body fields:**
| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| `android.state` | enum | 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` | ![Development](https://img.shields.io/badge/-development-blue) |
| `ios.state` | enum | 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` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`android.app.state`](/docs/attributes-registry/android.md) | string | This attribute represents the state of the application. [1] | `created` | `Conditionally Required` if and only if `os.name` is `android` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`ios.app.state`](/docs/attributes-registry/ios.md) | string | This attribute represents the state of the application. [2] | `active`; `inactive`; `background` | `Conditionally Required` if and only if `os.name` is `ios` | ![Development](https://img.shields.io/badge/-development-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.
**[1] `android.app.state`:** 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), and from which the `OS terminology` column values are derived.
**[2] `ios.app.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
`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.
---
`android.app.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 |
|---|---|---|
@ -60,7 +60,9 @@ The `android.state` and `ios.state` fields are mutually exclusive and MUST NOT b
| `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. | ![Development](https://img.shields.io/badge/-development-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. | ![Development](https://img.shields.io/badge/-development-blue) |
`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.
---
`ios.app.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 |
|---|---|---|

6
model/android/deprecated/registry-deprecated.yaml
View File

@ -7,10 +7,8 @@ groups:
attributes:
- id: android.state
stability: development
deprecated: "Replaced by `device.app.lifecycle`."
brief: >
Deprecated use the `device.app.lifecycle` event definition including
`android.state` as a payload field instead.
deprecated: "Renamed to `android.app.state`"
brief: Deprecated. Use `android.app.state` 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.

28
model/android/registry.yaml
View File

@ -13,3 +13,31 @@ 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: android.app.state
stability: development
brief: >
This attribute represents the state of the application.
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.
examples: [ "created" ]
type:
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: development
- 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: development
- 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: development

88
model/device/events.yaml
View File

@ -13,81 +13,13 @@ groups:
[resource semantic convention](/docs/resource/os.md) to identify the
mobile operating system (e.g. Android, iOS).
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` value.
body:
id: device_lifecycle_state
type: map
requirement_level: required
stability: development
fields:
- id: ios.state
stability: development
requirement_level:
conditionally_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),
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.
examples: ["active"]
type: enum
members:
- id: active
value: 'active'
brief: >
The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.
stability: development
- id: inactive
value: 'inactive'
brief: >
The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.
stability: development
- id: background
value: 'background'
brief: >
The app is now in the background.
This value is associated with UIKit notification `applicationDidEnterBackground`.
stability: development
- id: foreground
value: 'foreground'
brief: >
The app is now in the foreground.
This value is associated with UIKit notification `applicationWillEnterForeground`.
stability: development
- id: terminate
value: 'terminate'
brief: >
The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.
stability: development
- id: android.state
stability: development
requirement_level:
conditionally_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.
examples: ["created"]
type: enum
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: development
- 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: development
- 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: development
The `android.app.state` and `ios.app.state` fields are mutually
exclusive and MUST NOT be used together, each field MUST be
used with its corresponding `os.name` value.
attributes:
- ref: ios.app.state
requirement_level:
conditionally_required: if and only if `os.name` is `ios`
- ref: android.app.state
requirement_level:
conditionally_required: if and only if `os.name` is `android`

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

@ -7,13 +7,11 @@ groups:
attributes:
- id: ios.state
stability: development
deprecated: "Moved to a payload field of `device.app.lifecycle`."
deprecated: "Renamed to `ios.app.state`"
brief: Deprecated. use the `ios.app.state` instead.
note: >
The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate),
and from which the `OS terminology` column values are derived.
brief: >
Deprecated use the `device.app.lifecycle` event definition including
`ios.state` as a payload field instead.
type:
members:
- id: active

43
model/ios/registry.yaml Normal file
View File

@ -0,0 +1,43 @@
groups:
- id: registry.ios
type: attribute_group
display_name: iOS Attributes
brief: >
This group describes iOS-specific attributes.
attributes:
- id: ios.app.state
stability: development
brief: >
This attribute represents the state of the application.
note: >
The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate),
and from which the `OS terminology` column values are derived.
type:
members:
- id: active
value: 'active'
brief: >
The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`.
stability: development
- id: inactive
value: 'inactive'
brief: >
The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`.
stability: development
- id: background
value: 'background'
brief: >
The app is now in the background.
This value is associated with UIKit notification `applicationDidEnterBackground`.
stability: development
- id: foreground
value: 'foreground'
brief: >
The app is now in the foreground.
This value is associated with UIKit notification `applicationWillEnterForeground`.
stability: development
- id: terminate
value: 'terminate'
brief: >
The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`.
stability: development

7
schema-next.yaml
View File

@ -2,6 +2,13 @@ file_format: 1.1.0
schema_url: https://opentelemetry.io/schemas/next
versions:
next:
all:
changes:
# https://github.com/open-telemetry/semantic-conventions/pull/1880
- rename_attributes:
attribute_map:
android.state: android.app.state
io.state: ios.app.state
metrics:
changes:
- rename_metrics: