feat: Add spans for app start, time to first draw, time on screen

.chloggen/feat_app-spans.yaml

@@ -0,0 +1,22 @@
+# 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: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: app
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add spans for app start, time to first draw, time on screen
+
+# 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: [2830]
+
+# (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:

docs/app/app-spans.md

@@ -0,0 +1,172 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: App spans
+--->
+
+# Semantic conventions for app spans
+
+**Status**: [Development][DocumentStatus]
+
+<!-- toc -->
+
+- [Time to first draw span](#time-to-first-draw-span)
+- [Time on screen span](#time-on-screen-span)
+- [App start span](#app-start-span)
+
+<!-- tocstop -->
+
+## Time to first draw span
+
+<!-- semconv span.app.screen.time_to_first_draw.internal -->
+<!-- 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:** ![Development](https://img.shields.io/badge/-development-blue)
+
+This span represents an application screen first draw operation.
+
+**Span name**: MUST be `app.screen.time_to_first_draw`.
+
+**Span kind** MUST be `INTERNAL`.
+
+This span captures the time from screen initialization to the first frame
+of an application UI screen being drawn.
+
+**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`app.screen.time_to_first_draw.duration`](/docs/registry/attributes/app.md) | double | The time, in seconds, from screen initialization to the first frame being rendered. [1] | `0.95`; `2.0` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.id`](/docs/registry/attributes/app.md) | string | An identifier that uniquely differentiates this screen from other screens in the same application. [2] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `com.example.app.MainActivity`; `com.example.shop.ProductDetailFragment`; `MyApp.ProfileView`; `MyApp.ProfileViewController` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.name`](/docs/registry/attributes/app.md) | string | The name of an application screen. [3] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.type`](/docs/registry/attributes/app.md) | string | The type of UI management component or framework used to render and manage the screen's presentation and interactions. [4] | `swiftui`; `uikit`; `activity`; `fragment` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `app.screen.time_to_first_draw.duration`:** This measures the time, in seconds, until the first frame of the screen is rendered and becomes visible to the user.
+
+**[2] `app.screen.id`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
+
+**[3] `app.screen.name`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
+
+**[4] `app.screen.type`:** This attribute indicates which framework or structure is used to manage and display the screen’s content. For iOS, it may refer to either SwiftUI (declarative) or UIKit (imperative) for managing views. On Android, it can refer to either an Activity or a Fragment.
+
+---
+
+`app.screen.type` 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 |
+|---|---|---|
+| `activity` | Android Activity (Android) | ![Development](https://img.shields.io/badge/-development-blue) |
+| `fragment` | Android Fragment (Android) | ![Development](https://img.shields.io/badge/-development-blue) |
+| `swiftui` | SwiftUI View (iOS) | ![Development](https://img.shields.io/badge/-development-blue) |
+| `uikit` | UIKit ViewController (iOS) | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## Time on screen span
+
+<!-- semconv span.app.screen.time_on_screen.internal -->
+<!-- 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:** ![Development](https://img.shields.io/badge/-development-blue)
+
+This span_kind captures the duration that a screen was visible to the user, indicating the time between when the screen becomes visible and when it stops being visible.
+
+**Span name:** MUST be `app.screen.time_on_screen`.
+
+**Span kind** MUST be `INTERNAL`.
+
+This span captures the screen's visibility, in seconds, meaning it includes only the time the screen is actively being shown to the user.
+It does not include times when the app is in the background or when other screens/modal views are covering it. For example:
+- **iOS**: From `viewDidAppear` to `viewWillDisappear`, indicating when the screen is first shown and when it's about to disappear.
+- **Android**: From `onResume` to `onPause`, indicating when the screen comes to the foreground and when it goes to the background.
+
+**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`app.screen.time_on_screen.duration`](/docs/registry/attributes/app.md) | double | The total time, in seconds, that the screen remained visible to the user. [1] | `30.0`; `10.21` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.id`](/docs/registry/attributes/app.md) | string | An identifier that uniquely differentiates this screen from other screens in the same application. [2] | `f9bc787d-ff05-48ad-90e1-fca1d46130b3`; `com.example.app.MainActivity`; `com.example.shop.ProductDetailFragment`; `MyApp.ProfileView`; `MyApp.ProfileViewController` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.name`](/docs/registry/attributes/app.md) | string | The name of an application screen. [3] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.type`](/docs/registry/attributes/app.md) | string | The type of UI management component or framework used to render and manage the screen's presentation and interactions. [4] | `swiftui`; `uikit`; `activity`; `fragment` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `app.screen.time_on_screen.duration`:** This attribute measures the duration during which the screen is visible and actively being displayed to the user. It begins when the screen becomes visible (e.g., `viewDidAppear` on iOS or `onResume` on Android) and ends when it is no longer visible (e.g., `viewWillDisappear` on iOS or `onPause` on Android). It does **not** include the time when the screen is in the background, nor does it account for time the screen may be obscured by other views or overlays (e.g., modals, popups, or other screens in split-view).
+
+**[2] `app.screen.id`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
+
+**[3] `app.screen.name`:** A screen represents only the part of the device display drawn by the app. It typically contains multiple widgets or UI components and is larger in scope than individual widgets. Multiple screens can coexist on the same display simultaneously (e.g., split view on tablets).
+
+**[4] `app.screen.type`:** This attribute indicates which framework or structure is used to manage and display the screen’s content. For iOS, it may refer to either SwiftUI (declarative) or UIKit (imperative) for managing views. On Android, it can refer to either an Activity or a Fragment.
+
+---
+
+`app.screen.type` 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 |
+|---|---|---|
+| `activity` | Android Activity (Android) | ![Development](https://img.shields.io/badge/-development-blue) |
+| `fragment` | Android Fragment (Android) | ![Development](https://img.shields.io/badge/-development-blue) |
+| `swiftui` | SwiftUI View (iOS) | ![Development](https://img.shields.io/badge/-development-blue) |
+| `uikit` | UIKit ViewController (iOS) | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## App start span
+
+<!-- semconv span.app.start.internal -->
+<!-- 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:** ![Development](https://img.shields.io/badge/-development-blue)
+
+This span represents an application start operation.
+
+**Span name:** MUST be `app.start`.
+
+**Span kind** MUST be `INTERNAL`.
+
+This span captures the time from user initiation (e.g., tapping the app icon or opening a link)
+to the moment the app begins UI rendering.
+
+**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`app.start.duration`](/docs/registry/attributes/app.md) | double | The total time, in seconds, taken for the application to start, from user initiation to being ready for interaction. [1] | `0.95`; `2.0` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.start.type`](/docs/registry/attributes/app.md) | string | The type of application start, indicating the state of the app when it was initiated. | `cold`; `warm` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `app.start.duration`:** This is the time, in seconds, between the user's initiation of the app start (e.g., tapping the app icon or opening a link) and the point when the app is fully ready for interaction, such as the main screen becoming visible or the app’s main functionality being accessible.
+
+---
+
+`app.start.type` 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 |
+|---|---|---|
+| `cold` | App start from terminated state [2] | ![Development](https://img.shields.io/badge/-development-blue) |
+| `warm` | App start from background state [3] | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[2]:** The app is started from a terminated state, meaning no prior instance of the app is running.
+
+**[3]:** The app is started from the background, meaning an instance of the app is still in memory, but not active.
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status