📊 Next.js App Router 웹 애널리틱스 설정 완벽 가이드

Next.js App Router를 사용하는 프로젝트에서 성능 모니터링, 사용자 분석, 오픈텔레메트리 관측까지 설정하는 방법을 정리합니다.
실제 운영 환경을 고려해 실용적인 구성만 다룹니다.

✅ 1. Web Vitals 성능 데이터 수집

Next.js는 기본적으로 웹 퍼포먼스 지표(Core Web Vitals)를 수집할 수 있는 useReportWebVitals 훅을 제공합니다.

사용법

// app/_components/WebVitals.tsx
'use client';

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals((metric) => {
    console.log(metric);
    // 예: 외부 분석 서비스로 전송 가능
  });
}

루트 레이아웃에 추가하면 전역 측정이 가능합니다.

// app/layout.tsx
import { WebVitals } from './_components/WebVitals';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <WebVitals />
        {children}
      </body>
    </html>
  );
}

주의: 반드시 클라이언트 컴포넌트여야 하며, 'use client' 선언이 필요합니다.

✅ 2. 클라이언트 초기화 코드 실행하기

앱이 시작할 때 애널리틱스 초기화 코드나 에러 리스너를 등록하고 싶다면 instrumentation-client.ts 파일을 활용합니다.

예시

// instrumentation-client.ts
console.log('애널리틱스 시작');

window.addEventListener('error', (event) => {
  console.error('오류 발생', event.error);
  // 오류를 외부 서버로 전송 가능
});

이 파일은 루트 디렉토리에 생성하고, 자동으로 애플리케이션 초기화 과정에 포함됩니다.

✅ 3. Google Analytics 쉽게 연결하기

Next.js는 GA4를 쉽게 연동할 수 있도록 @next/third-parties 패키지를 제공합니다.

설치

npm install @next/third-parties

사용법

// app/layout.tsx
import { GoogleAnalytics } from '@next/third-parties/google';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        {children}
        <GoogleAnalytics gaId="G-XXXXXXX" />
      </body>
    </html>
  );
}

G-XXXXXXX는 본인의 Google Analytics 측정 ID로 교체합니다.
페이지 이동 시 자동 추적됩니다.

참고: Google Tag Manager를 쓰는 경우, GA 직접 삽입 대신 GTM을 통해 관리하는 것도 좋은 방법입니다.

✅ 4. OpenTelemetry를 이용한 고급 관측 설정

앱 전체 트래픽, API 응답 시간, 서버 성능 등을 모니터링하고 싶다면 OpenTelemetry를 사용할 수 있습니다.

설정 절차

패키지 설치

npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation

instrumentation.ts 파일 생성

// instrumentation.ts
import { registerOTel } from '@vercel/otel';

registerOTel();

자동으로 트레이스(trace), 로그, 메트릭(metrics)을 수집 가능
Datadog, NewRelic, Jaeger 등 다양한 백엔드에 연동 가능

✅ 요약 정리

기능 구현 방법 위치/파일

Web Vitals 측정	useReportWebVitals 훅	클라이언트 컴포넌트
클라이언트 초기화 코드	instrumentation-client.ts 작성	루트 디렉토리
Google Analytics 연동	@next/third-parties 설치 및 사용	루트 레이아웃
OpenTelemetry 설정	instrumentation.ts 작성 및 등록	루트 디렉토리

https://nextjs.org/docs/app/guides/analytics

Next.js, App Router, 웹 분석, Web Vitals, Google Analytics, OpenTelemetry, 성능 모니터링, 클라이언트 초기화, 데이터 수집, SEO 최적화, 서버 관측