Next.js 애플리케이션에 분석 기능 추가하기
Next.js는 성능 메트릭을 측정하고 보고하는 기능을 내장하고 있습니다. useReportWebVitals 훅을 사용하여 직접 보고를 관리하거나, Vercel에서 제공하는 관리형 서비스를 사용하여 자동으로 메트릭을 수집하고 시각화할 수 있습니다.
클라이언트 인스트루멘테이션
더 고급 분석 및 모니터링 요구사항을 위해 Next.js는 애플리케이션의 프론트엔드 코드가 실행되기 전에 실행되는 instrumentation-client.js|ts 파일을 제공합니다. 이는 전역 분석, 에러 추적 또는 성능 모니터링 도구를 설정하는 데 이상적입니다.
사용하려면 애플리케이션의 루트 디렉토리에 instrumentation-client.js 또는 instrumentation-client.ts 파일을 생성합니다:
// instrumentation-client.js
// 앱이 시작되기 전에 분석 초기화
console.log('Analytics initialized')
// 전역 에러 추적 설정
window.addEventListener('error', (event) => {
// 에러 추적 서비스로 전송
reportError(event.error)
})Client Instrumentation은 다음과 같은 실무 상황에서 매우 유용합니다:
- Google Analytics 4나 Mixpanel 같은 분석 도구 초기화
- Sentry나 Bugsnag 같은 에러 모니터링 도구 설정
- 사용자 세션 추적 및 A/B 테스트 도구 연결
직접 구현하기
// app/_components/web-vitals.js
'use client'
import { useReportWebVitals } from 'next/web-vitals'
export function WebVitals() {
useReportWebVitals((metric) => {
console.log(metric)
})
}// app/layout.js
import { WebVitals } from './_components/web-vitals'
export default function Layout({ children }) {
return (
<html>
<body>
<WebVitals />
{children}
</body>
</html>
)
}더 자세한 정보는 API 참조를 확인하세요.
Web Vitals
Web Vitals는 웹 페이지의 사용자 경험을 포착하는 것을 목표로 하는 유용한 메트릭 집합입니다. 다음 웹 바이탈들이 모두 포함됩니다:
- Time to First Byte (TTFB)
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)
- First Input Delay (FID)
- Cumulative Layout Shift (CLS)
- Interaction to Next Paint (INP)
name 속성을 사용하여 이러한 메트릭의 모든 결과를 처리할 수 있습니다.
// app/_components/web-vitals.tsx
'use client'
import { useReportWebVitals } from 'next/web-vitals'
export function WebVitals() {
useReportWebVitals((metric) => {
switch (metric.name) {
case 'FCP': {
// FCP 결과 처리
}
case 'LCP': {
// LCP 결과 처리
}
// ...
}
})
}Web Vitals 성능 기준값을 참고하여 최적화하세요:
- LCP: 2.5초 이하 (Good), 4초 이상 (Poor)
- FID: 100ms 이하 (Good), 300ms 이상 (Poor)
- CLS: 0.1 이하 (Good), 0.25 이상 (Poor)
- INP: 200ms 이하 (Good), 500ms 이상 (Poor)
외부 시스템으로 결과 전송
사이트의 실제 사용자 성능을 측정하고 추적하기 위해 결과를 모든 엔드포인트로 전송할 수 있습니다. 예를 들어:
useReportWebVitals((metric) => {
const body = JSON.stringify(metric)
const url = 'https://example.com/analytics'
// `navigator.sendBeacon()`이 사용 가능하면 사용하고, 그렇지 않으면 `fetch()`로 대체
if (navigator.sendBeacon) {
navigator.sendBeacon(url, body)
} else {
fetch(url, { body, method: 'POST', keepalive: true })
}
})Google Analytics를 사용하는 경우, id 값을 사용하여 메트릭 분포를 수동으로 구성할 수 있습니다 (백분위수 계산 등).
useReportWebVitals((metric) => {
// Google Analytics를 다음 예시처럼 초기화했다면 `window.gtag`를 사용하세요:
// https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics
window.gtag('event', metric.name, {
value: Math.round(
metric.name === 'CLS' ? metric.value * 1000 : metric.value
), // 값은 정수여야 함
event_label: metric.id, // 현재 페이지 로드에 고유한 id
non_interaction: true, // 이탈률에 영향을 주지 않음
})
})Google Analytics로 결과 전송하기에 대해 더 읽어보세요.
실제 프로덕션 환경에서 자주 사용되는 분석 도구들:
- Vercel Analytics: Next.js와 완벽 통합, 실시간 성능 모니터링
- Google Analytics 4: 무료, 포괄적인 사용자 행동 분석
- DataDog RUM: 엔터프라이즈급 실사용자 모니터링
- New Relic Browser: 상세한 성능 분석 및 에러 추적
'(준)공식 문서 > Next.js' 카테고리의 다른 글
| [ Next.js 15 공식 문서 ] Backend For Frontend (BFF) (3) | 2025.07.27 |
|---|---|
| [ Nexts.js 15 공식 문서 ] Authentication (인증) (2) | 2025.07.27 |
| [ Next.js 15 공식 문서 ] Route Handlers and Middleware (라우트 핸들러와 미들웨어) (0) | 2025.07.20 |
| [ Next.js 15 공식 문서 ] Metadata and OG images (메타 데이터와 OG 이미지) (0) | 2025.07.20 |
| [ Next.js 15 공식 문서 ] Font Optimization (폰트 최적화) (0) | 2025.07.20 |