@imqa/user-event

개요

@imqa/user-event는 개발자가 특정 사용자 이벤트를 추적하고 분석할 수 있도록 도와주는 라이브러리입니다. 이 패키지를 사용하여 사용자 상호작용, 비즈니스 로직 실행, 폼 제출 등과 같은 중요한 이벤트들을 OpenTelemetry trace로 기록할 수 있습니다.

주요 목적:

• 이벤트 추적: 사용자의 특정 행동이나 애플리케이션의 중요한 동작을 trace로 기록
• 성능 분석: 이벤트의 시작부터 완료까지의 전체 duration 측정
• 컨텍스트 관리: 이벤트 진행 중 발생하는 다른 계측(fetch, console, exception 등)들을 동일한 컨텍스트로 그룹화
• 이벤트 분석: IMQA에서 제공하는 이벤트 분석 기능을 통한 사용자 행동 패턴 분석

설치

npm install @imqa/user-event

주요 기능

핵심 API

• start(): 사용자 이벤트를 시작하고 새로운 컨텍스트 생성
• end(): 이벤트를 완료하고 duration과 함께 span 기록
• getActive(): 현재 활성화된 이벤트 정보 조회
• cancel(): 이벤트를 취소 (span을 기록하지 않음)

기본 사용법

import { IMQA } from '@imqa/web-agent';

// 기본 사용 예시
function handleButtonClick() {
  // 이벤트 시작 - 새로운 컨텍스트 생성
  const eventId = IMQA.userEvent.start('button-click', {
    'button.name': 'submit',
    'page.url': window.location.href,
  });

  // 이 시점부터 다른 계측들(fetch, console 등)이 
  // 위에서 생성된 컨텍스트를 사용하게 됩니다
  
  // 비즈니스 로직 실행
  setTimeout(() => {
    // 이벤트 완료 - 전체 duration과 함께 span 기록
    IMQA.userEvent.end(eventId, {
      'action.result': 'success',
      'items.count': 5,
    });
  }, 1000);
}

상세 API 문서

start(name?, attributes?)

사용자 이벤트를 시작하고 고유한 이벤트 ID를 반환합니다.

Parameters:

• name (string, optional): 이벤트 이름 (기본값: user-event-[randomId])
• attributes (Attributes, optional): 이벤트에 추가할 커스텀 속성

Returns: string - 이벤트의 고유 식별자

end(id, attributes?)

지정된 ID의 사용자 이벤트를 완료하고 span을 기록합니다.

Parameters:

• id (string, required): start()에서 반환된 이벤트 ID
• attributes (Attributes, optional): 이벤트 완료 시 추가할 속성

getActive()

현재 활성화된 사용자 이벤트 정보를 반환합니다.

Returns: UserEventInstance | undefined

cancel(id)

지정된 ID의 사용자 이벤트를 취소합니다. span을 기록하지 않습니다.

Parameters:

• id (string, required): 취소할 이벤트 ID

사용 예시

1. 기본 이벤트 추적

export function basicUserEventExample() {
  // 버튼 클릭 이벤트 시작
  const eventId = IMQA.userEvent.start('button-click', {
    'button.name': 'submit',
    'page.url': window.location.href,
  });

  // 이 기간 동안 다른 계측들이 동일한 컨텍스트를 사용
  // 예: fetch 요청, console 로그, exception 등
  
  setTimeout(() => {
    // 이벤트 완료 - 전체 duration과 함께 span 생성
    IMQA.userEvent.end(eventId, {
      'action.result': 'success',
      'items.count': 5,
    });
  }, 1000);
}

2. 에러 처리가 포함된 고급 사용법

2-1. getActive()를 사용한 에러 처리

이 방법은 getActive()를 사용하여 현재 활성화된 이벤트를 가져와서 처리합니다. 동시에 여러개의 활성화된 이벤트가 있을 수 있는 상황에서는 eventId 변수를 사용하는 방법(2-2)을 권장합니다.

export function advancedUserEventWithGetActive() {
  try {
    // 폼 제출 이벤트 시작
    IMQA.userEvent.start('form-submission', {
      'form.type': 'contact',
      'form.fields': 'name,email,message',
    });

    // 폼 검증 및 제출 로직
    validateForm();
    submitForm();
    
    // 현재 활성화된 이벤트를 가져와서 성공 처리
    const activeEvent = IMQA.userEvent.getActive();
    if (activeEvent) {
      IMQA.userEvent.end(activeEvent.id, {
        'submission.result': 'success',
      });
    }
  } catch (error) {
    // 현재 활성화된 이벤트를 가져와서 에러 처리
    const activeEvent = IMQA.userEvent.getActive();
    if (activeEvent) {
      IMQA.userEvent.end(activeEvent.id, {
        'submission.result': 'error',
        'error.type': error.constructor.name,
        'error.message': error.message,
      });
    }
    throw error;
  }
}

2-2. eventId 변수를 사용한 에러 처리

eventId 변수를 여러 비즈니스 로직에서 공유할 수 있는 스코프에 선언하여 사용합니다.

export function advancedUserEventWithEventId() {
  let eventId: string | null = null;
  
  try {
    // 폼 제출 이벤트 시작 - ID를 변수에 저장
    eventId = IMQA.userEvent.start('form-submission', {
      'form.type': 'contact',
      'form.fields': 'name,email,message',
    });

    // 폼 검증 및 제출 로직
    validateForm();
    submitForm();
    
    // 저장된 eventId로 성공 처리
    IMQA.userEvent.end(eventId, {
      'submission.result': 'success',
    });
    
    eventId = null; // 완료 후 초기화
  } catch (error) {
    // 저장된 eventId로 에러 처리
    if (eventId) {
      IMQA.userEvent.end(eventId, {
        'submission.result': 'error',
        'error.type': error.constructor.name,
        'error.message': error.message,
      });
      eventId = null; // 에러 처리 후 초기화
    }
    throw error;
  }
}

3. 활성 이벤트 확인

export function checkActiveUserEvent() {
  const activeEvent = IMQA.userEvent.getActive();
  
  if (activeEvent) {
    console.log('Active user event:', {
      id: activeEvent.id,
      name: activeEvent.name,
      duration: Date.now() - activeEvent.startTime,
      attributes: activeEvent.attributes,
    });
  } else {
    console.log('No active user event');
  }
}

4. 이벤트 취소

export function cancelUserEventExample() {
  const eventId = IMQA.userEvent.start('file-upload', {
    'file.size': '1024000',
    'file.type': 'image/jpeg',
  });

  // 사용자가 업로드를 취소하는 경우
  setTimeout(() => {
    // end() 대신 cancel() 사용 - span을 기록하지 않음
    IMQA.userEvent.cancel(eventId);
  }, 500);
}

기록되는 속성

사용자 이벤트가 완료될 때 다음과 같은 기본 속성들이 자동으로 추가됩니다:

• imqa.span.type: 'user_event'
• user_event.duration_ms: 이벤트의 전체 지속 시간 (밀리초)
• user_event.end_time: 이벤트 완료 시각 (타임스탬프)

추가로 start()와 end() 호출 시 제공한 커스텀 속성들도 함께 기록됩니다.

라이센스

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