Add Browser UserAction Event #1941
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| linkTitle: Events | ||
| ---> | ||
|
|
||
| # Semantic conventions for browser events | ||
|
|
||
| **Status**: [Development][DocumentStatus] | ||
|
|
||
| This document defines semantic conventions for browser (web) instrumentations | ||
| that emit events. | ||
|
|
||
| ## UserAction Event | ||
|
|
||
| <!-- 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:**  | ||
|
|
||
| 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:** | ||
|
|
||
| | Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | ||
| |---|---|---|---|---|---| | ||
| | `click_coordinates` | string | Click coordinates captured as a string in the format {x}X{y}. | `345X23` | `Recommended` |  | | ||
| | `element` | string | Target element tag name and it is obtained via event.target.tagName. | `button` | `Recommended` |  | | ||
| | `element_xpath` | string | Target element xpath | `//*[@id='testBtn']` | `Recommended` |  | | ||
| | `tags` | string | Grab data from data-otel-* attributes in tree. | `id` | `Recommended` |  | | ||
| | `user_action_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. | `cl` | `Required` |  | | ||
|
|
||
| `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 | | ||
| |---|---|---| | ||
| | `cl` | An element is left clicked by a user. |  | | ||
| | `cm` | An element is middle clicked by a user. |  | | ||
| | `cr` | An element is right clicked by a user. |  | | ||
| | `ke` | An element is entered via keyboard by a user. |  | | ||
| | `ks` | A space is entered via keyboard by a user. |  | | ||
| | `o` | User actions that are not listed above. |  | | ||
| | `r` | An element is resized by a user. |  | | ||
| | `s` | An element is scrolled by a user. |  | | ||
| | `z` | An element is zoomed by a user. |  | | ||
|
|
||
| <!-- markdownlint-restore --> | ||
| <!-- prettier-ignore-end --> | ||
| <!-- END AUTOGENERATED TEXT --> | ||
| <!-- endsemconv --> | ||
|
|
||
| [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status |
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,82 @@ | ||||||
| groups: | ||||||
| - id: event.browser.user_action | ||||||
| stability: development | ||||||
| type: event | ||||||
| name: browser.user_action | ||||||
|
There was a problem hiding this comment. Do we think there's an opportunity to use another prefix/namespace other than Possible alternative namespaces: There was a problem hiding this comment. Maybe, but that is a larger discussion for the Client SIG. We can always deprecate this event in favor of any stable standard. But generally it would be "nice" to have to define a commonly used event once -- but there are some very browser centric definitions here at the moment. |
||||||
| brief: > | ||||||
| This event describes actions performed by the user such as click, scroll, zoom, resize, etc. | ||||||
| body: | ||||||
|
There was a problem hiding this comment. I would like to see a comment here to clarify that this is temporary or that this will actually be an attribute. That way readers do not expect to find content in the actual body. |
||||||
| id: browser.user_action | ||||||
| requirement_level: required | ||||||
| stability: development | ||||||
| type: map | ||||||
| fields: | ||||||
| - id: element | ||||||
|
There was a problem hiding this comment. let's try to follow attribute naming guidelines since we'll be moving these to (complex) attributes in the future
Suggested change
There was a problem hiding this comment. @trask Sorry No! If / when the Then there is just the overhead of creating individual on-off fields (only used for a single event) and going through the approvals / discussions about each individual field and how it can / should be made generic. Vs having a single discussion about the "naming" of fields within a specific event. If / When the community decides that they want to reuse the same type of "thing" identified by the individual event specific name, then at that point for those few fields (like the already defined While I know there has been discussions about "allowing" complex types to be defined as individual fields but sent in a complete manner, this is would not scalable and would also mean that for every event specific field for every event the names would become something like
Additional, part of the reason that the browser environment NEEDS to keep these in a single location is because
The client Sig spent months defining the "common" set of values for the event payloads based on different companies (well before some of the attributes became stable and renamed (like the There was a problem hiding this comment. I'm not proposing a top-level There was a problem hiding this comment. I'm ok with keeping this as just There was a problem hiding this comment. on further discussion in client SIG meeting, let's go with (we can't have both There was a problem hiding this comment. @breedx-splk , based on us changing this from a I know for .NET there is no "Element" (so the tag name is not relevant as it's more "type" (button, text box)) but it does have an Originally (years ago), we started out calling this There was a problem hiding this comment. And to be a little clearer here, (if) |
||||||
| type: string | ||||||
| stability: development | ||||||
| brief: Target element tag name and it is obtained via event.target.tagName. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| requirement_level: recommended | ||||||
| examples: ["button"] | ||||||
| - id: element_xpath | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Some of the documentation (if you care to read) around how we got to these names in the client SIG are located in the Archived section of the Client SIG meeting notes this inlcudes documents and spreadsheets used to get consensus on names to be used If your objecting the the |
||||||
| type: string | ||||||
| stability: development | ||||||
| brief: Target element xpath | ||||||
| requirement_level: recommended | ||||||
| examples: ["//*[@id='testBtn']"] | ||||||
| - id: user_action_type | ||||||
trask marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| type: enum | ||||||
|
There was a problem hiding this comment. need to confirm the |
||||||
| members: | ||||||
| - id: clickleft | ||||||
| value: "cl" | ||||||
|
There was a problem hiding this comment. is |
||||||
| stability: development | ||||||
| brief: An element is left clicked by a user. | ||||||
| - id: clickright | ||||||
| value: "cr" | ||||||
| stability: development | ||||||
| brief: An element is right clicked by a user. | ||||||
| - id: clickmiddle | ||||||
| value: "cm" | ||||||
| stability: development | ||||||
| brief: An element is middle clicked by a user. | ||||||
| - id: scroll | ||||||
| value: "s" | ||||||
| stability: development | ||||||
| brief: An element is scrolled by a user. | ||||||
| - id: zoom | ||||||
| value: "z" | ||||||
| stability: development | ||||||
| brief: An element is zoomed by a user. | ||||||
| - id: resize | ||||||
| value: "r" | ||||||
| stability: development | ||||||
| brief: An element is resized by a user. | ||||||
| - id: keyboardenter | ||||||
| value: "ke" | ||||||
| stability: development | ||||||
| brief: An element is entered via keyboard by a user. | ||||||
| - id: keyboardspace | ||||||
| value: "ks" | ||||||
| stability: development | ||||||
| brief: A space is entered via keyboard by a user. | ||||||
| - id: other | ||||||
| value: "o" | ||||||
| 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: ["cl"] | ||||||
| - id: click_coordinates | ||||||
|
There was a problem hiding this comment. what do you think about
or is {x}Y{y} a browser spec thing? thanks There was a problem hiding this comment. We had this discussion in the Client Sig when we came up with this name, it went through many iterations and we settled on a single field formatted in this manner so that backends (and users) can add any processing they want around this vs the overhead of populating, sending, storing and processing of individual fields. There was a problem hiding this comment. For reference, the Android There was a problem hiding this comment. discussion in SIG meeting leaning towards 2-value number array |
||||||
| type: string | ||||||
| stability: development | ||||||
| brief: Click coordinates captured as a string in the format {x}X{y}. | ||||||
| requirement_level: recommended | ||||||
| examples: ["345X23"] | ||||||
|
Comment on lines
+71
to
+76
There was a problem hiding this comment. Is this specific enough? Should this also specify if the coordinates are relative to the element or the page or the window or ??? |
||||||
| - id: tags | ||||||
| type: string | ||||||
| stability: development | ||||||
| brief: Grab data from data-otel-* attributes in tree. | ||||||
| requirement_level: recommended | ||||||
| examples: ["id"] | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
May use client?