@imqa/otel-web NPM

@imqa/otel-web

OpenTelemetry-based Real User Monitoring (RUM) for Web @imqa/otel-web는 웹 애플리케이션에서 RUM(Real User Monitoring)과 OpenTelemetry 기능을 통합하여 성능 모니터링 및 트레이싱을 효율적으로 수행할 수 있도록 돕는 라이브러리입니다. 이 패키지는 세션 관리, 예외 기록, 사용자 상호작용 추적 등 다양한 기능을 제공합니다.

특징

RUM 통합: 사용자 세션과 상호작용을 실시간으로 모니터링합니다.
OpenTelemetry 지원: 트레이싱 및 메트릭 수집을 위한 강력한 도구 제공.
예외 기록: 애플리케이션 내 발생하는 예외를 자동으로 기록합니다.
사용자 상호작용 추적: 클릭, 입력 등 사용자 행동을 추적하여 분석합니다.
세션 관리: 세션 ID를 관리하고, 비활동 시간을 기준으로 세션을 유지 또는 종료합니다.
유연한 구성: 다양한 설정 옵션을 통해 필요에 맞게 커스터마이즈 가능합니다.

설치

npm install @imqa/otel-web

또는

yarn add @imqa/otel-web

빠른 시작

초기화

@imqa/otel-web를 초기화하려면 Rum 객체를 설정 파일과 함께 초기화합니다.

import Rum from '@imqa/otel-web';
import { RumOtelWebConfig } from '@imqa/otel-web/types';

const config: RumOtelWebConfig = {
  serviceName: 'my-web-app',
  serviceKey: 'your-service-key',
  serviceVersion: '1.0.0',
  collectorUrl: 'https://collector.imqa.io',
  deploymentEnvironment: 'production',
  debug: true,
  ignoreUrls: [/^https:\/\/ignore\.com/, 'https://example.com/health'],
  instrumentations: {
    console: true,
    fetch: {
      propagateTraceHeaderCorsUrls: ['https://api.example.com'],
    },
    errors: true,
  },
};

Rum.init(config);

예외 기록

예외를 수동으로 기록하려면 recordException 메서드를 사용합니다.

사용자 상호작용 추적

사용자 클릭과 같은 상호작용을 자동으로 추적할 수 있습니다.

// 초기화 시 이미 instrumentations 설정을 통해 자동 추적됨
Rum.init(config);

// 또는 특정 이벤트를 수동으로 기록할 수 있습니다
Rum.addAction('button_click', { buttonId: 'submit-button' });

API 문서

`RumOtelWebType`

Rum 객체는 RumOtelWebType 인터페이스를 구현하며, 주요 메서드와 속성을 포함합니다.

주요 메서드

init(options: RumOtelWebConfig): void: @imqa/otel-web를 초기화합니다.
deinit(): void: 초기화를 해제하고 리소스를 정리합니다.
_internalInit(): void: 내부 초기화 메서드입니다.

`RumOtelWebConfig`

RumOtelWebConfig는 @imqa/otel-web 초기화 시 사용하는 설정 옵션을 정의합니다.

주요 필드

serviceName (string, 필수): 서비스의 이름을 지정합니다.
serviceKey (string, 필수): 서비스 키를 설정합니다.
serviceVersion (string, 필수): 서비스의 버전을 지정합니다.
collectorUrl (string, 선택): 텔레메트리 데이터를 전송할 콜렉터의 URL.
deploymentEnvironment (string, 선택): 배포 환경을 설정합니다 (예: production, staging).
debug (boolean, 선택): 디버그 모드를 활성화합니다.
ignoreUrls (Array<string | RegExp>, 선택): 트래킹하지 않을 URL 패턴을 지정합니다.
instrumentations (IMQAOtelWebOptionsInstrumentations, 선택): 활성화할 계측 모듈 설정.

IMQAOtelWebOptionsInstrumentations

계측 모듈의 활성화 여부 및 세부 설정을 정의하는 인터페이스입니다.

속성 목록

속성 이름	타입	설명
`console`	`boolean` 또는 `IMQAConsoleInstrumentation`	콘솔 계측을 활성화하거나 비활성화합니다. 추가 설정이 가능합니다.
`document`	`boolean` 또는 `InstrumentationConfig`	문서 로드 계측을 활성화하거나 비활성화합니다.
`errors`	`boolean`	오류 계측을 활성화하거나 비활성화합니다.
`fetch`	`boolean` 또는 `IMQAFetchInstrumentationConfig`	Fetch API 계측을 활성화하거나 비활성화합니다.
`interactions`	`boolean` 또는 `IMQAUserInteractionInstrumentationConfig`	사용자 상호작용 계측을 활성화하거나 비활성화합니다.
`longtask`	`boolean` 또는 `InstrumentationConfig`	장시간 작업 계측을 활성화하거나 비활성화합니다.
`visibility`	`boolean` 또는 `InstrumentationConfig`	페이지 가시성 계측을 활성화하거나 비활성화합니다.
`connectivity`	`boolean` 또는 `InstrumentationConfig`	네트워크 연결 상태 계측을 활성화하거나 비활성화합니다.
`postload`	`boolean` 또는 `IMQAPostDocLoadResourceInstrumentationConfig`	문서 로드 후 리소스 계측을 활성화하거나 비활성화합니다.
`socketio`	`boolean` 또는 `SocketIoClientInstrumentationConfig`	Socket.io 클라이언트 계측을 활성화하거나 비활성화합니다.
`websocket`	`boolean` 또는 `InstrumentationConfig`	WebSocket 계측을 활성화하거나 비활성화합니다.
`webvitals`	`boolean`	Web Vitals 계측을 활성화하거나 비활성화합니다.
`xhr`	`boolean` 또는 `IMQAXMLHttpRequestInstrumentationConfig`	XMLHttpRequest 계측을 활성화하거나 비활성화합니다.

