chore: improve getElementXPath and adjust instrumentation to updated semconv PR

Author: joaquin-diaz

packages/instrumentation-user-action/src/instrumentation.test.ts

@@ -48,7 +48,7 @@ describe('UserActionInstrumentation', () => {
   };
 
   const dispatchMouseDownEvent = (element: HTMLElement, button: number) => {
-    const clickEvent = new MouseEvent('mousedown', {
+    const clickEvent = new MouseEvent('click', {
       button,
       bubbles: true,
       clientX: 100,
@@ -67,12 +67,12 @@ describe('UserActionInstrumentation', () => {
 
     const log = logs[0];
     expect(log?.severityNumber).toBe(SeverityNumber.INFO);
-    expect(log?.eventName).toBe('browser.user_action');
-    expect(log?.attributes['page.x']).toBe(100);
-    expect(log?.attributes['page.y']).toBe(150);
-    expect(log?.attributes['tag_name']).toBe('DIV');
-    expect(log?.attributes['type']).toBe('mousedown.left');
-    expect(log?.attributes['xpath']).toBe('//html/body/div');
+    expect(log?.eventName).toBe('browser.user_action.click');
+    expect(log?.attributes['browser.mouse_event.button']).toBe('left');
+    expect(log?.attributes['browser.page.x']).toBe(100);
+    expect(log?.attributes['browser.page.y']).toBe(150);
+    expect(log?.attributes['browser.tag_name']).toBe('DIV');
+    expect(log?.attributes['browser.xpath']).toBe('//html/body/div');
   });
 
   it('should emit a log when the element triggers a mousedown event with the right and middle click', () => {
@@ -85,17 +85,21 @@ describe('UserActionInstrumentation', () => {
     expect(logs.length).toBe(2);
 
     const middleClickLog = logs[0];
-    expect(middleClickLog?.attributes['type']).toBe('mousedown.middle');
+    expect(middleClickLog?.attributes['browser.mouse_event.button']).toBe(
+      'middle',
+    );
 
     const rightClickLog = logs[1];
-    expect(rightClickLog?.attributes['type']).toBe('mousedown.right');
+    expect(rightClickLog?.attributes['browser.mouse_event.button']).toBe(
+      'right',
+    );
   });
 
   it('should not emit a log when the event target is not an HTMLElement', () => {
     const textNode = document.createTextNode('Test Text Node');
     document.body.appendChild(textNode);
 
-    const clickEvent = new MouseEvent('mousedown', {
+    const clickEvent = new MouseEvent('click', {
       button: 0,
       bubbles: true,
       clientX: 100,
@@ -128,7 +132,7 @@ describe('UserActionInstrumentation', () => {
     expect(logs.length).toBe(1);
 
     const log = logs[0];
-    expect(log?.attributes['tags']).toEqual({
+    expect(log?.attributes['browser.element.attributes']).toEqual({
       'user-id': '12345',
       'session-id': 'abcde',
     });

packages/instrumentation-user-action/src/instrumentation.ts

@@ -18,21 +18,21 @@ import { SeverityNumber } from '@opentelemetry/api-logs';
 import { InstrumentationBase } from '@opentelemetry/instrumentation';
 import { getElementXPath } from '@opentelemetry/web-utils';
 import {
+  ATTR_MOUSE_EVENT_BUTTON,
   ATTR_PAGE_X,
   ATTR_PAGE_Y,
   ATTR_TAG_NAME,
   ATTR_TAGS,
-  ATTR_TYPE,
   ATTR_XPATH,
-  EVENT_NAME,
+  CLICK_EVENT_NAME,
 } from './semconv';
 import type {
   AutoCapturedUserAction,
-  UserActionEvent,
+  MouseButton,
   UserActionInstrumentationConfig,
 } from './types';
 
-const DEFAULT_AUTO_CAPTURED_ACTIONS: AutoCapturedUserAction[] = ['mousedown'];
+const DEFAULT_AUTO_CAPTURED_ACTIONS: AutoCapturedUserAction[] = ['click'];
 const OTEL_ELEMENT_ATTRIBUTE_PREFIX = 'data-otel-';
 
 /**
@@ -47,16 +47,16 @@ export class UserActionInstrumentation extends InstrumentationBase<UserActionIns
     return [];
   }
 
-  private _getUserActionFromMouseEvent(event: MouseEvent): UserActionEvent {
+  private _getMouseButtonFromMouseEvent(event: MouseEvent): MouseButton {
     switch (event.button) {
       case 0:
-        return 'mousedown.left';
+        return 'left';
       case 1:
-        return 'mousedown.middle';
+        return 'middle';
       case 2:
-        return 'mousedown.right';
+        return 'right';
       default:
-        return 'mousedown.left';
+        return 'left';
     }
   }
 
@@ -71,7 +71,10 @@ export class UserActionInstrumentation extends InstrumentationBase<UserActionIns
       return;
     }
 
-    const xPath = getElementXPath(element, true);
+    const xPath = getElementXPath(element, {
+      useIdForTargetElement: true,
+      useIdForAncestors: true,
+    });
     const otelPrefixedAttributes: Record<string, string> = {};
 
     // Grab all the attributes in the element that start with data-otel-*
@@ -85,13 +88,13 @@ export class UserActionInstrumentation extends InstrumentationBase<UserActionIns
 
     this.logger.emit({
       severityNumber: SeverityNumber.INFO,
-      eventName: EVENT_NAME,
+      eventName: CLICK_EVENT_NAME,
       attributes: {
         [ATTR_PAGE_X]: event.pageX,
         [ATTR_PAGE_Y]: event.pageY,
         [ATTR_TAG_NAME]: element.tagName,
         [ATTR_TAGS]: otelPrefixedAttributes,
-        [ATTR_TYPE]: this._getUserActionFromMouseEvent(event),
+        [ATTR_MOUSE_EVENT_BUTTON]: this._getMouseButtonFromMouseEvent(event),
         [ATTR_XPATH]: xPath,
       },
     });
@@ -101,12 +104,12 @@ export class UserActionInstrumentation extends InstrumentationBase<UserActionIns
     const autoCapturedActions =
       this._config.autoCapturedActions ?? DEFAULT_AUTO_CAPTURED_ACTIONS;
 
-    if (autoCapturedActions.includes('mousedown')) {
-      document.addEventListener('mousedown', this._clickHandler, true);
+    if (autoCapturedActions.includes('click')) {
+      document.addEventListener('click', this._clickHandler, true);
     }
   }
 
   override disable(): void {
-    document.removeEventListener('mousedown', this._clickHandler, true);
+    document.removeEventListener('click', this._clickHandler, true);
   }
 }

packages/instrumentation-user-action/src/semconv.ts

@@ -20,46 +20,46 @@
  * @see https://github.com/open-telemetry/opentelemetry-js/tree/main/semantic-conventions#unstable-semconv
  */
 
-export const EVENT_NAME = 'browser.user_action';
+export const CLICK_EVENT_NAME = 'browser.user_action.click';
 
 /**
- * @example 10
+ * @example left
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_PAGE_X = 'page.x';
+export const ATTR_MOUSE_EVENT_BUTTON = 'browser.mouse_event.button';
 
 /**
  * @example 10
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_PAGE_Y = 'page.y';
+export const ATTR_PAGE_X = 'browser.page.x';
 
 /**
- * @example "BUTTON"
+ * @example 10
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_TAG_NAME = 'tag_name';
+export const ATTR_PAGE_Y = 'browser.page.y';
 
 /**
- * @example ["id", "name"]
+ * @example "BUTTON"
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_TAGS = 'tags';
+export const ATTR_TAG_NAME = 'browser.tag_name';
 
 /**
- * @example "click.right"
+ * @example {"id": "123", "name": "Name"}
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_TYPE = 'type';
+export const ATTR_TAGS = 'browser.element.attributes';
 
 /**
  * @example "//*[@id='testBtn']"
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_XPATH = 'xpath';
+export const ATTR_XPATH = 'browser.xpath';

packages/instrumentation-user-action/src/types.ts

@@ -16,12 +16,9 @@
 
 import type { InstrumentationConfig } from '@opentelemetry/instrumentation';
 
-export type AutoCapturedUserAction = 'mousedown';
+export type AutoCapturedUserAction = 'click';
 
-export type UserActionEvent =
-  | 'mousedown.left'
-  | 'mousedown.middle'
-  | 'mousedown.right';
+export type MouseButton = 'left' | 'middle' | 'right';
 
 /**
  * UserActionInstrumentation Configuration

packages/web-utils/src/getElementXPath.test.ts

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it } from 'vitest';
 
 import { getElementXPath } from './getElementXPath';
 
-describe(getElementXPath, () => {
+describe('getElementXPath', () => {
   const expectXPath = (xpath: string, node: Node) => {
     const result = document.evaluate(
       xpath,
@@ -31,24 +31,45 @@ describe(getElementXPath, () => {
     expect(result.singleNodeValue).toBe(node);
   };
 
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
   it('should return "/" for document node', () => {
     const xpath = getElementXPath(document);
 
     expect(xpath).toBe('/');
     expectXPath(xpath, document);
   });
 
-  it('should return correct XPath for element with ID when optimized', () => {
+  it('should return correct XPath for element with ID when useIdForTargetElement is true', () => {
     const div = document.createElement('div');
     div.id = 'test-id';
     document.body.appendChild(div);
 
-    const xpath = getElementXPath(div, true);
+    const xpath = getElementXPath(div, {
+      useIdForTargetElement: true,
+    });
 
     expect(xpath).toBe('//*[@id="test-id"]');
     expectXPath(xpath, div);
+  });
+
+  it('should not use ID for element with ID when useIdForTargetElement is true but there are duplicated IDs', () => {
+    const div = document.createElement('div');
+    div.id = 'test-id';
+    document.body.appendChild(div);
+
+    const duplicateDiv = document.createElement('div');
+    duplicateDiv.id = 'test-id';
+    document.body.appendChild(duplicateDiv);
 
-    document.body.removeChild(div);
+    const xpath = getElementXPath(div, {
+      useIdForTargetElement: true,
+    });
+
+    expect(xpath).toBe('//html/body/div');
+    expectXPath(xpath, div);
   });
 
   it('should return correct XPath for nested elements', () => {
@@ -61,8 +82,21 @@ describe(getElementXPath, () => {
 
     expect(xpath).toBe('//html/body/div/span');
     expectXPath(xpath, child);
+  });
 
-    document.body.removeChild(parent);
+  it('should return correct XPath using ID for nested elements', () => {
+    const parent = document.createElement('div');
+    parent.id = 'parent-id';
+    const child = document.createElement('span');
+    parent.appendChild(child);
+    document.body.appendChild(parent);
+
+    const xpath = getElementXPath(child, {
+      useIdForAncestors: true,
+    });
+
+    expect(xpath).toBe('//html/body//*[@id="parent-id"]/span');
+    expectXPath(xpath, child);
   });
 
   it('should return correct XPath with index for sibling elements', () => {
@@ -77,7 +111,5 @@ describe(getElementXPath, () => {
 
     expect(xpath).toBe('//html/body/div/span[2]');
     expectXPath(xpath, child2);
-
-    document.body.removeChild(parent);
   });
 });