XMLHttpRequest 계측
@imqa/instrumentation-xml-http-request
개요
XMLHttpRequest 계측은 웹 애플리케이션에서 XMLHttpRequest API를 통해 이루어지는 HTTP 요청을 자동으로 추적하고 모니터링하는 기능을 제공합니다. 전통적인 AJAX 요청의 성능, 성공/실패 상태, 응답 시간 등을 실시간으로 수집하여 레거시 네트워크 통신을 효과적으로 모니터링할 수 있습니다.
주요 기능
자동 AJAX 추적
- XMLHttpRequest 호출 자동 감지 및 추적
- 요청/응답 메타데이터 수집
- 네트워크 타이밍 정보 캡처
성능 모니터링
- 요청 지연 시간 측정
- 응답 크기 및 상태 코드 추적
- 실패한 요청에 대한 상세 정보
호환성 지원
- 레거시 브라우저 및 라이브러리 지원
- jQuery, Axios 등 XMLHttpRequest 기반 라이브러리 추적
- 분산 추적을 위한 trace 정보
계측 범위
XMLHttpRequest 계측은 다음과 같은 HTTP 요청을 추적합니다:
- AJAX 요청: 비동기 HTTP 통신
- Form 제출: XMLHttpRequest를 통한 폼 데이터 전송
- 파일 업로드: FormData 기반 파일 전송
- API 호출: RESTful API 및 서드파티 서비스 통신
주요 속성
| 속성 | 설명 |
|---|---|
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 | 사용자 세션 식별자 |
인스트루멘테이션 범위
XMLHttpRequest Telemetry는 주로 다음과 같은 인스트루멘테이션 범위를 통해 캡처됩니다:
@imqa/instrumentation-xml-http-request: XMLHttpRequest API를 통한 HTTP 요청 캡처
XMLHttpRequest 스팬
XMLHttpRequest 스팬은 웹 애플리케이션의 XMLHttpRequest를 통한 HTTP 요청과 응답을 추적합니다:
traceId: 트레이스의 고유 식별자spanId: 스팬의 고유 식별자name: HTTP 메서드 (예: "GET", "POST")kind: 스팬의 타입 (INTERNAL = 1)startTimeUnixNano: 에포크 이후의 XMLHttpRequest 시작 시간 (나노초)endTimeUnixNano: 에포크 이후의 XMLHttpRequest 완료 시간 (나노초)status: 결과 상태 (OK = 0)
XMLHttpRequest 스팬 속성
각 XMLHttpRequest 스팬은 다음과 같은 속성을 포함합니다:
| 속성 | 타입 | 설명 |
|---|---|---|
http.method | string | HTTP 메서드 (GET, POST 등) |
http.url | string | (deprecated) 요청의 전체 URL (예: "https://imqa.io/1.jpg" ) |
http.scheme | string | 프로토콜 (http, https) |
http.status_code | integer | HTTP 응답 코드 |
http.host | string | 요청에서의 호스트 이름 (예: "imqa.io") |
http.request_content_length | integer | 요청 컨텐츠의 크기 (바이트) |
http.response_content_length | integer | 응답 컨텐츠의 크기 (바이트) |
http.response_content_length_uncompressed | integer | 압축되지 않은 응답의 크기 (사용 가능한 경우) |
duration | integer | 요청 처리 시간 (나노초) |
location.href | string | 현재 페이지 URL |
environment | string | 환경 이름 |
deployment.environment | string | 배포 환경 |
screen.name | string | 화면/페이지 이름 |
screen.type | string | 화면/페이지 타입 |
session.id | string | 사용자 세션 식별자 |
url.full | string | 전체 URL (예: "https://imqa.io/1.jpg?hmac=fk" ) |
component | string | 인스트루멘테이션 컴포넌트 이름 |
span.type | string | 스팬 타입 (예: "xhr") |
사용 방법
이 스키마는 IMQA 모니터링 시스템으로 Telemetry 데이터를 처리하고 저장하기 전에 XMLHttpRequest Telemetry 데이터를 검증하는 데 사용됩니다. 이는 모든 필수 필드가 올바르게 포함되어 있는지 확인합니다.
계측 설정
(
boolean또는IMQAXMLHttpRequestInstrumentationConfig, 선택)
XMLHttpRequest 계측을 활성화하거나 비활성화합니다. true로 설정하면 XMLHttpRequest 요청이 자동으로 계측됩니다. IMQAXMLHttpRequestInstrumentationConfig을 통해 계측의 세부 설정을 조정할 수 있습니다.
자세한 계측 정보는 @imqa/instrumentation-xml-http-request 참조
interface XMLHttpRequestInstrumentationConfig extends InstrumentationConfig {
clearTimingResources?: boolean;
propagateTraceHeaderCorsUrls?: PropagateTraceHeaderCorsUrls;
ignoreUrls?: Array<string | RegExp>;
applyCustomAttributesOnSpan?: XHRCustomAttributeFunction;
ignoreNetworkEvents?: boolean;
measureRequestSize?: boolean;
advancedNetworkCapture?: () => boolean;
}
clearTimingResources: 타이밍 리소스를 초기화합니다. 기본값은false입니다.propagateTraceHeaderCorsUrls: CORS 요청에 Trace Header를 전파할 URL 목록을 지정합니다. 기본값은web.PropagateTraceHeaderCorsUrls입니다.ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있으며, 부분 일치 또는 정확히 일치하는 URL은 계측되지 않습니다.applyCustomAttributesOnSpan: Span에 사용자 정의 속성을 추가하는 함수입니다. 기본값은undefined입니다.ignoreNetworkEvents: 네트워크 이벤트를 무시합니다. 기본값은false입니다.measureRequestSize: 요청 크기를 측정합니다. 기본값은false입니다.advancedNetworkCapture: 고급 네트워크 캡처를 활성화합니다. 기본값은false입니다.
네트워크 캡처 활성화네트워크 캡처를 활성화하면 IMQA가 네트워크 요청을 수집합니다. 이 기능을 활성화 하면 성능 모니터링 및 디버깅에 유용하지만, body와 header에 담긴 민감한 정보가 함께 계측합니다. 개인 정보 보호 및 보안 요구 사항을 준수해야 합니다. 사용하기 전에 관련 법률 및 규정을 확인하세요.
예시
유효한 XMLHttpRequest Telemetry 객체는 다음과 같은 내용을 포함합니다:
- 서비스, 브라우저 및 환경을 식별하는 리소스 정보
- XMLHttpRequest를 통한 HTTP 요청과 응답을 캡처하는 스팬
- 요청 처리 시간과 응답 크기와 같은 성능 메트릭
데이터는 다양한 Telemetry 수집 및 분석 도구와 호환되는 OpenTelemetry 프로토콜 형식을 따릅니다.