added mobile instrumentation to log-event semantic conventions (#67)

Co-authored-by: jason plumb <75337021+breedx-splk@users.noreply.github.com> Co-authored-by: Alexander Wert <AlexanderWert@users.noreply.github.com>
open-telemetry · Oct 20, 2023 · e029787 · e029787
1 parent 86f1ba4
commit e029787
Show file tree

Hide file tree

Showing 3 changed files with 154 additions and 0 deletions.
diff --git a/docs/mobile/README.md b/docs/mobile/README.md
@@ -0,0 +1,18 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: mobile
+path_base_for_github_subdir:
+  from: content/en/docs/specs/semconv/mobile/_index.md
+  to: mobile/README.md
+--->
+
+# Semantic Convention for Mobile Platform
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for mobile platform spans, metrics and logs.
+
+Semantic conventions for the mobile platform are defined for the following signals:
+
+* [Mobile Events](events.md) : Semantic Conventions for mobile events in *logs*.
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
diff --git a/docs/mobile/events.md b/docs/mobile/events.md
@@ -0,0 +1,63 @@
+# Semantic Conventions for mobile events
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for instrumentations that emit events on mobile platforms.
+All mobile events MUST set `event.domain` as `device`.
+
+<!-- toc -->
+
+- [Lifecycle instrumentation](#lifecycle-instrumentation)
+  * [iOS](#ios)
+  * [Android](#android)
+
+<!-- tocstop -->
+
+## 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](/docs/resource/os.md) to identify the mobile operating system (e.g. Android, iOS).
+
+### iOS
+
+<!-- semconv ios.lifecycle.events -->
+The event name MUST be `app.lifecycle`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `active` | Required |
+
+**[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` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `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`. |
+<!-- endsemconv -->
+
+### Android
+
+<!-- semconv android.lifecycle.events -->
+The event name MUST be `app.lifecycle`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | Required |
+
+**[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.
+
+`android.state` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `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. |
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
diff --git a/model/logs/mobile-events.yaml b/model/logs/mobile-events.yaml
@@ -0,0 +1,73 @@
+groups:
+  - id: ios.lifecycle.events
+    type: event
+    prefix: ios
+    name: app.lifecycle
+    brief: >
+      This event represents an occurrence of a lifecycle transition on the iOS platform. `event.domain` MUST be `device`.
+    attributes:
+      - id: state
+        requirement_level: "required"
+        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.lifecycle.events
+    type: event
+    prefix: android
+    name: app.lifecycle
+    brief: >
+      This event represents an occurrence of a lifecycle transition on the Android platform.
+      `event.domain` MUST be `device`.
+    attributes:
+      - id: state
+        requirement_level: required
+        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.