Web Vitals
Sophonz Browser SDK가 Core Web Vitals를 어떤 형태로 내보내는지 — browser.web_vital Span·이벤트·히스토그램과 그 속성, 그리고 기존 web-vital.* 이름을 대체한 속성 변경을 설명합니다.
Web Vitals 계측은 Google의 Core Web Vitals를 수집해 OpenTelemetry의 browser.web_vital 시맨틱 컨벤션으로 내보냅니다. 이 문서는 실제로 콜렉터에 도달하는 데이터의 레퍼런스이자, 기존 속성 이름을 대체한 변경 사항을 정리한 문서입니다.
기본값은 활성화입니다. 끄려면 webVitals를 참고하세요.
호환성 변경: web-vital.*가 browser.web_vital.*로 대체되었습니다
WARNING — 기존 속성 이름으로 작성한 쿼리는 아무 결과도 반환하지 않습니다
SDK는 더 이상 web-vital.name, web-vital.value, web-vital.delta, web-vital.rating, web-vital.navigation_type을 내보내지 않습니다. 이 키를 읽는 대시보드, 쿼리, 알림, 내보내기는 아래의 browser.web_vital.* 이름으로 수정해야 합니다. 두 이름을 함께 내보내는 전환 기간은 없습니다.
세 가지가 동시에 바뀌므로 쿼리를 수정할 때 모두 반영해야 합니다.
| 기존 | 변경 | 참고 |
|---|---|---|
web-vital.name | browser.web_vital.name | 값이 소문자로 바뀌었습니다. LCP가 아니라 lcp입니다 |
web-vital.value | browser.web_vital.value | |
web-vital.delta | browser.web_vital.delta | |
web-vital.rating | browser.web_vital.rating | |
web-vital.navigation_type | browser.web_vital.navigation_type | 브라우저가 값을 제공하지 않으면 속성 자체가 붙지 않습니다 |
| — | browser.web_vital.id | 새로 추가되었습니다. 명세상 필수이며 중복 제거 키로 사용합니다 |
바뀌지 않은 것도 있습니다. Span은 그대로 발생하며 app.span.type = "webvitals"도 유지됩니다. Span 타입으로 웹 바이탈 데이터를 선택하는 쿼리는 그대로 동작합니다.
무엇이 전송되는가
하나의 지표가 보고되면 최대 세 가지 신호가 만들어집니다.
이벤트
정식 표현입니다. OpenTelemetry 시맨틱 컨벤션은 browser.web_vital을 이벤트, 즉 로그 레코드로 정의합니다. 웹 바이탈은 지속 시간이 있는 작업이 아니라 한 시점의 측정값이고, 메트릭으로 만들면 웹 바이탈을 쓸모 있게 만드는 세션 정보와 귀속 정보를 잃기 때문입니다.
eventName은browser.web_vital입니다. 속성이 아니라 로그 레코드의 네이티브 필드입니다.- 레코드는 아래의 Span에 바인딩되므로 동일한 Trace ID와 Span ID를 가집니다.
- 속성:
browser.web_vital.name,.value,.delta,.id,.rating, 값이 있을 때의.navigation_type, 그리고app.screen.name. session.id와sophonz.browser.device는 레코드에 중복해서 붙이지 않습니다. 리소스 속성이라 SDK가 보내는 모든 로그 레코드에 이미 포함되어 있습니다.
Span
세션 타임라인이 app.span.type으로 데이터를 선택하기 때문에 그대로 유지됩니다.
- Span 이름:
@sophonz/instrumentation-webvitals - 시작 시각과 종료 시각이 같은 0초 Span입니다.
- 속성:
app.span.type = "webvitals", 6개의browser.web_vital.*속성, 그리고 SDK의 모든 Span이 공통으로 갖는 화면 이름, 화면 타입, 세션 ID,url.full.
히스토그램
지표 값을 기록하는 webvitals 메트릭 계기입니다.
- 속성:
app.span.type,browser.web_vital.name,browser.web_vital.delta,browser.web_vital.rating, 값이 있을 때의browser.web_vital.navigation_type browser.web_vital.id는 의도적으로 제외했습니다. 측정마다 고유한 값이라 데이터 포인트마다 별도의 시계열이 만들어지기 때문입니다.
속성
| 속성 | 타입 | 설명 |
|---|---|---|
browser.web_vital.name | string | cls, fcp, inp, lcp, ttfb 중 하나. 소문자입니다 |
browser.web_vital.value | number | 측정값 |
browser.web_vital.delta | number | 같은 지표의 직전 보고값 대비 변화량 |
browser.web_vital.id | string | 측정마다 고유한 값. 중복 제거에 사용합니다 |
browser.web_vital.rating | string | good, needs-improvement, poor 중 하나 |
browser.web_vital.navigation_type | string | navigate, reload, back-forward, back-forward-cache, prerender, restore 중 하나. 브라우저가 값을 제공하지 않으면 붙지 않습니다 |
수집하는 지표
cls, fcp, inp, lcp, ttfb를 수집하며, 각 지표는 페이지 로드당 한 번만 보고됩니다.
FID는 수집하지 않습니다. INP로 대체된 지표이며 SDK가 관측하지 않습니다.
집계할 때
이 데이터로 패널을 만들 때 유의할 점은 두 가지입니다.
평균이 아니라 p75를 사용하세요. Google은 Core Web Vitals 기준값(LCP 2.5초, INP 200ms, CLS 0.1)을 75번째 백분위수로 정의합니다. 그리고 p75는 합성되지 않으므로, 화면별 백분위수를 다시 합치지 말고 항상 원본 이벤트에서 계산해야 합니다.
browser.web_vital.id로 중복을 제거하세요. 지표는 페이지 로드당 한 번 보고되지만 bfcache 복원과 SPA 라우트 전환은 새 ID를 만들어냅니다. ID로 묶은 뒤 가장 마지막 값을 취하는 것이 이 속성의 용도입니다.
browser.web_vital.rating은 백분위수보다 다루기 쉬운 대안입니다. good 비율은 어떤 기준으로 묶어도 저렴하게 합산되지만 백분위수는 그렇지 않습니다.