Skip to content
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/joaquin-diaz_feat_add-user-action-event.yaml
Original file line number Diff line number Diff line change
@@ -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: [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.
# Use pipe (|) for multiline entries.
subtext:
44 changes: 44 additions & 0 deletions docs/browser/browser-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,48 @@ semantic convention tooling supports complex attributes
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

<!-- semconv event.browser.user_action -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

**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) |

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
43 changes: 33 additions & 10 deletions docs/registry/attributes/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,43 @@

The web browser attributes

**Attributes:**

| Key | Stability | Value Type | Description | Example Values |
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="browser-brands" href="#browser-brands">`browser.brands`</a> | ![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"]` |
| <a id="browser-language" href="#browser-language">`browser.language`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` |
| <a id="browser-mobile" href="#browser-mobile">`browser.mobile`</a> | ![Development](https://img.shields.io/badge/-development-blue) | boolean | A boolean that is true if the browser is running on a mobile device [3] | |
| <a id="browser-platform" href="#browser-platform">`browser.platform`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` |
| <a id="browser-brands" href="#browser-brands">`browser.brands`</a> | 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) |
| <a id="browser-element-attributes" href="#browser-element-attributes">`browser.element.attributes`</a> | 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) |
| <a id="browser-language" href="#browser-language">`browser.language`</a> | string | Preferred language of the user using the browser [3] | `en`; `en-US`; `fr`; `fr-FR` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-mobile" href="#browser-mobile">`browser.mobile`</a> | boolean | A boolean that is true if the browser is running on a mobile device [4] | | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-page-x" href="#browser-page-x">`browser.page.x`</a> | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-page-y" href="#browser-page-y">`browser.page.y`</a> | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-platform" href="#browser-platform">`browser.platform`</a> | string | The platform on which the browser is running [5] | `Windows`; `macOS`; `Android` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-tag-name" href="#browser-tag-name">`browser.tag_name`</a> | string | Target element tag name obtained via event.target.tagName. | `BUTTON` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-user-action-type" href="#browser-user-action-type">`browser.user_action.type`</a> | string | Type of user interaction. [6] | `click.right` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="browser-xpath" href="#browser-xpath">`browser.xpath`</a> | 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) |
44 changes: 44 additions & 0 deletions model/browser/events.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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']"]
37 changes: 37 additions & 0 deletions model/browser/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Comment on lines +53 to +62
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

- id: browser.tag_name
type: string
stability: development
brief: 'Target element tag name obtained via event.target.tagName.'
examples: ['BUTTON']
Comment on lines +63 to +67
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

- 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']"]
Loading