diff --git a/.chloggen/browser_user_action.yaml b/.chloggen/browser_user_action.yaml new file mode 100644 index 0000000000..3f20fa6d47 --- /dev/null +++ b/.chloggen/browser_user_action.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: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: browser + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add `browser.user_action` event. + +# 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: [1941] + +# (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: diff --git a/docs/browser/events.md b/docs/browser/events.md index c1aec9abb0..986433508c 100644 --- a/docs/browser/events.md +++ b/docs/browser/events.md @@ -51,4 +51,53 @@ semantic convention tooling supports complex attributes +## 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:** + +:warning: Body fields will be moved to complex attributes once the +semantic convention tooling supports complex attributes +(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)). + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `page.x` | int | Click x(horizontal) coordinates(in pixels) relative to the entire document. | `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `page.y` | int | Click y(vertical) coordinates(in pixels) relative to the entire document. | `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `tag_name` | string | Target element tag name and it is obtained via `event.target.tagName`. | `BUTTON` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `tags` | string[] | Grab data from data-otel-* attributes in tree. | `["id", "name"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `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. | `click.right` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `xpath` | string | Target element xpath by using [XPathExpression](https://developer.mozilla.org/en-US/docs/Web/API/XPathExpression). see [xpath](https://www.w3.org/TR/xpath/). | `//*[@id='testBtn']` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +`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 | +|---|---|---| +| `click.left` | An element is left clicked by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `click.middle` | An element is middle clicked by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `click.right` | An element is right clicked by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `keyboard.enter` | An element is entered via keyboard by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `keyboard.space` | A space is entered via keyboard by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `other` | User actions that are not listed above. | ![Development](https://img.shields.io/badge/-development-blue) | +| `resize` | An element is resized by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `scroll` | An element is scrolled by a user. | ![Development](https://img.shields.io/badge/-development-blue) | +| `zoom` | 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 index 00fedf7ee2..461ec8fd9e 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -52,3 +52,95 @@ groups: brief: A unique ID representing this particular metric instance. requirement_level: required examples: ["v3-1677874579383-6381583661209"] + - 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: tag_name + type: string + stability: development + brief: Target element tag name and it is obtained via `event.target.tagName`. + requirement_level: recommended + examples: ["BUTTON"] + - id: xpath + type: string + stability: development + brief: > + Target element xpath by using [XPathExpression](https://developer.mozilla.org/en-US/docs/Web/API/XPathExpression). + see [xpath](https://www.w3.org/TR/xpath/). + requirement_level: recommended + examples: ["//*[@id='testBtn']"] + - id: type + type: enum + members: + - id: click.left + value: "click.left" + stability: development + brief: An element is left clicked by a user. + - id: click.right + value: "click.right" + stability: development + brief: An element is right clicked by a user. + - id: click.middle + value: "click.middle" + stability: development + brief: An element is middle clicked by a user. + - id: scroll + value: "scroll" + stability: development + brief: An element is scrolled by a user. + - id: zoom + value: "zoom" + stability: development + brief: An element is zoomed by a user. + - id: resize + value: "resize" + stability: development + brief: An element is resized by a user. + - id: keyboard.enter + value: "keyboard.enter" + stability: development + brief: An element is entered via keyboard by a user. + - id: keyboard.space + value: "keyboard.space" + stability: development + brief: A space is entered via keyboard by a user. + - id: other + value: "other" + 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: ["click.right"] + - id: page.x + type: int + stability: development + brief: Click x(horizontal) coordinates(in pixels) relative to the entire document. + requirement_level: recommended + examples: + - 10 + - id: page.y + type: int + stability: development + brief: Click y(vertical) coordinates(in pixels) relative to the entire document. + requirement_level: recommended + examples: + - 10 + - id: tags + type: string[] + stability: development + brief: Grab data from data-otel-* attributes in tree. + requirement_level: recommended + examples: + - ["id", "name"]