🔍 Next.js Instrumentation 가이드: 서버 및 클라이언트 관측성 설정

🔍 Next.js Instrumentation 가이드: 서버 및 클라이언트 관측성 설정

Next.js의 Instrumentation 기능은 애플리케이션의 성능 모니터링, 오류 추적, 로깅 등을 위한 관측성 도구를 통합할 수 있도록 지원합니다.
이를 통해 서버와 클라이언트에서 발생하는 다양한 이벤트를 추적하고 분석할 수 있습니다.

---

📁 파일 구성 및 위치

1. instrumentation.ts 또는 instrumentation.js

• 위치: 프로젝트 루트 디렉토리 또는 src/ 폴더 내부
• 용도: 서버 측 관측성 도구 초기화 및 설정
• 필수 함수: register 함수

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

export function register() {
  registerOTel('next-app');
}

참고:
instrumentation 파일은 app/ 또는 pages/ 디렉토리 내부가 아닌 루트에 위치해야 합니다.
src/ 폴더를 사용하는 경우, 해당 폴더 내에 배치합니다.

---

2. instrumentation-client.ts 또는 instrumentation-client.js

• 위치: 프로젝트 루트 디렉토리 또는 src/ 폴더 내부
• 용도: 클라이언트 측 관측성 도구 초기화 및 설정
• 특징: 특정 함수의 export 없이 코드 실행

// instrumentation-client.ts
console.log('클라이언트 측 관측성 도구 초기화');

// 오류 추적 설정
window.addEventListener('error', (event) => {
  console.error('오류 발생:', event.error);
});

참고:
이 파일은 애플리케이션의 프론트엔드 코드가 실행되기 전에 로드되므로, 초기화 코드나 글로벌 설정을 배치하기에 적합합니다.

---

⚙️ 동작 원리 및 설정

반응형

서버 측: register 함수

• 호출 시점: 새로운 Next.js 서버 인스턴스가 시작될 때 한 번 호출
• 비동기 지원: async 함수로 정의 가능

export async function register() {
  await import('some-observability-tool');
}

주의:
register 함수는 모든 런타임 환경에서 호출되므로, 특정 환경(Node.js 또는 Edge)에만 필요한 코드는 조건부로 로드해야 합니다.

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node');
  } else if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge');
  }
}

---

클라이언트 측: 초기화 코드

• 실행 시점: 프론트엔드 코드가 실행되기 전에 로드
• 용도: 퍼포먼스 모니터링, 오류 추적, 분석 도구 초기화 등

// instrumentation-client.ts
performance.mark('app-init');

// 분석 도구 초기화
console.log('분석 도구 초기화 완료');

---

🔌 OpenTelemetry 통합 예시

Next.js는 OpenTelemetry를 통한 관측성 도구 통합을 지원합니다.
@vercel/otel 패키지를 활용하여 간단하게 설정할 수 있습니다.

설치

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

설정

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

export function register() {
  registerOTel('next-app');
}

---

🧪 테스트 및 디버깅

• 환경 변수 확인: process.env.NEXT_RUNTIME을 통해 현재 런타임 환경(Node.js 또는 Edge)을 확인할 수 있습니다.
• 에러 처리: onRequestError 함수를 instrumentation.ts 파일에 정의하여 서버 측 에러를 처리할 수 있습니다.

export function onRequestError(error: Error) {
  console.error('서버 에러 발생:', error);
}

---

✅ 활용 방안

1. 서버 로깅 및 추적
   • instrumentation.ts에 서버 모니터링 도구 설정
   • console.log를 통한 실시간 상태 확인
2. 클라이언트 분석 도구 통합
   • Google Analytics 또는 Sentry 초기화 코드 추가
   • 성능 데이터 수집을 위한 Web Vitals 활용
3. 에러 추적
   • onRequestError 함수로 서버 에러를 관리
   • 클라이언트 측에서는 window.addEventListener('error')로 오류 포착

---

✅ 요약

구성 요소 설명

instrumentation.ts	서버 측 관측성 도구 초기화 및 설정
instrumentation-client.ts	클라이언트 측 관측성 도구 초기화 및 설정
register 함수	서버 인스턴스 시작 시 호출되어 초기화 작업 수행
onRequestError 함수	서버 측 에러 발생 시 호출되어 에러 처리 수행
런타임 환경 변수	process.env.NEXT_RUNTIME을 통해 확인
OpenTelemetry 통합	@vercel/otel 패키지를 활용하여 간단 설정

---

 

Next.js, Instrumentation, 관측성, OpenTelemetry, 서버 모니터링, 클라이언트 모니터링, 퍼포먼스 추적, 에러 추적, 로깅, 분석 도구, 서버 초기화, 클라이언트 초기화