Semantic conventions for browser events #30
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,211 @@ | ||
| # 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 --> | ||
|
|
||
| - [Events](#events) | ||
| * [PageView](#pageview) | ||
| * [PageNavigationTiming](#pagenavigationtiming) | ||
| * [ResourceTiming](#resourcetiming) | ||
| * [Exception](#exception) | ||
| * [UserAction](#useraction) | ||
| * [WebVital](#webvital) | ||
|
|
||
| <!-- tocstop --> | ||
|
|
||
| </details> | ||
|
|
||
| This document describes the semantic conventions for browser events. | ||
|
|
||
| ## Events | ||
|
|
||
| The events may be represented either as Span Events or Log Events. | ||
|
|
||
| All events have the following three high-level attributes. The event name is specified at the beginning of each section below. The payload of the event goes in an attribute called `event.data` of whose value is of type `map`. The contents of the `event.data` map for each event is listed in the sections below. | ||
|
|
||
| | Key | Type | Description | Examples | Requirement Level | | ||
| |---|---|---|---|---| | ||
| | `event.domain` | string | Fixed value: browser ||Required| | ||
| | `event.name` | string | Described in each section below||Required| | ||
| | `event.data` | map | A map of key/value pairs, with the keys for each event described in following sections||Recommended| | ||
|
|
||
| ### PageView | ||
|
|
||
| **Event name**: `page_view`. | ||
|
|
||
| | Attribute | 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 | | ||
|
|
||
| **[1]:** Alias for [`http.url`](../../../trace/semantic_conventions/http.md) | ||
| **[2]:** The URL fragment may be included for virtual pages | ||
|
|
||
| `type` MUST be one of the following: | ||
|
|
||
| | 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.| | ||
|
|
||
|
There was a problem hiding this comment. Should we have an attribute to show the change in state that happened on soft navigation (virtual pages) like pushState and replaceState. Name can be changeState |
||
| <details> | ||
| <summary>Sample PageView Event</summary> | ||
|
|
||
| ```json | ||
| "log_record": { | ||
| "timeUnixNano":"1581452773000000789", | ||
| "attributes": [ | ||
| { | ||
| "key": "event.domain", | ||
| "value": { | ||
| "stringValue": "browser" | ||
| } | ||
| }, | ||
| { | ||
| "key": "event.name", | ||
| "value": { | ||
| "stringValue": "page_view" | ||
| } | ||
| }, | ||
|
|
||
| { | ||
| "key": "event.data", | ||
| "value": { | ||
| "kvlistValue": [ | ||
| { | ||
| "key": "type", | ||
| "value": { | ||
| "intValue": "0" | ||
| } | ||
| }, | ||
| { | ||
| "key": "url", | ||
| "value": { | ||
| "stringValue": "https://www.guidgenerator.com/online-guid-generator.aspx" | ||
| } | ||
| }, | ||
| { | ||
| "key": "referrer", | ||
| "value": { | ||
| "stringValue": "https://wwww.google.com" | ||
| } | ||
| }, | ||
| { | ||
| "key": "title", | ||
| "value": { | ||
| "stringValue": "Free Online GUID Generator" | ||
| } | ||
| }, | ||
| ] | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ### PageNavigationTiming | ||
|
|
||
| **Event name**:`page_navigation_timing` | ||
|
|
||
| This event describes the timing metrics of a page navigation as provided by | ||
| `PerformanceNavigationTiming` Performance API. | ||
|
There was a problem hiding this comment. Does this include the page that is loading somewhere? There was a problem hiding this comment. Added |
||
|
|
||
| | Key | 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 | | ||
|
|
||
| ### ResourceTiming | ||
|
|
||
| **Event name**:`resource_timing` | ||
|
There was a problem hiding this comment. Shouldn't this include an attribute denoting the resource that was fetched? There was a problem hiding this comment. Added |
||
|
|
||
| This event describes the timing metrics as provided by `PerformanceResourceTiming` | ||
| Performance API. These metrics are related to fetching a resource, such as | ||
| XMLHttpRequest, Fetch, sendBeacon APIs, SVG, image or script. | ||
|
|
||
| | Key | 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 | | ||
|
|
||
| ### Exception | ||
|
|
||
| **Event name**:`exception` | ||
|
There was a problem hiding this comment. Why is this redefined? Shouldn't this just leverage existing exception specification, e.g. https://github.com/open-telemetry/semantic-conventions/blob/main/specification/logs/semantic_conventions/exceptions.md |
||
|
|
||
| | Attribute | Type | Description | Examples | Requirement Level | | ||
| |---|---|---|---|---| | ||
| | `exception.file_name` | string | Name of the file that generated the error | `foo.js` | Recommended | | ||
| | `exception.line_number` | int | Line number where the error occurred | | Recommended | | ||
| | `exception.column_number` | int | Column number where the error occurred | | Recommended | | ||
| | `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | Recommended | | ||
| | `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended | | ||
| | `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | Recommended | | ||
|
|
||
| ### UserAction | ||
|
|
||
| **Event name**:`user_action` | ||
|
There was a problem hiding this comment. Can you outline in more detail what user actions should be captured? There was a problem hiding this comment. Added a few user actions captured using this Event. |
||
|
|
||
| This event describes actions performed by the user such as click, scroll, zoom, resize, etc. | ||
|
|
||
| | Attribute | 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 | | ||
|
|
||
| `user_action_type` MUST be one of the following: | ||
|
|
||
| | Value | Description | | ||
| |---|---| | ||
| | `click` | click | | ||
|
|
||
| ### WebVital | ||
|
|
||
| **Event name**:`web_vital` | ||
|
There was a problem hiding this comment. Can you outline in more detail what this is? There was a problem hiding this comment. Added a short description for this event type. |
||
|
|
||
| This event describes the website performance metrics introduced by Google (See <https://web.dev/vitals/>). | ||
|
|
||
| | Attribute | 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 | | ||
|
|
||
| `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 | | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should make use of semantic conventions YAML definitions for attributes, where possible.