diff --git a/docs/browser/events.md b/docs/browser/events.md new file mode 100644 index 0000000000..31b931fc4b --- /dev/null +++ b/docs/browser/events.md @@ -0,0 +1,56 @@ + + +# Semantic conventions for browser events + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for browser (web) instrumentations +that emit events. + +## UserAction Event + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `browser.user_action`. + +This event describes actions performed by the user such as click, scroll, zoom, resize, etc. + +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `click_coordinates` | string | Click coordinates captured as a string in the format {x}X{y}. | `345X23` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `element` | string | Target element tag name and it is obtained via event.target.tagName. | `button` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `element_xpath` | string | Target element xpath | `//*[@id='testBtn']` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `tags` | string | Grab data from data-otel-* attributes in tree. | `id` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `user_action_type` | enum | Type of interaction. See enum [here](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts) for potential values we could add support for. | `cl` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +`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 | Stability | +|---|---|---| +| `cl` | An element is left clicked by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `cm` | An element is middle clicked by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `cr` | An element is right clicked by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `ke` | An element is entered via keyboard by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `ks` | A space is entered via keyboard by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `o` | User actions that are not listed above. | ![Development](https://img.shields.io/badge/-development-blue) | +| `r` | An element is resized by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `s` | An element is scrolled by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `z` | An element is zoomed by a user. | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/browser/events.yaml b/model/browser/events.yaml new file mode 100644 index 0000000000..846fc7757f --- /dev/null +++ b/model/browser/events.yaml @@ -0,0 +1,82 @@ +groups: + - id: event.browser.user_action + stability: development + type: event + name: browser.user_action + brief: > + This event describes actions performed by the user such as click, scroll, zoom, resize, etc. + body: + id: browser.user_action + requirement_level: required + stability: development + type: map + fields: + - id: element + type: string + stability: development + brief: Target element tag name and it is obtained via event.target.tagName. + requirement_level: recommended + examples: ["button"] + - id: element_xpath + type: string + stability: development + brief: Target element xpath + requirement_level: recommended + examples: ["//*[@id='testBtn']"] + - id: user_action_type + type: enum + members: + - id: clickleft + value: "cl" + stability: development + brief: An element is left clicked by a user. + - id: clickright + value: "cr" + stability: development + brief: An element is right clicked by a user. + - id: clickmiddle + value: "cm" + stability: development + brief: An element is middle clicked by a user. + - id: scroll + value: "s" + stability: development + brief: An element is scrolled by a user. + - id: zoom + value: "z" + stability: development + brief: An element is zoomed by a user. + - id: resize + value: "r" + stability: development + brief: An element is resized by a user. + - id: keyboardenter + value: "ke" + stability: development + brief: An element is entered via keyboard by a user. + - id: keyboardspace + value: "ks" + stability: development + brief: A space is entered via keyboard by a user. + - id: other + value: "o" + stability: development + brief: User actions that are not listed above. + stability: development + brief: > + Type of interaction. + See enum [here](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts) for potential values we could add support for. + requirement_level: required + examples: ["cl"] + - id: click_coordinates + type: string + stability: development + brief: Click coordinates captured as a string in the format {x}X{y}. + requirement_level: recommended + examples: ["345X23"] + - id: tags + type: string + stability: development + brief: Grab data from data-otel-* attributes in tree. + requirement_level: recommended + examples: ["id"]