From cee548967f874b648bbc2bb879a825d13676c9cc Mon Sep 17 00:00:00 2001 From: joaquin-diaz Date: Tue, 28 Oct 2025 11:03:13 -0300 Subject: [PATCH 1/8] feat: Add Browser UserAction Event --- ...aquin-diaz_feat_add-user-action-event.yaml | 22 ++++++++++ docs/browser/browser-events.md | 44 +++++++++++++++++++ docs/registry/attributes/browser.md | 43 +++++++++++++----- model/browser/events.yaml | 44 +++++++++++++++++++ model/browser/registry.yaml | 37 ++++++++++++++++ 5 files changed, 180 insertions(+), 10 deletions(-) create mode 100644 .chloggen/joaquin-diaz_feat_add-user-action-event.yaml diff --git a/.chloggen/joaquin-diaz_feat_add-user-action-event.yaml b/.chloggen/joaquin-diaz_feat_add-user-action-event.yaml new file mode 100644 index 0000000000..9c90ca4423 --- /dev/null +++ b/.chloggen/joaquin-diaz_feat_add-user-action-event.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: browser + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add `event.browser.user_action` to capture user action events in the browser + +# 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: [] + +# (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/browser-events.md b/docs/browser/browser-events.md index c25a76fd3d..59e2364e7b 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -51,4 +51,48 @@ semantic convention tooling supports complex attributes + + + + + + + +**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. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|----------------------------------------------------------------------|---|---|---|---|---| +| [`browser.element.attributes`](/docs/registry/attributes/browser.md) | string | JSON-serialized map of data-otel-* attributes from the target element. [1] | `{"id": "123", "name": "Name"}` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`browser.page.x`](/docs/registry/attributes/browser.md) | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`browser.page.y`](/docs/registry/attributes/browser.md) | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`browser.tag_name`](/docs/registry/attributes/browser.md) | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`browser.user_action.type`](/docs/registry/attributes/browser.md) | string | Type of user interaction. [2] | `click.right` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`browser.xpath`](/docs/registry/attributes/browser.md) | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `browser.element.attributes`:** Represented as a JSON object string. Example: {"id": "123", "name": "Name"}. Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. + +**[2] `browser.user_action.type`:** Possible values inspired by [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). + +`browser.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 | +|------------------|----------------------------------------------------------|---| +| `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) | +| `input` | An element is registers an input via keyboard by a user. | ![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) | +| `other` | User actions that are not listed above. | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/registry/attributes/browser.md b/docs/registry/attributes/browser.md index cc8d235f4e..9e02759a8c 100644 --- a/docs/registry/attributes/browser.md +++ b/docs/registry/attributes/browser.md @@ -7,20 +7,43 @@ The web browser attributes -**Attributes:** - -| Key | Stability | Value Type | Description | Example Values | +| Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `browser.brands` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | Array of brand name and version separated by a space [1] | `[" Not A;Brand 99", "Chromium 99", "Chrome 99"]` | -| `browser.language` | ![Development](https://img.shields.io/badge/-development-blue) | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | -| `browser.mobile` | ![Development](https://img.shields.io/badge/-development-blue) | boolean | A boolean that is true if the browser is running on a mobile device [3] | | -| `browser.platform` | ![Development](https://img.shields.io/badge/-development-blue) | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | +| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[" Not A;Brand 99", "Chromium 99", "Chrome 99"]` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.element.attributes` | string | JSON-serialized map of data-otel-* attributes from the target element. [2] | `{"id": "123", "name": "Name"}` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.language` | string | Preferred language of the user using the browser [3] | `en`; `en-US`; `fr`; `fr-FR` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [4] | | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.page.x` | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.page.y` | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.platform` | string | The platform on which the browser is running [5] | `Windows`; `macOS`; `Android` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.tag_name` | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.user_action.type` | string | Type of user interaction. [6] | `click.right` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.xpath` | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `browser.brands`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). -**[2] `browser.language`:** This value is intended to be taken from the Navigator API `navigator.language`. +**[2] `browser.element.attributes`:** Represented as a JSON object string. Example: {"id": "123", "name": "Name"}. Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. + +**[3] `browser.language`:** This value is intended to be taken from the Navigator API `navigator.language`. -**[3] `browser.mobile`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. +**[4] `browser.mobile`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. -**[4] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. +**[5] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. + +**[6] `browser.user_action.type`:** Possible values inspired by [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). + +--- + +`browser.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 | +|------------------|----------------------------------------------------------|---| +| `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) | +| `input` | An element is registers an input via keyboard by a user. | ![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) | +| `other` | User actions that are not listed above. | ![Development](https://img.shields.io/badge/-development-blue) | \ No newline at end of file diff --git a/model/browser/events.yaml b/model/browser/events.yaml index 00fedf7ee2..789cdbfc24 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -52,3 +52,47 @@ 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. + attributes: + - id: browser.page.x + type: int + stability: development + brief: 'Click x (horizontal) coordinates (in pixels) relative to the entire document.' + examples: [10] + - id: browser.page.y + type: int + stability: development + brief: 'Click y (vertical) coordinates (in pixels) relative to the entire document.' + examples: [10] + - id: browser.tag_name + type: string + stability: development + brief: 'Target element tag name obtained via event.target.tagName.' + examples: ['BUTTON'] + - id: browser.element.attributes + type: string + stability: development + brief: 'JSON-serialized map of data-otel-* attributes from the target element.' + note: > + Represented as a JSON object string. Example: + {"id": "123", "name": "Name"}. + Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. + examples: ['{"id": "123", "name": "Name"}'] + - id: browser.user_action.type + type: string + stability: development + brief: 'Type of user interaction.' + note: > + Possible values inspired by + [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). + examples: ['click.right'] + - id: browser.xpath + type: string + stability: development + brief: 'Target element XPath using the XPathExpression API.' + examples: ["//*[@id='testBtn']"] diff --git a/model/browser/registry.yaml b/model/browser/registry.yaml index 040f2d6838..4718f3965e 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -50,3 +50,40 @@ groups: This value is intended to be taken from the Navigator API `navigator.language`. examples: ["en", "en-US", "fr", "fr-FR"] + - id: browser.page.x + type: int + stability: development + brief: 'Click x (horizontal) coordinates (in pixels) relative to the entire document.' + examples: [10] + - id: browser.page.y + type: int + stability: development + brief: 'Click y (vertical) coordinates (in pixels) relative to the entire document.' + examples: [10] + - id: browser.tag_name + type: string + stability: development + brief: 'Target element tag name obtained via event.target.tagName.' + examples: ['BUTTON'] + - id: browser.element.attributes + type: string + stability: development + brief: 'JSON-serialized map of data-otel-* attributes from the target element.' + note: > + Represented as a JSON object string. Example: + {"id": "123", "name": "Name"}. + Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. + examples: ['{"id": "123", "name": "Name"}'] + - id: browser.user_action.type + type: string + stability: development + brief: 'Type of user interaction.' + note: > + Possible values inspired by + [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). + examples: ['click.right'] + - id: browser.xpath + type: string + stability: development + brief: 'Target element XPath using the XPathExpression API.' + examples: ["//*[@id='testBtn']"] From 42b43b6af21041672504a72a09f7307e4842c2bf Mon Sep 17 00:00:00 2001 From: joaquin-diaz Date: Tue, 28 Oct 2025 11:09:53 -0300 Subject: [PATCH 2/8] chore: set PR number in the issues field of the changelog entry --- .chloggen/joaquin-diaz_feat_add-user-action-event.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/joaquin-diaz_feat_add-user-action-event.yaml b/.chloggen/joaquin-diaz_feat_add-user-action-event.yaml index 9c90ca4423..31021e3449 100644 --- a/.chloggen/joaquin-diaz_feat_add-user-action-event.yaml +++ b/.chloggen/joaquin-diaz_feat_add-user-action-event.yaml @@ -14,7 +14,7 @@ note: Add `event.browser.user_action` to capture user action events in the brows # 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: [] +issues: [2992] # (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. From 9d78ec57322f8ad1db00d65acd6b6a4f6b14ccd5 Mon Sep 17 00:00:00 2001 From: joaquin-diaz Date: Tue, 28 Oct 2025 17:24:37 -0300 Subject: [PATCH 3/8] chore: convert generic event to click specific event --- docs/browser/browser-events.md | 43 +++++++++++----------- docs/registry/attributes/browser.md | 45 +++++++++++------------ model/browser/events.yaml | 55 ++++++++--------------------- model/browser/registry.yaml | 26 +++++++++----- 4 files changed, 73 insertions(+), 96 deletions(-) diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index 59e2364e7b..b2ec70ea81 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -51,7 +51,7 @@ semantic convention tooling supports complex attributes - + @@ -60,35 +60,32 @@ semantic convention tooling supports complex attributes **Status:** ![Development](https://img.shields.io/badge/-development-blue) -The event name MUST be `browser.user_action`. +The event name MUST be `browser.user_action.click`. -This event describes actions performed by the user such as click, scroll, zoom, resize, etc. +This event describes a user click action in the browser. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|----------------------------------------------------------------------|---|---|---|---|---| -| [`browser.element.attributes`](/docs/registry/attributes/browser.md) | string | JSON-serialized map of data-otel-* attributes from the target element. [1] | `{"id": "123", "name": "Name"}` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`browser.page.x`](/docs/registry/attributes/browser.md) | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`browser.page.y`](/docs/registry/attributes/browser.md) | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`browser.tag_name`](/docs/registry/attributes/browser.md) | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`browser.user_action.type`](/docs/registry/attributes/browser.md) | string | Type of user interaction. [2] | `click.right` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`browser.xpath`](/docs/registry/attributes/browser.md) | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +|---|---|---|---|---|---| +| [`browser.page.x`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | +| [`browser.page.y`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | +| [`browser.tag_name`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | +| [`browser.xpath`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | +| [`browser.element.attributes`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | JSON-serialized map of data-otel-* attributes from the target element. [1] | `{"id": "123", "name": "Name"}` | +| [`browser.mouse_event.button`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | **[1] `browser.element.attributes`:** Represented as a JSON object string. Example: {"id": "123", "name": "Name"}. Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. -**[2] `browser.user_action.type`:** Possible values inspired by [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). +--- -`browser.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. +`browser.mouse_event.button` 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) | -| `input` | An element is registers an input via keyboard by a user. | ![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) | -| `other` | User actions that are not listed above. | ![Development](https://img.shields.io/badge/-development-blue) | +| Value | Description | Stability | +|---|---|---| +| `left` | Left button | ![Development](https://img.shields.io/badge/-development-blue) | +| `middle` | Middle button | ![Development](https://img.shields.io/badge/-development-blue) | +| `right` | Right button | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/registry/attributes/browser.md b/docs/registry/attributes/browser.md index 9e02759a8c..1654a77fcf 100644 --- a/docs/registry/attributes/browser.md +++ b/docs/registry/attributes/browser.md @@ -7,18 +7,20 @@ The web browser attributes -| Attribute | Type | Description | Examples | Stability | +**Attributes:** + +| Key | Stability | Value Type | Description | Example Values | |---|---|---|---|---| -| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[" Not A;Brand 99", "Chromium 99", "Chrome 99"]` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.element.attributes` | string | JSON-serialized map of data-otel-* attributes from the target element. [2] | `{"id": "123", "name": "Name"}` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.language` | string | Preferred language of the user using the browser [3] | `en`; `en-US`; `fr`; `fr-FR` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [4] | | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.page.x` | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.page.y` | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.platform` | string | The platform on which the browser is running [5] | `Windows`; `macOS`; `Android` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.tag_name` | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.user_action.type` | string | Type of user interaction. [6] | `click.right` | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.xpath` | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.brands` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | Array of brand name and version separated by a space [1] | `[" Not A;Brand 99", "Chromium 99", "Chrome 99"]` | +| `browser.element.attributes` | ![Development](https://img.shields.io/badge/-development-blue) | string | JSON-serialized map of data-otel-* attributes from the target element. [2] | `{"id": "123", "name": "Name"}` | +| `browser.language` | ![Development](https://img.shields.io/badge/-development-blue) | string | Preferred language of the user using the browser [3] | `en`; `en-US`; `fr`; `fr-FR` | +| `browser.mobile` | ![Development](https://img.shields.io/badge/-development-blue) | boolean | A boolean that is true if the browser is running on a mobile device [4] | | +| `browser.mouse_event.button` | ![Development](https://img.shields.io/badge/-development-blue) | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | +| `browser.page.x` | ![Development](https://img.shields.io/badge/-development-blue) | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | +| `browser.page.y` | ![Development](https://img.shields.io/badge/-development-blue) | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | +| `browser.platform` | ![Development](https://img.shields.io/badge/-development-blue) | string | The platform on which the browser is running [5] | `Windows`; `macOS`; `Android` | +| `browser.tag_name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | +| `browser.xpath` | ![Development](https://img.shields.io/badge/-development-blue) | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | **[1] `browser.brands`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). @@ -31,19 +33,12 @@ The web browser attributes **[5] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. -**[6] `browser.user_action.type`:** Possible values inspired by [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). - --- -`browser.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 | -|------------------|----------------------------------------------------------|---| -| `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) | -| `input` | An element is registers an input via keyboard by a user. | ![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) | -| `other` | User actions that are not listed above. | ![Development](https://img.shields.io/badge/-development-blue) | \ No newline at end of file +`browser.mouse_event.button` 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 | +|---|---|---| +| `left` | Left button | ![Development](https://img.shields.io/badge/-development-blue) | +| `middle` | Middle button | ![Development](https://img.shields.io/badge/-development-blue) | +| `right` | Right button | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/browser/events.yaml b/model/browser/events.yaml index 789cdbfc24..9acd686e06 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -52,47 +52,22 @@ groups: brief: A unique ID representing this particular metric instance. requirement_level: required examples: ["v3-1677874579383-6381583661209"] - - id: event.browser.user_action + - id: event.browser.user_action.click stability: development type: event - name: browser.user_action + name: browser.user_action.click brief: > - This event describes actions performed by the user such as click, scroll, zoom, resize, etc. + This event describes a user click action in the browser. attributes: - - id: browser.page.x - type: int - stability: development - brief: 'Click x (horizontal) coordinates (in pixels) relative to the entire document.' - examples: [10] - - id: browser.page.y - type: int - stability: development - brief: 'Click y (vertical) coordinates (in pixels) relative to the entire document.' - examples: [10] - - id: browser.tag_name - type: string - stability: development - brief: 'Target element tag name obtained via event.target.tagName.' - examples: ['BUTTON'] - - id: browser.element.attributes - type: string - stability: development - brief: 'JSON-serialized map of data-otel-* attributes from the target element.' - note: > - Represented as a JSON object string. Example: - {"id": "123", "name": "Name"}. - Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. - examples: ['{"id": "123", "name": "Name"}'] - - id: browser.user_action.type - type: string - stability: development - brief: 'Type of user interaction.' - note: > - Possible values inspired by - [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). - examples: ['click.right'] - - id: browser.xpath - type: string - stability: development - brief: 'Target element XPath using the XPathExpression API.' - examples: ["//*[@id='testBtn']"] + - ref: browser.mouse_event.button + requirement_level: recommended + - ref: browser.page.x + requirement_level: required + - ref: browser.page.y + requirement_level: required + - ref: browser.tag_name + requirement_level: required + - ref: browser.xpath + requirement_level: required + - ref: browser.element.attributes + requirement_level: recommended diff --git a/model/browser/registry.yaml b/model/browser/registry.yaml index 4718f3965e..b1b5cd8a51 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -74,16 +74,26 @@ groups: {"id": "123", "name": "Name"}. Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. examples: ['{"id": "123", "name": "Name"}'] - - id: browser.user_action.type - type: string - stability: development - brief: 'Type of user interaction.' - note: > - Possible values inspired by - [ApplicationInsights Click Analytics Enums](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-clickanalytics-js/src/Enums.ts). - examples: ['click.right'] - id: browser.xpath type: string stability: development brief: 'Target element XPath using the XPathExpression API.' examples: ["//*[@id='testBtn']"] + - id: browser.mouse_event.button + type: + members: + - id: left + value: 'left' + brief: Left button + stability: development + - id: middle + value: 'middle' + brief: Middle button + stability: development + - id: right + value: 'right' + brief: Right button + stability: development + stability: development + brief: 'User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value).' + examples: ["left"] From 32555218ca02768ebb41df80ddc728703a2a7c11 Mon Sep 17 00:00:00 2001 From: Joaquin Diaz <32420835+joaquin-diaz@users.noreply.github.com> Date: Wed, 29 Oct 2025 10:45:34 -0300 Subject: [PATCH 4/8] Update docs/browser/browser-events.md Co-authored-by: James Thompson --- docs/browser/browser-events.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index b2ec70ea81..52c0dff907 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -51,6 +51,8 @@ semantic convention tooling supports complex attributes +## Event: `browser.user_action.click` + From 484680ac9ab7d2560fecd02c3abe26a23ebbf434 Mon Sep 17 00:00:00 2001 From: joaquin-diaz Date: Wed, 29 Oct 2025 10:55:29 -0300 Subject: [PATCH 5/8] chore: rename browser.mouse_event.button to hw.mouse.button --- docs/browser/browser-events.md | 4 ++-- docs/registry/attributes/browser.md | 4 ++-- model/browser/events.yaml | 2 +- model/browser/registry.yaml | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index 52c0dff907..e03096fdc1 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -75,13 +75,13 @@ This event describes a user click action in the browser. | [`browser.tag_name`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | | [`browser.xpath`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | | [`browser.element.attributes`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | JSON-serialized map of data-otel-* attributes from the target element. [1] | `{"id": "123", "name": "Name"}` | -| [`browser.mouse_event.button`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | +| [`hw.mouse.button`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | **[1] `browser.element.attributes`:** Represented as a JSON object string. Example: {"id": "123", "name": "Name"}. Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. --- -`browser.mouse_event.button` 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. +`hw.mouse.button` 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 | |---|---|---| diff --git a/docs/registry/attributes/browser.md b/docs/registry/attributes/browser.md index 1654a77fcf..e31374301b 100644 --- a/docs/registry/attributes/browser.md +++ b/docs/registry/attributes/browser.md @@ -15,12 +15,12 @@ The web browser attributes | `browser.element.attributes` | ![Development](https://img.shields.io/badge/-development-blue) | string | JSON-serialized map of data-otel-* attributes from the target element. [2] | `{"id": "123", "name": "Name"}` | | `browser.language` | ![Development](https://img.shields.io/badge/-development-blue) | string | Preferred language of the user using the browser [3] | `en`; `en-US`; `fr`; `fr-FR` | | `browser.mobile` | ![Development](https://img.shields.io/badge/-development-blue) | boolean | A boolean that is true if the browser is running on a mobile device [4] | | -| `browser.mouse_event.button` | ![Development](https://img.shields.io/badge/-development-blue) | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | | `browser.page.x` | ![Development](https://img.shields.io/badge/-development-blue) | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | | `browser.page.y` | ![Development](https://img.shields.io/badge/-development-blue) | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | | `browser.platform` | ![Development](https://img.shields.io/badge/-development-blue) | string | The platform on which the browser is running [5] | `Windows`; `macOS`; `Android` | | `browser.tag_name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | | `browser.xpath` | ![Development](https://img.shields.io/badge/-development-blue) | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | +| `hw.mouse.button` | ![Development](https://img.shields.io/badge/-development-blue) | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | **[1] `browser.brands`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). @@ -35,7 +35,7 @@ The list of possible values is defined in the [W3C User-Agent Client Hints speci --- -`browser.mouse_event.button` 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. +`hw.mouse.button` 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 | |---|---|---| diff --git a/model/browser/events.yaml b/model/browser/events.yaml index 9acd686e06..f448ec0dbc 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -59,7 +59,7 @@ groups: brief: > This event describes a user click action in the browser. attributes: - - ref: browser.mouse_event.button + - ref: hw.mouse.button requirement_level: recommended - ref: browser.page.x requirement_level: required diff --git a/model/browser/registry.yaml b/model/browser/registry.yaml index b1b5cd8a51..fe6103f598 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -79,7 +79,7 @@ groups: stability: development brief: 'Target element XPath using the XPathExpression API.' examples: ["//*[@id='testBtn']"] - - id: browser.mouse_event.button + - id: hw.mouse.button type: members: - id: left From db593e6df6bfabf73a867aadac25377d71d009ab Mon Sep 17 00:00:00 2001 From: joaquin-diaz Date: Wed, 29 Oct 2025 11:14:38 -0300 Subject: [PATCH 6/8] chore: use template[string] as type for browser.element.attributes --- docs/browser/browser-events.md | 4 ++-- docs/registry/attributes/browser.md | 4 ++-- model/browser/registry.yaml | 13 +++++++------ 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index e03096fdc1..fee4428871 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -74,10 +74,10 @@ This event describes a user click action in the browser. | [`browser.page.y`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | | [`browser.tag_name`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | | [`browser.xpath`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element XPath using the XPathExpression API. | `//*[@id='testBtn']` | -| [`browser.element.attributes`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | JSON-serialized map of data-otel-* attributes from the target element. [1] | `{"id": "123", "name": "Name"}` | +| [`browser.element.attributes.`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Map of data-otel-* attributes from the target element. [1] | `testBtn`; `submit` | | [`hw.mouse.button`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | User friendly name of the mouse button pressed. See [MouseEvent.buttons](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons#value). | `left` | -**[1] `browser.element.attributes`:** Represented as a JSON object string. Example: {"id": "123", "name": "Name"}. Arbitrary maps are not supported as attribute types in OTel, so this is stored as string. +**[1] `browser.element.attributes.`:** Key is the attribute name after "data-otel-" and value is the attribute value. Example: `