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

## Event: `browser.user_action.click`

<!-- 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.css_selector`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Target element CSS Selector [1] | `#main > div:nth-child(2) > button.submit` |
| [`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.element.attributes.<key>`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Map of data-otel-* attributes from the target element. [2] | `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.css_selector`:** Value SHOULD be a CSS selector that uniquely identifies the target element within the document. Value SHOULD be escaped using CSS.escape() to avoid issues with special characters.

**[2] `browser.element.attributes.<key>`:** Key is the attribute name after "data-otel-" and value is the attribute value. Example: `<button data-otel-id="testBtn" data-otel-role="submit">` SHOULD be recorded as `browser.element.attributes.id = "testBtn"` and `browser.element.attributes.role = "submit"`.

---

`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 |
|---|---|---|
| `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
32 changes: 26 additions & 6 deletions docs/registry/attributes/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,35 @@ 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-css-selector" href="#browser-css-selector">`browser.css_selector`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Target element CSS Selector [2] | `#main > div:nth-child(2) > button.submit` |
| <a id="browser-element-attributes" href="#browser-element-attributes">`browser.element.attributes.<key>`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Map of data-otel-* attributes from the target element. [3] | `testBtn`; `submit` |
| <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 [4] | `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 [5] | |
| <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 [6] | `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="hw-mouse-button" href="#hw-mouse-button">`hw.mouse.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` |

**[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.css_selector`:** Value SHOULD be a CSS selector that uniquely identifies the target element within the document. Value SHOULD be escaped using CSS.escape() to avoid issues with special characters.

**[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.element.attributes.<key>`:** Key is the attribute name after "data-otel-" and value is the attribute value. Example: `<button data-otel-id="testBtn" data-otel-role="submit">` SHOULD be recorded as `browser.element.attributes.id = "testBtn"` and `browser.element.attributes.role = "submit"`.

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

**[5] `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.

**[6] `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.

---

`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 |
|---|---|---|
| `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: hw.mouse.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.css_selector
requirement_level: required
- ref: browser.element.attributes
requirement_level: recommended
51 changes: 51 additions & 0 deletions model/browser/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,54 @@ 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: template[string]
stability: development
brief: 'Map of data-otel-* attributes from the target element.'
note: >
Key is the attribute name after "data-otel-" and value is the attribute value. Example:
`<button data-otel-id="testBtn" data-otel-role="submit">`
SHOULD be recorded as `browser.element.attributes.id = "testBtn"`
and `browser.element.attributes.role = "submit"`.
examples: ["testBtn", "submit"]
- id: browser.css_selector
type: string
stability: development
brief: 'Target element CSS Selector'
examples: ["#main > div:nth-child(2) > button.submit"]
note: >
Value SHOULD be a CSS selector that uniquely identifies the target element within the document.
Value SHOULD be escaped using CSS.escape() to avoid issues with special characters.
- id: hw.mouse.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"]
Comment on lines +86 to +103
Copy link
Contributor

Choose a reason for hiding this comment

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

These should be in the registry file in the hardware folder. But only make the change once the triage:accepted label has been added.

Loading