속성 상세 설명

console (boolean 또는 IMQAConsoleInstrumentation, 선택)
콘솔 계측을 활성화하거나 비활성화합니다. true로 설정하면 기본 콘솔 계측이 활성화됩니다. IMQAConsoleInstrumentation 객체를 제공하여 콘솔 계측의 세부 설정을 커스터마이즈할 수 있습니다.
document (boolean 또는 InstrumentationConfig, 선택)
문서 로드 계측을 활성화하거나 비활성화합니다. true로 설정하면 문서 로드 이벤트가 계측됩니다. InstrumentationConfig을 제공하여 계측의 세부 설정을 조정할 수 있습니다.
errors (boolean, 선택)
오류 계측을 활성화하거나 비활성화합니다. true로 설정하면 전역 오류 핸들러가 활성화되어 애플리케이션에서 발생하는 오류가 자동으로 계측됩니다.
fetch (boolean 또는 IMQAFetchInstrumentationConfig, 선택)
Fetch API 계측을 활성화하거나 비활성화합니다. true로 설정하면 Fetch 요청이 자동으로 계측됩니다. IMQAFetchInstrumentationConfig을 제공하여 Fetch 계측의 세부 설정을 조정할 수 있습니다.
interactions (boolean 또는 IMQAUserInteractionInstrumentationConfig, 선택)
사용자 상호작용 계측을 활성화하거나 비활성화합니다. true로 설정하면 클릭, 입력 등 사용자 상호작용 이벤트가 자동으로 계측됩니다. IMQAUserInteractionInstrumentationConfig을 통해 상호작용 계측의 세부 설정을 커스터마이즈할 수 있습니다.
longtask (boolean 또는 InstrumentationConfig, 선택)
장시간 작업 계측을 활성화하거나 비활성화합니다. true로 설정하면 긴 시간 동안 실행되는 작업이 자동으로 계측됩니다. InstrumentationConfig을 제공하여 계측의 세부 설정을 조정할 수 있습니다.
visibility (boolean 또는 InstrumentationConfig, 선택)
페이지 가시성 계측을 활성화하거나 비활성화합니다. true로 설정하면 페이지의 가시성 상태(포그라운드/백그라운드 변화)가 자동으로 계측됩니다. InstrumentationConfig을 통해 계측의 세부 설정을 조정할 수 있습니다.
connectivity (boolean 또는 InstrumentationConfig, 선택)
네트워크 연결 상태 계측을 활성화하거나 비활성화합니다. true로 설정하면 네트워크 상태(온라인/오프라인 변화)가 자동으로 계측됩니다. InstrumentationConfig을 제공하여 계측의 세부 설정을 조정할 수 있습니다.
postload (boolean 또는 IMQAPostDocLoadResourceInstrumentationConfig, 선택)
문서 로드 후 리소스 계측을 활성화하거나 비활성화합니다. true로 설정하면 문서가 완전히 로드된 후 리소스 로딩 이벤트가 자동으로 계측됩니다. IMQAPostDocLoadResourceInstrumentationConfig을 통해 계측의 세부 설정을 커스터마이즈할 수 있습니다.
socketio (boolean 또는 SocketIoClientInstrumentationConfig, 선택)
Socket.io 클라이언트 계측을 활성화하거나 비활성화합니다. true로 설정하면 Socket.io 클라이언트의 이벤트가 자동으로 계측됩니다. SocketIoClientInstrumentationConfig을 제공하여 계측의 세부 설정을 조정할 수 있습니다.
websocket (boolean 또는 InstrumentationConfig, 선택)
WebSocket 계측을 활성화하거나 비활성화합니다. true로 설정하면 WebSocket 연결 이벤트가 자동으로 계측됩니다. InstrumentationConfig을 통해 계측의 세부 설정을 조정할 수 있습니다.
webvitals (boolean, 선택)
Web Vitals 계측을 활성화하거나 비활성화합니다. true로 설정하면 Core Web Vitals 지표가 자동으로 계측됩니다.
xhr (boolean 또는 IMQAXMLHttpRequestInstrumentationConfig, 선택)
XMLHttpRequest 계측을 활성화하거나 비활성화합니다. true로 설정하면 XMLHttpRequest 요청이 자동으로 계측됩니다. IMQAXMLHttpRequestInstrumentationConfig을 통해 계측의 세부 설정을 조정할 수 있습니다.

환경 설정

패키지는 다양한 환경 설정을 통해 유연하게 동작을 조정할 수 있습니다.

주요 설정

MaxSessionAgeMillis: 세션의 최대 유효 기간을 밀리초 단위로 설정합니다. 기본값은 4 60 60 * 1000 (4시간)입니다.
InactivityTimeoutSeconds: 비활동 상태로 간주되기까지의 시간을 초 단위로 설정합니다. 기본값은 15 * 60 (15분)입니다.
PeriodicCheckSeconds: 세션 상태를 주기적으로 확인하는 간격을 초 단위로 설정합니다. 기본값은 60 (1분)입니다.