Add browser events and describe their payload

CHANGELOG.md

@@ -8,6 +8,8 @@
 <!-- next version -->
 ## Unreleased
 
+- Add browser events and describe their payload [#838](https://github.com/open-telemetry/semantic-conventions/pull/838)
+
 ### Breaking
 
 ### Features

docs/browser/events.md

@@ -0,0 +1,161 @@
+# Semantic conventions for browser events
+
+**Status**: [Experimental](../../../document-status.md)
+
+<details>
+<summary>Table of Contents</summary>
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [PageView](#pageview)
+- [PageNavigationTiming](#pagenavigationtiming)
+- [ResourceTiming](#resourcetiming)
+- [Exception](#exception)
+- [UserAction](#useraction)
+- [WebVital](#webvital)
+
+<!-- tocstop -->
+
+</details>
+
+This document describes the semantic conventions for events on browser platform. All browser events MUST use a namespace of `browser` in the `event.name` property.
+
+## PageView
+
+The event name MUST be `browser.page_view`.
+
+This event describes the details of the web page visited.
+
+The following table describes the payload fields that MUST be used to describe the details of event.
+
+| Body Field  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `referrer` | string | Referring Page URI (`document.referrer`) whenever available. | `https://en.wikipedia.org/wiki/Main_Page` | Recommended |
+| `type` | int | Browser page type | `0` | Required |
+| `title` | string | Page title DOM property | `Shopping cart page` | Recommended |
+| `url` [1] | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [2] | `https://en.wikipedia.org/wiki/Main_Page`; `https://en.wikipedia.org/wiki/Main_Page#foo` | Required |
+| `changeState` | string | Type of state change used for the virtual page navigation | `pushState`, `replaceState` | Recommended |
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`session.id`](../attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |
+
+**[1]:** Alias for [`http.url`](../../../trace/semantic_conventions/http.md)
+**[2]:** The URL fragment may be included for virtual pages
+
+`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 |
+|---|---|
+| `0` | physical_page - Initial page load within the browser and will generally also precede a PageNavigationTiming event.|
+| `1` | virtual_page - This is for Single Page Applications (SPA) where the framework provides the ability to perform client side only page "navigation", the exact definition of what a virtual page change is determined by the SPA and the framework it is using.|
+
+## PageNavigationTiming
+
+The event name MUST be `browser.page_navigation_timing`.
+
+This event describes the timing metrics of a page navigation as provided by
+[PerformanceNavigationTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) Performance API.
+
+The following table describes the payload fields that MUST be used to describe the details of event.
+
+| Body Field  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| name | string | URL of the page || Recommended |
+| fetchStart | long | || Recommended |
+| unloadEventStart | long | || Recommended |
+| unloadEventEnd | long | || Recommended |
+| domInteractive | long | || Recommended |
+| domContentLoadedEventStart | long | || Recommended |
+| domContentLoadedEventEnd | long | || Recommended |
+| domComplete | long | || Recommended |
+| loadEventStart | long | || Recommended |
+| loadEventEnd | long | || Recommended |
+| firstPaint | long | || Recommended |
+| firstContentfulPaint | long | || Recommended |
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`session.id`](../attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |
+
+## ResourceTiming
+
+The event name MUST be `browser.resource_timing`.
+
+This event describes the timing metrics as provided by [PerformanceResourceTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming)
+Performance API.  These metrics are related to fetching a resource, such as
+XMLHttpRequest, Fetch, sendBeacon APIs, SVG, image or script.
+
+The following table describes the payload fields that MUST be used to describe the details of event.
+
+| Body Field  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+|name | string | URL of the requested resource || Recommended |
+|fetchStart | long | || Recommended |
+|domainLookupStart | long | || Recommended |
+|domainLookupEnd | long | || Recommended |
+|connectStart | long | || Recommended |
+|secureConnectionStart | long | || Recommended |
+|connectEnd | long | || Recommended |
+|requestStart | long | || Recommended |
+|responseStart | long | || Recommended |
+|responseEnd | long | || Recommended |
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`session.id`](../attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |
+
+## UserAction
+
+The event name MUST be `browser.user_action`.
+
+This event describes actions performed by the user such as click, scroll, zoom, resize, etc.
+
+The following table describes the payload fields that MUST be used to describe the details of event.
+
+| Body Field  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `element` | string | Target element tag name (obtained via `event.target.tagName`) | `button` | Recommended |
+| `element_xpath` | string | Target element xpath | `//*[@id="testBtn"]` | Recommended |
+| `user_action_type` | string | Type of interaction. See enum [here](https://github.com/microsoft/ApplicationInsights-JS/blob/941ec2e4dbd017b8450f2b17c60088ead1e6c428/extensions/applicationinsights-clickanalytics-js/src/Enums.ts) for potential values we could add support for. | `click` | Required |
+| `click_coordinates` | string | Click coordinates captured as a string in the format {x}X{y}.  Eg. 345X23 | `345X23` | Recommended |
+| `tags` | string[] | Grab data from data-otel-* attributes in tree | `[data-otel-asd="value" -> asd attr w/ "value"]` | Recommended |
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`session.id`](../attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |
+
+`user_action_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 |
+|---|---|
+| `click` | click |
+
+## WebVital
+
+The event name MUST be `browser.web_vital`.
+
+This event describes the website performance metrics introduced by Google (See <https://web.dev/vitals/>).
+
+The following table describes the payload fields that MUST be used to describe the details of event.
+
+| Body Field  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `name` | string | name of the web vital | `CLS` | Required |
+| `value` | double | value of the web vital | `1.0`; `2.0` | Required |
+| `delta` | double | The delta between the current value and the last-reported value | `0.2` | Required |
+| `id` | string | A unique ID representing this particular metric instance | "v3-1677874579383-6381583661209" | Required |
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`session.id`](../attributes-registry/session.md) | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | `Opt-In` |
+
+`name` 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 |
+|---|---|
+| `CLS` | Cumulative Layout Shift |
+| `LCP` | Largest Contentful Paint |
+| `FID` | First Input Delay |
+| `INP` | Interation to Next Paint |