Fetch API 계측

@imqa/instrumentation-fetch

NPM Last Update NPM Unpacked Size npm package minimized gzipped size NPM Downloads NPM Type Definitions

개요

Fetch API 계측은 웹 애플리케이션에서 Fetch API를 통해 이루어지는 HTTP 요청을 자동으로 추적하고 모니터링하는 기능을 제공합니다. API 호출의 성능, 성공/실패 상태, 응답 시간 등을 실시간으로 수집하여 네트워크 통신 상태를 모니터링할 수 있습니다.

주요 기능

자동 요청 추적

Fetch API 호출 자동 감지 및 추적
요청/응답 메타데이터 수집
네트워크 타이밍 정보 캡처

성능 모니터링

요청 지연 시간 측정
응답 크기 및 상태 코드 추적
실패한 요청에 대한 상세 정보

컨텍스트 정보

요청 헤더 및 본문 정보 (설정 시)
사용자 세션과 연계된 추적
분산 추적을 위한 trace 정보

계측 범위

Fetch API 계측은 다음과 같은 HTTP 요청을 추적합니다:

REST API 호출: GET, POST, PUT, DELETE 등 모든 HTTP 메서드
GraphQL 요청: GraphQL 엔드포인트 호출
파일 업로드/다운로드: 멀티파트 폼 데이터 및 바이너리 전송
외부 서비스 호출: 서드파티 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`	사용자 세션 식별자

인스트루멘테이션 범위

Fetch API Telemetry는 주로 다음과 같은 인스트루멘테이션 범위를 통해 캡처됩니다:

@imqa/instrumentation-fetch: Fetch API를 통한 HTTP 요청 캡처

Fetch API 스팬

각 스팬은 단일 Fetch API 요청/응답을 나타내며, 다음과 같은 내용을 포함합니다:

traceId: 트레이스의 고유 식별자
spanId: 스팬의 고유 식별자
parentSpanId: 부모 스팬의 식별자 (적용될 경우)
name: 작업의 이름
kind: 스팬의 타입 (CLIENT = 3)
startTimeUnixNano: 에포크 이후의 Fetch 요청 시작 시간 (나노초)
endTimeUnixNano: 에포크 이후의 Fetch 요청 완료 시간 (나노초)
status: 결과 상태 (OK = 0, ERROR = 1, UNSET = 2)

Fetch API 스팬 속성

각 Fetch API 스팬은 다음과 같은 속성을 포함합니다:

속성	타입	설명
`http.method`	`string`	HTTP 메서드 (`GET`, `POST` 등)
`http.url`	`string`(deprecated)	요청의 전체 URL (예: "https://imqa.io/1.jpg" )
`location.href`	`string`	현재 페이지 URL (예: "https://imqa.io/test" )
`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`	스팬 타입 (예: "fetch")
`http.response_content_length`	integer	응답 본문의 크기 (바이트)
`http.status_code`	`integer`	HTTP 상태 코드
`http.status_text`	`string`	HTTP 상태 텍스트
`http.host`	`string`	요청에서의 호스트 이름 (예: "imqa.io")
`http.scheme`	`string`	프로토콜 (`http`, `https`)
`http.user_agent`	`string`	사용자 에이전트 문자열

사용 방법

이 스키마는 IMQA 모니터링 시스템으로 Telemetry 데이터를 처리하고 저장하기 전에 Fetch API Telemetry 데이터를 검증하는 데 사용됩니다. 이는 모든 필수 필드가 올바르게 포함되어 있는지 확인합니다.

계측 설정

(boolean 또는 IMQAFetchInstrumentationConfig, 선택)

Fetch API 계측을 활성화하거나 비활성화합니다. true로 설정하면 Fetch 요청이 자동으로 계측됩니다. IMQAFetchInstrumentationConfig을 제공하여 Fetch 계측의 세부 설정을 조정할 수 있습니다.

type IMQAFetchInstrumentationConfig = {
  advancedNetworkCapture?: () => boolean;
  clearTimingResources?: boolean;
  propagateTraceHeaderCorsUrls?: web.PropagateTraceHeaderCorsUrls;
  ignoreUrls?: Array<string | RegExp>;
  applyCustomAttributesOnSpan?: FetchCustomAttributeFunction;
  ignoreNetworkEvents?: boolean;
  measureRequestSize?: boolean;
}

advancedNetworkCapture: 고급 네트워크 캡처를 활성화합니다. 기본값은 false입니다.

네트워크 캡처 활성화

네트워크 캡처를 활성화하면 IMQA가 네트워크 요청을 수집합니다. 이 기능을 활성화 하면 성능 모니터링 및 디버깅에 유용하지만, body와 header에 담긴 민감한 정보가 함께 계측합니다. 개인 정보 보호 및 보안 요구 사항을 준수해야 합니다. 사용하기 전에 관련 법률 및 규정을 확인하세요.

clearTimingResources: 타이밍 리소스를 초기화합니다. 기본값은 false입니다.
propagateTraceHeaderCorsUrls: CORS 요청에 Trace Header를 전파할 URL 목록을 지정합니다. 기본값은 web.PropagateTraceHeaderCorsUrls입니다.
ignoreUrls: 계측하지 않을 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있으며, 부분 일치 또는 정확히 일치하는 URL은 계측되지 않습니다.
applyCustomAttributesOnSpan: Span에 사용자 정의 속성을 추가하는 함수입니다. 기본값은 undefined입니다.
ignoreNetworkEvents: 네트워크 이벤트를 무시합니다. 기본값은 false입니다.
measureRequestSize: 요청 크기를 측정합니다. 기본값은 false입니다.

예시

유효한 Fetch Telemetry 객체는 다음과 같은 내용을 포함합니다:

서비스, 브라우저 및 환경을 식별하는 리소스 정보
Fetch API 요청을 나타내는 하나 이상의 스팬
각 스팬은 요청 메서드, URL, 타이밍, 응답 상태에 대한 상세 정보를 포함

데이터는 다양한 Telemetry 수집 및 분석 도구와 호환되는 OpenTelemetry 프로토콜 형식을 따릅니다. XMLHttpRequest와 달리, Fetch API는 HTTP 요청을 위한 더 현대적인 프로미스 기반 인터페이스를 제공하며, 이 스키마는 이러한 요청에 대한 관련 Telemetry를 캡처합니다.

수정하기