WebSocket 계측
@imqa/instrumentation-websocket
개요
WebSocket 계측은 웹 애플리케이션에서 WebSocket 연결과 실시간 메시지 통신을 자동으로 추적하고 모니터링하는 기능을 제공합니다. WebSocket 연결 상태, 메시지 전송/수신, 연결 오류, 성능 지표 등을 실시간으로 수집하여 실시간 통신의 안정성과 성능을 모니터링할 수 있습니다.
주요 기능
연결 상태 추적
- WebSocket 연결 수립 및 종료 모니터링
- 연결 실패 및 재연결 시도 추적
- 연결 지속 시간 및 안정성 측정
메시지 통신 모니터링
- 메시지 송신/수신 이벤트 추적
- 메시지 크기 및 전송 빈도 측정
- 메시지 타입별 분류 및 분석
성능 및 오류 분석
- WebSocket 응답 시간 측정
- 연결 오류 및 타임아웃 감지
- 네트워크 상태에 따른 성능 변화 추적
계측 범위
WebSocket 계측은 다음과 같은 이벤트를 추적합니다:
- 연결 라이프사이클: 연결, 열림, 닫힘, 오류
- 메시지 통신: 텍스트/바이너리 메시지 송수신
- 프로토콜 이벤트: 핸드셰이크, 하트비트, 핑/퐁
- 오류 처리: 연결 실패, 프로토콜 오류, 네트워크 이슈
주요 속성
리소스 섹션은 서비스와 환경을 설명하는 속성을 포함합니다:
| 속성 | 설명 |
|---|---|
service.name | Telemetry를 생성하는 서비스의 이름 |
service.version | 서비스 버전 |
service.namespace | 서비스 네임스페이스 |
deployment.environment.name | 배포 환경 |
telemetry.sdk.language | Telemetry SDK의 프로그래밍 언어 |
telemetry.sdk.name | Telemetry SDK의 이름 |
telemetry.sdk.version | Telemetry SDK의 버전 |
process.runtime.name | 런타임 이름 (예: "browser") |
os.name | 운영체제 이름 |
os.version | 운영체제 버전 |
imqa.browser.device | 디바이스 타입 |
imqa.browser.name | 브라우저 이름 |
imqa.browser.version | 브라우저 전체 버전 |
imqa.browser.version_major | 브라우저 메이저 버전 |
service.key | 서비스 식별 키 |
imqa.agent.version | IMQA 에이전트 버전 |
rum.version | RUM (Real User Monitoring) 버전 |
rum.scriptInstance | RUM 스크립트 인스턴스 식별자 |
session.id | 사용자 세션 식별자 |
인스트루멘테이션 범위
WebSocket Telemetry는 주로 다음과 같은 인스트루멘테이션 범위를 통해 캡처됩니다:
@imqa/instrumentation-websocket: WebSocket 연결과 메시지 통신 캡처
WebSocket 연결 스팬
WebSocket 연결 스팬은 WebSocket 연결과 메시지를 추적합니다:
traceId: 트레이스의 고유 식별자spanId: 스팬의 고유 식별자name: 이벤트의 이름 (예: "connect", "message", "close")kind: 스팬의 타입 (INTERNAL = 1)startTimeUnixNano: 에포크 이후의 WebSocket 이벤트 시작 시간 (나노초)endTimeUnixNano: 에포크 이후의 WebSocket 이벤트 종료 시간 (나노초)status: 결과 상태 (OK = 0)
WebSocket 스팬 속성
각 WebSocket 스팬은 다음과 같은 속성을 포함합니다:
| 속성 | 타입 | 설명 |
|---|---|---|
websocket.url | string | WebSocket 연결 URL |
websocket.event_type | string | 이벤트의 타입 (connect, message, close 등) |
websocket.message_type | string | 메시지의 타입 (text, binary) |
websocket.message_size | integer | 메시지의 크기 (바이트) |
websocket.connection_status | string | 연결 상태 (open, closing, closed) |
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 | 스팬 타입 (예: "websocket") |
사용 방법
이 스키마는 IMQA 모니터링 시스템으로 Telemetry 데이터를 처리하고 저장하기 전에 WebSocket 연결과 메시지를 위한 Telemetry 데이터를 검증하는 데 사용됩니다. 이는 모든 필수 필드가 올바르게 포함되어 있는지 확인합니다.
계측 설정
(
boolean또는IMQAWebSocketInstrumentationConfig, 선택)
WebSocket 계측을 활성화하거나 비활성화합니다. true로 설정하면 WebSocket 연결 이벤트가 자동으로 계측됩니다. IMQAWebSocketInstrumentationConfig을 통해 계측의 세부 설정을 조정할 수 있습니다.
interface IMQAWebSocketInstrumentationConfig extends InstrumentationConfig {
ignoreUrls?: (string | RegExp)[];
}
ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있으며, 부분 일치 또는 정확히 일치하는 URL은 계측되지 않습니다.
예시
유효한 WebSocket Telemetry 객체는 다음과 같은 내용을 포함합니다:
- 서비스, 브라우저 및 환경을 식별하는 리소스 정보
- WebSocket 연결과 메시지를 캡처하는 WebSocket 스팬
- 메시지 크기와 연결 상태와 같은 통신 메트릭
데이터는 다양한 Telemetry 수집 및 분석 도구와 호환되는 OpenTelemetry 프로토콜 형식을 따릅니다.