문서 로드 계측
@imqa/instrumentation-document-load
개요
문서 로드 계측은 웹 페이지의 초기 로딩 프로세스를 자동으로 추적하고 분석하는 기능을 제공합니다. HTML 문서 로딩부터 DOM 구성, 리소스 로딩까지의 전체 과정을 실시간으로 모니터링하여 페이지 로딩 성능을 최적화할 수 있는 데이터를 제공합니다.
주요 기능
로딩 단계별 추적
- HTML 문서 다운로드 시간 측정
- DOM 파싱 및 구성 시간 추적
- 리소스 로딩 병목 지점 식별
- 개별 리소스별 타이밍 정보 수집
성능 메트릭 수집
- Navigation Timing API 기반 정밀 측정
- Resource Timing API를 통한 리소스별 성능 데이터
- 서버 응답 시간 및 네트워크 지연
- Server-Timing 헤더 정보 자동 캡처
- 브라우저 렌더링 성능 분석
서버 추적 통합
- Server-Timing 헤더를 통한 분산 추적
- 서버 측과 클라이언트 측 성능 데이터 연결
- TraceParent 정보 자동 추출 및 연결
리소스 필터링
- 특정 리소스 타입 제외 (beacon, fetch, XMLHttpRequest)
- URL 패턴 기반 리소스 무시
- 불필요한 계측 오버헤드 최소화
최적화 인사이트
- 로딩 성능 개선점 도출
- 리소스 우선순위 최적화 지원
- 사용자 경험 개선을 위한 데이터
- 화면 크기 및 참조 페이지 정보
계측 범위
문서 로드 계측은 다음과 같은 로딩 이벤트를 추적합니다:
1. 문서 로드 (documentLoad)
- 네비게이션 시작: 페이지 요청 시작 시점
- 서버 응답: HTML 문서 다운로드 완료
- DOM 파싱: HTML 파싱 및 DOM 트리 구성
- 이벤트 처리: DOMContentLoaded, Load 이벤트
- 추가 메타데이터:
- 문서 참조자 (referrer)
- 화면 해상도 (screen.xy)
- 사용자 에이전트
2. 문서 가져오기 (documentFetch)
- 초기 HTML 문서 다운로드
- Server-Timing 헤더 정보
- TraceParent를 통한 서버 추적 연결
- HTTP 메서드 (기본값: GET)
3. 리소스 가져오기 (resourceFetch)
다음 리소스 타입을 추적합니다:
- CSS 스타일시트
- JavaScript 파일
- 이미지 (PNG, JPG, SVG 등)
- 폰트 파일
- 기타 리소스
다음 리소스 타입은 제외됩니다:
beacon: 분석 비콘fetch: Fetch API 호출 (별도 계측)xmlhttprequest: XHR 요청 (별도 계측)
주요 속성
리소스 속성
리소스 섹션은 서비스와 환경을 설명하는 속성을 포함합니다:
| 속성 | 설명 |
|---|---|
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 | 사용자 세션 식별자 |
인스트루멘테이션 범위
문서 로드 Telemetry는 주로 다음과 같은 인스트루멘테이션 범위를 통해 캡처됩니다:
@imqa/instrumentation-document-load: 웹 페이지 문서 로드 프로세스 캡처
DocumentLoad Telemetry는 주로 @opentelemetry/instrumentation-document-load 인스트루멘테이션 범위를 통해 캡처됩니다.
문서 로드 스팬
문서 로드 인스트루멘테이션은 여러 유형의 스팬을 생성합니다:
메인 문서 로드 스팬
전체 페이지 로딩 프로세스를 나타내는 주 스팬입니다:
traceId: 트레이스의 고유 식별자spanId: 스팬의 고유 식별자name: "documentLoad"kind: 스팬의 타입 (INTERNAL = 1)startTimeUnixNano: 에포크 이후의 페이지 로드 시작 시간 (나노초)endTimeUnixNano: 에포크 이후의 페이지 로드 종료 시간 (나노초)status: 결과 상태 (OK = 0, ERROR = 1, UNSET = 2)
문서 가져오기(documentFetch) 스팬
초기 HTML 문서 가져오기 작업을 나타내는 자식 스팬입니다:
name: "documentFetch"parentSpanId: 부모 documentLoad 스팬의 ID
리소스 가져오기(resourceFetch) 스팬
스크립트, 스타일시트 등 다양한 페이지 리소스의 가져오기를 나타내는 여러 자식 스팬:
name: "resourceFetch"parentSpanId: 부모 documentLoad 스팬의 ID
스팬 타입별 속성
1. 문서 로드 (documentLoad) 스팬 속성
메인 문서 로드 스팬은 다음 속성을 포함합니다:
| 속성 | 타입 | 설명 |
|---|---|---|
imqa.rum.component | string | 계측 컴포넌트 이름 |
imqa.span.type | string | "render" (메인 문서 로드) |
location.href | string | 현재 페이지 URL |
screen.name | string | 화면/페이지 이름 |
screen.type | string | 화면/페이지 타입 |
session.id | string | 사용자 세션 식별자 |
environment | string | 환경 이름 |
deployment.environment | string | 배포 환경 |
imqa.document.referrer | string | 이전 페이지 URL (존재하는 경우) |
imqa.document.screen.xy | string | 화면 해상도 (예: "1920x1080") |
url.full | string | 요청 전체 URL |
http.url | string | (deprecated) 문서 URL |
http.response_content_length | integer | 응답 컨텐츠 크기 (바이트) |
http.request.method | string | HTTP 메서드 (기본값: "GET") |
http.scheme | string | 프로토콜 (예: "https") |
http.host | string | 호스트 이름 |
http.user_agent | string | 브라우저 사용자 에이전트 |
2. 문서 가져오기 (documentFetch) 스팬 속성
초기 HTML 문서 가져오기 스팬은 다음 속성을 포함합니다:
| 속성 | 타입 | 설명 |
|---|---|---|
imqa.rum.component | string | 계측 컴포넌트 이름 |
imqa.span.type | string | "render_child" |
http.request.method | string | "GET" |
location.href | string | 현재 페이지 URL |
screen.name | string | 화면/페이지 이름 |
screen.type | string | 화면/페이지 타입 |
session.id | string | 사용자 세션 식별자 |
environment | string | 환경 이름 |
deployment.environment | string | 배포 환경 |
Server-Timing 연결:
- Navigation Timing API의
serverTiming정보 자동 추출 - TraceParent 정보를 통한 분산 추적 연결
3. 리소스 가져오기 (resourceFetch) 스팬 속성
개별 리소스 로드 스팬은 다음 속성을 포함합니다:
| 속성 | 타입 | 설명 |
|---|---|---|
imqa.rum.component | string | 계측 컴포넌트 이름 |
imqa.span.type | string | "render_child" |
http.request.method | string | "GET" |
url.full | string | 리소스의 전체 URL |
http.url | string | 리소스 URL |
http.response_content_length | integer | 리소스 크기 (바이트) |
location.href | string | 현재 페이지 URL |
screen.name | string | 화면/페이지 이름 |
screen.type | string | 화면/페이지 타입 |
session.id | string | 사용자 세션 식별자 |
TraceParent 연결:
- Performance Entry의 Server-Timing 정보에서 자동 추출
- 서버 측 추적과의 자동 연결
이벤트
문서 로드 스팬은 페이지 로드 프로세스의 주요 마일스톤을 나타내는 다양한 이벤트를 포함합니다:
문서 로드(doucmentLoad) 이벤트
| 이벤트 | 설명 |
|---|---|
fetchStart | 가져오기 프로세스 시작 |
unloadEventStart | 이전 페이지의 언로드 이벤트 시작 |
unloadEventEnd | 이전 페이지의 언로드 이벤트 종료 |
domInteractive | DOM이 상호작용 준비 완료 |
domContentLoadedEventStart | DOMContentLoaded 이벤트 시작 |
domContentLoadedEventEnd | DOMContentLoaded 이벤트 종료 |
domComplete | DOM 구조화 완료 |
loadEventStart | 로드 이벤트 시작 |
loadEventEnd | 로드 이벤트 종료 |
리소스 가져오기(resourceFetch) 이벤트
| 이벤트 | 설명 |
|---|---|
fetchStart | 리소스 가져오기 시작 |
domainLookupStart | DNS 조회 시작 |
domainLookupEnd | DNS 조회 종료 |
connectStart | 서버 연결 시작 |
connectEnd | 서버 연결 종료 |
requestStart | 서버로 요청 전송 |
responseStart | 첫 번째 바이트 응답 수신 |
responseEnd | 마지막 바이트 응답 수신 |
사용 방법
이 스키마는 IMQA 모니터링 시스템으로 Telemetry 데이터를 처리하고 저장하기 전에 문서 로드 Telemetry 데이터를 검증하는 데 사용됩니다. 이는 다음과 같은 주요 메트릭을 모니터링하여 페이지 로드 성능을 추적하는 데 도움이 됩니다:
- 전체 페이지 로드 시간
- 문서 가져오기 시간
- 리소스 가져오기 시간
- DOM 처리 시간
계측 설정
(
boolean또는IMQADocLoadInstrumentationConfig, 선택)
문서 로드 계측을 활성화하거나 비활성화합니다. true로 설정하면 문서 로드 이벤트가 계측됩니다. IMQADocLoadInstrumentationConfig을 제공하여 계측의 세부 설정을 조정할 수 있습니다.
interface IMQADocLoadInstrumentationConfig extends InstrumentationConfig {
ignoreUrls?: (string | RegExp)[];
screenNameOption?: ScreenNameOption;
}
설정 옵션:
-
ignoreUrls((string | RegExp)[], optional): 계측하지 않을 리소스 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있으며, 패턴과 일치하는 리소스는 계측되지 않습니다. -
screenNameOption(ScreenNameOption, optional): 화면 이름 생성 방식을 지정합니다. 이 설정은screen.name과screen.type속성 생성에 영향을 줍니다.
자동 제외되는 리소스 타입:
다음 initiatorType을 가진 리소스는 자동으로 계측에서 제외됩니다:
beacon: 분석 비콘fetch: Fetch API 호출xmlhttprequest: XMLHttpRequest 호출
이러한 리소스들은 별도의 계측 모듈에서 처리됩니다.
사용 예시
기본 설정
문서 로드 계측은 기본적으로 활성화되며 추가 설정 없이 사용할 수 있습니다:
IMQA.init({
collectorUrl: 'https://collector.example.com',
serviceName: 'my-web-app',
serviceKey: 'your-service-key',
// 문서 로드 계측은 기본적으로 활성화됨
});
리소스 URL 필터링
특정 URL 패턴의 리소스를 계측에서 제외할 수 있습니다:
IMQA.init({
collectorUrl: 'https://collector.example.com',
serviceName: 'my-web-app',
serviceKey: 'your-service-key',
instrumentations: {
documentLoad: {
enabled: true,
// CDN 리소스 제외
ignoreUrls: [
/cdn\.example\.com/,
'https://analytics.example.com',
/google-analytics/
]
}
}
});
화면 이름 설정
화면 이름 생성 방식을 커스터마이징할 수 있습니다:
IMQA.init({
collectorUrl: 'https://collector.example.com',
serviceName: 'my-web-app',
serviceKey: 'your-service-key',
instrumentations: {
documentLoad: {
enabled: true,
screenNameOption: {
screenNameType: 'routeOnly', // 또는 'full', 'pathOnly'
urlWithSearchParams: false
}
}
}
});
고급 기능
Server-Timing 헤더 통합
문서 가져오기 시 서버가 Server-Timing 헤더를 제공하면 자동으로 캡처됩니다:
HTTP/1.1 200 OK
Server-Timing: db;dur=53, app;dur=47.2, total;dur=100.2
Server-Timing: traceparent;desc="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
이 정보는 다음과 같이 활용됩니다:
- 서버 측 성능 메트릭 자동 수집
- TraceParent를 통한 분산 추적 연결
- 클라이언트-서버 간 성능 상관관계 분석
TraceParent 자동 추출
Performance Entry에서 TraceParent 정보를 자동으로 추출하여 서버 측 추적과 연결합니다:
// documentFetch 및 resourceFetch 스팬에서 자동 처리
captureTraceParentFromPerformanceEntries(entries, span);
이를 통해:
- 서버 측 트레이스와 클라이언트 측 트레이스 자동 연결
- 전체 요청 흐름의 종단 간 가시성 확보
- 서버와 클라이언트 성능 병목 구간 식별
리소스 타입 자동 필터링
다음 initiatorType의 리소스는 자동으로 제외됩니다:
const excludedInitiatorTypes = ['beacon', 'fetch', 'xmlhttprequest'];
제외 이유:
beacon: 분석/추적 목적의 작은 요청으로, 별도 모니터링 불필요fetch:@imqa/instrumentation-fetch에서 더 상세하게 추적xmlhttprequest:@imqa/instrumentation-xml-http-request에서 더 상세하게 추적
추가 문서 메타데이터
메인 문서 로드 스팬에 유용한 메타데이터가 자동으로 추가됩니다:
// 이전 페이지 정보
if (document.referrer && document.referrer !== '') {
span.setAttribute('imqa.document.referrer', document.referrer);
}
// 화면 해상도
if (window.screen) {
span.setAttribute(
'imqa.document.screen.xy',
window.screen.width + 'x' + window.screen.height
);
}
이 정보를 통해:
- 사용자 유입 경로 분석
- 화면 크기별 성능 분석
- 디바이스 타입별 최적화
Performance Timeline 활용
Navigation Timing API와 Resource Timing API를 활용하여 상세한 타이밍 정보를 수집합니다:
// Navigation Timing 이벤트
{
fetchStart: 1234567890,
domainLookupStart: 1234567891,
domainLookupEnd: 1234567892,
connectStart: 1234567892,
connectEnd: 1234567895,
requestStart: 1234567895,
responseStart: 1234567900,
responseEnd: 1234567950,
domInteractive: 1234568000,
domContentLoadedEventStart: 1234568100,
domContentLoadedEventEnd: 1234568110,
domComplete: 1234568200,
loadEventStart: 1234568200,
loadEventEnd: 1234568210
}
스팬 계층 구조
문서 로드 계측은 다음과 같은 계층 구조의 스팬을 생성합니다:
documentLoad (render)
├── documentFetch (render_child)
│ └── Server-Timing 정보
│ └── TraceParent 연결
├── resourceFetch (render_child) - style.css
│ └── TraceParent 연결 (가능한 경우)
├── resourceFetch (render_child) - script.js
├── resourceFetch (render_child) - logo.png
└── resourceFetch (render_child) - font.woff2
각 스팬은 다음을 포함합니다:
- 시작/종료 타임스탬프
- DNS 조회, 연결, 요청/응답 타이밍
- 리소스 크기
- 화면 및 세션 정보
성능 분석 시나리오
1. 느린 초기 로딩 분석
// documentLoad 스팬 분석
{
name: "documentLoad",
startTime: 0,
duration: 3500, // 3.5초
events: {
domInteractive: 1200,
domContentLoadedEventEnd: 2000,
loadEventEnd: 3500
}
}
분석:
- DOM 준비까지 1.2초: 적절함
- DOMContentLoaded까지 2초: 추가 800ms 소요 - 동기 스크립트 확인 필요
- 전체 로드 3.5초: 추가 1.5초 소요 - 이미지/리소스 최적화 필요
2. 리소스 로딩 병목 식별
// resourceFetch 스팬들 분석
[
{ name: "style.css", duration: 50, size: 24000 },
{ name: "app.js", duration: 500, size: 2400000 }, // 병목!
{ name: "vendor.js", duration: 300, size: 1200000 },
{ name: "hero.jpg", duration: 800, size: 1500000 } // 병목!
]
개선 방안:
app.js: 코드 분할 또는 압축 개선hero.jpg: 이미지 최적화, WebP 포맷 사용, lazy loading
3. 서버 응답 시간 분석
// documentFetch 스팬의 Server-Timing
{
serverTiming: [
{ name: "db", duration: 53 },
{ name: "app", duration: 47.2 },
{ name: "total", duration: 100.2 }
]
}
분석:
- 서버 측 처리: 100ms (양호)
- 데이터베이스 쿼리: 53ms (전체의 53%)
- 필요 시 쿼리 최적화 고려
주의사항
Performance API 의존성
- 이 계측은 브라우저의 Performance API에 의존합니다
- 오래된 브라우저에서는 일부 메트릭이 누락될 수 있습니다
- Navigation Timing Level 2를 지원하는 브라우저 권장
리소스 제외
fetch와xmlhttprequest는 자동으로 제외됩니다- 이들은 별도의 전문 계측 모듈에서 더 상세하게 추적됩니다
- 중복 계측을 방지하여 오버헤드 최소화
CORS 제한
- 크로스 오리진 리소스의 경우 타이밍 정보가 제한될 수 있습니다
Timing-Allow-Origin헤더를 설정하여 상세 타이밍 정보 활성화 가능
성능 영향
- 계측 자체의 성능 영향은 미미합니다
- Performance API는 브라우저에서 이미 데이터를 수집하므로 추가 오버헤드 최소
- 리소스가 많은 페이지에서도 안정적으로 동작
Telemetry 데이터 구조
유효한 문서 로드 Telemetry 객체는 다음과 같은 내용을 포함합니다:
리소스 정보
- 서비스, 브라우저 및 환경을 식별
- 세션 및 사용자 컨텍스트
Span 데이터
- 메인 documentLoad 스팬: 전체 페이지 로드 프로세스
- documentFetch 스팬: 초기 HTML 문서 가져오기
- resourceFetch 스팬들: 개별 리소스 로딩
타이밍 정보
- Navigation Timing API의 모든 이벤트
- 각 리소스의 상세 타이밍
- Server-Timing 헤더 정보
연결 정보
- TraceParent를 통한 서버 추적 연결
- 부모-자식 스팬 관계
- 세션 및 화면 정보
데이터는 다양한 Telemetry 수집 및 분석 도구와 호환되는 OpenTelemetry 프로토콜 형식을 따릅니다.