81 lines
5.0 KiB
Markdown
81 lines
5.0 KiB
Markdown
<!--- Hugo front matter used to generate the website version of this page:
|
|
linkTitle: Events
|
|
--->
|
|
|
|
# Semantic conventions for mobile events
|
|
|
|
**Status**: [Development][DocumentStatus]
|
|
|
|
This document defines semantic conventions for instrumentations that emit
|
|
events on mobile platforms. All mobile events MUST use a namespace of
|
|
`device` in the EventName LogRecord property.
|
|
|
|
<!-- toc -->
|
|
|
|
- [Lifecycle instrumentation](#lifecycle-instrumentation)
|
|
- [Device app lifecycle event](#device-app-lifecycle-event)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## Lifecycle instrumentation
|
|
|
|
This section defines how to apply semantic conventions when instrumenting
|
|
application lifecycle.
|
|
|
|
### Device app lifecycle event
|
|
|
|
<!-- semconv event.device.app.lifecycle -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
**Status:** 
|
|
|
|
The event name MUST be `device.app.lifecycle`.
|
|
|
|
This event represents an occurrence of a lifecycle transition on Android or iOS platform.
|
|
|
|
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.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.
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`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` |  |
|
|
| [`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` |  |
|
|
|
|
**[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] `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.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. |  |
|
|
| `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. |  |
|
|
| `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.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`. |  |
|
|
| `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`. |  |
|
|
| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. |  |
|
|
| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. |  |
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|