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, app screen load, app time to first draw
+
+# 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-events.md

@@ -16,6 +16,7 @@ This document defines events related to client-side applications
   - [Event: `app.widget.click`](#event-appwidgetclick)
 - [Jank Event](#jank-event)
   - [Event: `app.jank`](#event-appjank)
+- [Event: `app.screen.visible`](#event-appscreenvisible)
 - [Attributes](#attributes)
 
 <!-- tocstop -->
@@ -130,6 +131,51 @@ Jank happens when the UI is rendered slowly enough for the user to experience so
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
+## Event: `app.screen.visible`
+
+<!-- semconv event.app.screen.visible -->
+<!-- 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)
+
+The event name MUST be `app.screen.visible`.
+
+This event 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.
+
+This event measures the screen's visibility, in nanoseconds, 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.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`app.screen.name`](/docs/registry/attributes/app.md) | string | The name of an application screen. [1] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.visible.duration`](/docs/registry/attributes/app.md) | int | The total time, in nanoseconds, that the screen remained visible to the user. [2] | `1200`; `5500`; `700` | `Required` | ![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. [3] | `swiftui`; `uikit`; `activity`; `fragment` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `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).
+
+**[2] `app.screen.visible.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).
+
+**[3] `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 -->
+
 ## Attributes
 
 See the [app attributes](/docs/registry/attributes/app.md) registry for all

docs/app/app-spans.md

@@ -0,0 +1,165 @@
+<!--- 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)
+- [Screen load span](#screen-load-span)
+- [App start span](#app-start-span)
+
+<!-- tocstop -->
+
+## Time to first draw span
+
+<!-- semconv span.app.screen.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 describes the time until the first draw of an application UI screen.
+
+**Span name**: MUST be `app.screen.first_draw`.
+
+This span captures the time from screen initialization to the first frame drawn.
+
+**Span kind** SHOULD be `INTERNAL`.
+
+**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.first_draw.duration`](/docs/registry/attributes/app.md) | int | The time, in nanoseconds, from screen initialization to the first frame being rendered. [1] | `1000` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.name`](/docs/registry/attributes/app.md) | string | The name of an application screen. [2] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` | `Required` | ![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. [3] | `swiftui`; `uikit`; `activity`; `fragment` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `app.screen.first_draw.duration`:** This measures the time, in nanoseconds, until the first frame of the screen is rendered and becomes visible to the user.
+
+**[2] `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).
+
+**[3] `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 -->
+
+## Screen load span
+
+<!-- semconv span.app.screen.load.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 describes an application screen load operation, from navigation trigger to when the first stable frame has been rendered.
+
+**Span name:** MUST be `app.screen.load`.
+
+This span captures the time from user initiation of naigation (e.g., tapping a button) to the point when the first stable frame
+of the screen has been rendered. A frame is considered stable when no major layout or frame changes occur for a brief stability
+interval (e.g. 150 ms).
+
+**Span kind** SHOULD be `INTERNAL`.
+
+**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.load.duration`](/docs/registry/attributes/app.md) | int | The time taken, in nanoseconds, for a screen to load and become stable, measured from when the screen begins appearing until the first stable frame has been rendered. [1] | `1000` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+| [`app.screen.name`](/docs/registry/attributes/app.md) | string | The name of an application screen. [2] | `MainActivity`; `ProductDetailFragment`; `ProfileView`; `ProfileViewController` | `Required` | ![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. [3] | `swiftui`; `uikit`; `activity`; `fragment` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `app.screen.load.duration`:** This attribute represents the total duration, in nanoseconds, of a screen load as experienced by the user. The screen load is considered complete when the first stable frame of the screen has been rendered. A frame is considered stable when no major layout or frame changes occur for a brief stability interval (e.g. 150 ms).
+
+**[2] `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).
+
+**[3] `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.client -->
+<!-- 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 `AppStart`.
+
+**Span kind** MUST be `CLIENT`.
+
+This span captures the time from user initiation (e.g., tapping the app icon or opening a link)
+to the moment the app is ready for interaction.
+
+**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) | int | The total time, in nanoseconds, taken for the application to start, from user initiation to being ready for interaction. [1] | `1000` | `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. [2] | `cold`; `warm` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1] `app.start.duration`:** This is the time, in nanoseconds, 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.
+
+**[2] `app.start.type`:** Start types include:
+
+- **Cold**: The app is started from a terminated state, meaning no prior instance of the app is running.
+- **Warm**: The app is started from the background, meaning an instance of the app is still in memory, but not active.
+
+---
+
+`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 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `warm` | App start from background state | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status