이 가이드에서는 일련의 웹 성능 데이터를 제공하는 Chrome UX Report (CrUX) History API 엔드포인트를 소개합니다. 이 데이터는 매주 업데이트되며 약 6개월분의 기록을 확인할 수 있습니다. 일주일 간격으로 25개의 데이터 포인트가 표시됩니다.
기존 CrUX API 엔드포인트의 일일 업데이트와 함께 사용하면 이제 최신 데이터와 이전에 발생한 작업을 모두 빠르게 확인할 수 있으므로 시간 경과에 따른 웹페이지 변경사항을 확인할 수 있는 강력한 도구가 됩니다.
일일 CrUX API 쿼리
CrUX API에 관한 이전 도움말을 요약하면 다음과 같은 방법으로 특정 출처의 필드 데이터에 대한 스냅샷을 가져올 수 있습니다.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
이 스냅샷에는 특정 28일 수집 기간(이 경우 2022년 12월 27일~2023년 1월 23일)의 히스토그램 밀도 값과 백분위수 값이 포함됩니다.
CrUX History API 쿼리
기록 엔드포인트를 호출하려면 URL의 queryRecord를 curl 명령어에서 queryHistoryRecord로 변경합니다. 이전 호출과 동일한 CrUX API 키를 사용하면 됩니다.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
응답의 전반적인 형태는 비슷하지만, 데이터가 훨씬 더 많습니다. 이제 단일 데이터 포인트 대신 75번째 백분위수 (p75) 및 히스토그램 밀도 값을 포함하는 필드에 시계열이 표시됩니다.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
이 예에서 콘텐츠가 포함된 최대 페인트 (LCP) 측정항목의 0~2, 500밀리초 버킷에 대한 densities 시계열은 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].입니다. 각 밀도는 상응하는 collectionPeriods 항목에서 관찰되었습니다. 예를 들어 5번째 밀도인 0.9183은 2022년 9월 3일에 끝나는 5번째 수집 기간의 밀도였고, 0.9187은 그다음 주에 끝나는 기간의 밀도였습니다.
즉, https://web.dev에 대한 예시의 마지막 시계열 항목을 해석한 결과, 2022년 8월 14일부터 2022년 9월 10일까지 페이지 로드의 91.87%는 LCP 값이 2500ms보다 작고 5.27%는 2500ms와 4000ms5,
마찬가지로 p75 값에 대한 시계열이 있습니다. 2022년 8월 14일부터 2022년 9월 10일까지의 LCP p75는 1377였습니다. 즉, 이 수집 기간 동안 사용자 환경의 75% 에서 LCP가 1, 377ms 미만이고 사용자 환경의 25% 에서 LCP가 1, 377ms를 넘었습니다.
이 예에서는 6개의 시계열 항목과 수집 기간만 나열하지만 API의 응답은 25개의 시계열 항목을 제공합니다. 이러한 각 수집 기간의 종료일은 7일 간격의 토요일이므로 여기에는 6개월이 포함됩니다.
주어진 응답에서 히스토그램 빈 밀도와 p75 값의 시계열 길이는 collectionPeriods 필드의 배열 길이와 정확히 일치합니다. 이러한 배열의 색인을 기반으로 일대일 대응이 이루어집니다.
페이지 수준 데이터 쿼리
출처 수준 데이터뿐만 아니라 CrUX History API를 사용하면 이전 페이지 수준 데이터에도 액세스할 수 있습니다. 이전에는 BigQuery의 CrUX 데이터 세트 (또는 CrUX 대시보드 사용)를 사용해 출처 수준의 데이터를 사용할 수 있었지만, 페이지 수준의 과거 데이터는 사이트에서 데이터를 직접 수집하고 저장한 경우에만 사용할 수 있었습니다. 이제 새 API를 통해 이전 페이지 수준 데이터를 활용할 수 있습니다.
페이지 수준 데이터도 동일한 방식으로 쿼리할 수 있지만 페이로드에서 origin 대신 url를 사용합니다.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
페이지 수준 및 출처 수준의 이전 데이터에는 나머지 CrUX와 동일한 자격 요건이 적용되므로 특히 페이지에는 완전한 이전 기록이 없을 수 있습니다. 이러한 경우 '누락된' 데이터는 histogramTimeseries 밀도의 경우 "NaN"로, percentilesTimeseries의 경우 null로 표시됩니다. 차이가 생기는 이유는 히스토그램 밀도는 항상 숫자이지만 백분위수는 숫자 또는 문자열일 수 있습니다 (CLS는 숫자처럼 보이지만 문자열을 사용함).
데이터 시각화
그렇다면 데이터가 왜 이런 식으로 형성되었는지 궁금할 것입니다. 이렇게 하면 그래프를 더 쉽게 표시할 수 있습니다. 예를 들어 https://web.dev의 Interaction To Next Paint (INP)의 p75 값 그래프는 다음과 같습니다.
이 선 차트에서 y축의 각 값은 p75s 시계열의 p75 값이며 x축은 각 수집 기간에 대해 lastDate로 설정된 시간입니다.
다음은 히스토그램 빈 시계열 그래프(트라이빈 차트라고 함)에 대한 그래프입니다. 이러한 히스토그램에는 3개의 구간이 있기 때문입니다.
X축은 각 수집 기간에 대해 lastDate로 설정됩니다. 하지만 이번에는 y축이 INP 측정항목의 특정 범위에 속하는 페이지 로드 비율을 누적 막대 그래프를 통해 나타낸 것입니다. p75 차트는 간략한 개요를 제공하며 비교적 쉽게 단일 차트 내에서 여러 측정항목을 추가하거나 PHONE 및 DESKTOP 모두에 대한 선을 표시할 수 있습니다. 트리빈 차트는 각 수집 기간 동안 측정된 측정항목 값의 분포를 보여줍니다.
예를 들어 p75 차트에서는 관찰 기간 동안 https://web.dev가 거의 허용 가능한 INP 값을 나타냈음에도 불구하고 트라이빈(tri-bin) 차트에서는 소수의 페이지 로드에서 INP가 실제로 낮았음을 보여줍니다. 두 차트 모두 10월 말에 시작되어 11월 중순에 해결된 실적 회귀가 있었다는 것을 비교적 쉽게 추론할 수 있습니다.
이러한 차트를 직접 생성할 수 있도록 예시 Colab을 만들었습니다. Colab 또는 'Colaboratory'를 사용하면 브라우저 내에서 Python을 작성하고 실행할 수 있습니다. CrUX History API Colab (출처)은 Python을 사용하여 API를 호출하고 데이터를 차트로 표시합니다.
이 Colab을 사용하면 간단한 양식을 작성하여 p75 차트와 트리빈 차트를 만들고, 데이터를 표 형식으로 가져오고, CrUX API의 요청 및 응답 쌍을 확인할 수 있습니다. 프로그래머가 아니더라도 Python 코드를 보고 멋지게 수정할 수 있습니다! 즐겁게 사용해 보시고 발견한 내용에 대한 의견이 있으면 언제든지 알려주세요.
물론 Colab이나 Python에 국한되지 않으며 이 새로운 API를 사용하는 한 가지 예에 불과합니다. API는 JSON 기반의 HTTP 엔드포인트로서 모든 기술에서 쿼리할 수 있습니다.
결론
CrUX History API 엔드포인트를 도입하기 전에는 CrUX에서 얻을 수 있는 과거 정보가 사이트 소유자에게 제한되어 있었습니다. BigQuery 및 CrUX 대시보드를 사용하여 월별 원본 수준 데이터는 사용할 수 있었지만 주간 데이터는 사용할 수 없었고 페이지 수준 기록 데이터도 사용할 수 없었습니다. 사이트 소유자가 일일 API를 사용하여 이 데이터를 직접 기록할 수 있지만, 대개의 경우 측정항목이 회귀한 후에야 이를 발견하게 되었습니다.
이 CrUX History API를 통해 사이트 소유자가 변화하는 사이트 측정항목을 더 잘 이해하고 문제 발생 시 진단 도구로 사용할 수 있기를 바랍니다. 새 API를 사용 중인 경우 Chrome UX 보고서 (토론) Google 그룹에서 의견을 보내주세요.
감사의 말
Unsplash에 있는 Dave Herring의 히어로 이미지