npm package: @imqa/otel-web
Description: IMQA distribution of OpenTelemetry for real user monitoring (RUM)
Latest version: 0.0.19

# @imqa/otel-web

[![NPM Published Version][npm-img]][npm-url]


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

## 목차

- [특징](#특징)
- [설치](#설치)
- [빠른 시작](#빠른-시작)
  - [초기화](#초기화)
  - [예외 기록](#예외-기록)
  - [사용자 상호작용 추적](#사용자-상호작용-추적)
- [API 문서](#api-문서)
  - [RumOtelWebType](#rumotelwebtype)
  - [RumOtelWebConfig](#rumotelwebconfig)
  - [IMQAOtelWebOptionsInstrumentations](#imqaootelweboptionsinstrumentations)
- [환경 설정](#환경-설정)


## 특징

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

## 설치

```bash
npm install @imqa/otel-web
```

또는

```bash
yarn add @imqa/otel-web
```

## 빠른 시작

### 초기화

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

```typescript
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` 메서드를 사용합니다.

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

```ts
// 초기화 시 이미 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분)입니다.


[discussions-url]: https://github.com/onycom-imqa/imqa-js/discussions
[npm-url]: https://www.npmjs.com/package/@imqa/otel-web
[npm-img]: https://badge.fury.io/js/@imqa%2Fotel-web.svg