@imqa/instrumentation-user-interaction

개요

@imqa/instrumentation-user-interaction은 IMQA 모니터링 시스템에서 웹 애플리케이션의 사용자 이벤트를 캡처합니다. 이 계측은 OpenTelemetry 형식을 사용하여 클릭, 입력, 폼 제출과 같은 클라이언트 측 상호작용을 추적하도록 설계되었습니다.

스키마 구조

스키마는 JSON 문서로, JSON Schema Draft 2020-12 사양을 따릅니다. 사용자 상호작용 Telemetry 데이터의 구조화된 형식을 정의합니다.

사용자 상호작용 범위

사용자 상호작용 범위는 클릭과 같은 DOM 상호작용 이벤트를 캡처합니다.

범위 정의

"scope": {
  "name": "@opentelemetry/instrumentation-user-interaction",
  "version": "0.44.1"
}

사용자 상호작용 스팬

사용자 상호작용 스팬은 클릭과 같은 사용자 이벤트를 캡처합니다:

• traceId: 트레이스의 고유 식별자
• spanId: 스팬의 고유 식별자
• name: 상호작용의 타입 (예: "click")
• kind: 스팬의 타입 (1 = INTERNAL)
• startTimeUnixNano: 에포크 이후의 시작 시간 (나노초)
• endTimeUnixNano: 에포크 이후의 종료 시간 (나노초)
• status: 결과 상태 (0 = OK)

사용자 상호작용 스팬 속성

| 속성 | 타입 | 설명 | |-----------|------|-------------| | event_type | string | 이벤트의 타입 (예: "click") | | target_element | string | 상호작용된 HTML 요소 타입 | | target_xpath | string | 대상 요소의 XPath | | http.url | string | 현재 페이지 URL | | location.href | string | 현재 페이지 URL | | environment | string | 환경 이름 | | deployment.environment | string | 배포 환경 | | screen.name | string | 화면/페이지 이름 | | screen.type | string | 화면/페이지 타입 | | session.id | string | 사용자 세션 식별자 | | url.full | string | 요청 전체 URL (예: "https://example.com/articles/4?s=1&t1" ) | | component | string | 컴포넌트 (사용자 상호작용) | | span.type | string | 스팬 타입 (사용자 상호작용) |

다른 스키마와의 관계

사용자 상호작용은 종종 다른 추적된 이벤트를 트리거합니다:

1. 클릭이 싱글 페이지 애플리케이션의 라우트 변경을 트리거할 수 있습니다
2. 사용자 상호작용은 오류 스키마에서 캡처되는 오류를 초래할 수 있습니다
3. 사용자 상호작용은 일반적으로 라우트 변경과 오류의 부모 스팬으로 나타납니다

사용 방법

이 스키마는 IMQA 모니터링 시스템으로 Telemetry 데이터를 처리하고 저장하기 전에 사용자 상호작용을 위한 Telemetry 데이터를 검증하는 데 사용됩니다. 이는 모든 필수 필드가 올바르게 포함되어 있는지 확인합니다.

계측 설정

(boolean 또는 IMQAUserInteractionInstrumentationConfig, 선택)

사용자 상호작용 계측을 활성화하거나 비활성화합니다. true로 설정하면 클릭, 입력 등 사용자 상호작용 이벤트가 자동으로 계측됩니다. IMQAUserInteractionInstrumentationConfig을 통해 상호작용 계측의 세부 설정을 커스터마이즈할 수 있습니다.

자세한 계측 정보는 @imqa/instrumentation-user-interaction 참조

interface UserInteractionInstrumentationConfig extends InstrumentationConfig {
    eventNames?: EventName[];
    shouldPreventSpanCreation?: ShouldPreventSpanCreation;
    events?: UserInteractionEventsConfig;
}

• eventNames: 계측할 이벤트 목록을 지정합니다. 기본값은 DEFAULT_AUTO_INSTRUMENTED_EVENTS입니다.
  • 포인터 이벤트: click, dblclick, mousedown, mouseup
  • Form 이벤트: submit, reset, change
  • Drag & Drop: dragend, drop
  • 미디어 이벤트: ended, pause, play
• shouldPreventSpanCreation: Span이 생성될 때 호출되는 콜백 함수입니다. true를 반환하면 Span 기록을 방지합니다. 이 핸들러를 사용하여 생성된 Span에 추가 속성을 추가할 수 있습니다.
• events: 사용자 상호작용 이벤트를 설정합니다. UserInteractionEventsConfig 인터페이스를 사용하여 세부 설정을 지정할 수 있습니다.

type UserInteractionEventsConfig = {
  [type: string]: boolean;
};
const DEFAULT_AUTO_INSTRUMENTED_EVENTS: UserInteractionEventsConfig = {
  // pointer
  click: true,
  dblclick: true,
  mousedown: true,
  mouseup: true,

  // form
  submit: true,
  reset: true,
  change: true,

  // drap & drop
  dragend: true,
  drop: true,

  // media
  ended: true,
  pause: true,
  play: true,
};

기타

유효한 사용자 상호작용 Telemetry 객체는 다음과 같은 내용을 포함합니다:

• 서비스, 브라우저 및 환경을 식별하는 리소스 정보
• 클릭, 입력, 폼 제출과 같은 이벤트를 캡처하는 사용자 상호작용 스팬
• 상호작용된 요소에 대한 상세 정보

데이터는 다양한 Telemetry 수집 및 분석 도구와 호환되는 OpenTelemetry 프로토콜 형식을 따릅니다.

라이센스

Copyright (c) 2024-2025 ONYCOM CO., LTD. All rights reserved.