Semantic Conventions for mobile events

Status: Experimental

This document defines semantic conventions for instrumentations that emit events on mobile platforms. All mobile events MUST use a namespace of device in the event.name property.

Lifecycle instrumentation

This section defines how to apply semantic conventions when instrumenting application lifecycle. This event is meant to be used in conjunction with os.name resource semantic convention to identify the mobile operating system (e.g. Android, 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.

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

Event details

The event name MUST be device.app.lifecycle.

Body Field	Type	Description	Examples	Requirement Level	Stability
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
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

[1]: The Android lifecycle states are defined in Activity lifecycle callbacks, and from which the OS identifiers are derived.

[2]: The iOS lifecycle states are defined in the UIApplicationDelegate documentation, 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.
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.

ios.state MUST be one of the following:

Value	Description	Stability
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.