Skip to content
Open
Show file tree
Hide file tree
Changes from 3 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:
41 changes: 41 additions & 0 deletions docs/browser/browser-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,45 @@ semantic convention tooling supports complex attributes
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

<!-- semconv event.browser.user_action.click -->
<!-- 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.click`.

This event describes a user click action in the browser.

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

---

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

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

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
30 changes: 24 additions & 6 deletions docs/registry/attributes/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,33 @@ The web browser attributes
| Key | Stability | Value Type | Description | Example Values |
|---|---|---|---|---|
| <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-element-attributes" href="#browser-element-attributes">`browser.element.attributes`</a> | ![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"}` |
| <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 [3] | `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 [4] | |
| <a id="browser-mouse-event-button" href="#browser-mouse-event-button">`browser.mouse_event.button`</a> | ![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` |
| <a id="browser-page-x" href="#browser-page-x">`browser.page.x`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | Click x (horizontal) coordinates (in pixels) relative to the entire document. | `10` |
| <a id="browser-page-y" href="#browser-page-y">`browser.page.y`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | Click y (vertical) coordinates (in pixels) relative to the entire document. | `10` |
| <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 [5] | `Windows`; `macOS`; `Android` |
| <a id="browser-tag-name" href="#browser-tag-name">`browser.tag_name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Target element tag name obtained via event.target.tagName. | `BUTTON` |
| <a id="browser-xpath" href="#browser-xpath">`browser.xpath`</a> | ![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`).

**[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.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.
**[3] `browser.language`:** This value is intended to be taken from the Navigator API `navigator.language`.

**[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.
**[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.

**[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.

---

`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) |
19 changes: 19 additions & 0 deletions model/browser/events.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,22 @@ groups:
brief: A unique ID representing this particular metric instance.
requirement_level: required
examples: ["v3-1677874579383-6381583661209"]
- id: event.browser.user_action.click
stability: development
type: event
name: browser.user_action.click
brief: >
This event describes a user click action in the browser.
attributes:
- 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
47 changes: 47 additions & 0 deletions model/browser/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,50 @@ 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.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"]
Loading