@imqa/otel-web
v0.0.19
Published
IMQA distribution of OpenTelemetry for real user monitoring (RUM)
Readme
@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분)입니다.