@imqa/instrumentation-fetch

개요

@imqa/instrumentation-fetch는 IMQA 모니터링 시스템에서 Fetch API 요청 데이터를 캡처하고 보고하는 구조를 정의합니다. 이 스키마는 OpenTelemetry 형식을 사용하여 Fetch API를 통해 이루어지는 웹 애플리케이션의 HTTP 요청과 응답을 추적하도록 설계되었습니다.

스키마 구조

스키마는 JSON 문서로, JSON Schema Draft 2020-12 사양을 따릅니다. Fetch API 요청 Telemetry 데이터의 구조화된 형식을 정의하며, 다음과 같은 주요 구성요소를 포함합니다:

스팬

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

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

스팬 속성

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

| 속성 | 타입 | 설명 | |-----------|------|-------------| | 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 | 스팬 타입 xhr: IMQA 용도로 사용 | | 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 | 사용자 에이전트 문자열 |

사용 방법

계측 설정

(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입니다.
• 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를 캡처합니다.

라이센스

Copyright (c) 2024-2025 ONYCOM CO., LTD. All rights reserved.