Next.js 로그 / 에러 처리 포인트¶
Next.js는 빌드 타임과 런타임이 명확히 분리된 구조를 가지며,
이로 인해 로그와 에러의 발생 지점도 두 영역으로 나뉜다.
Express와 달리, 서버 로그만으로는 전체 장애를 분석할 수 없다.
1. 서버 런타임 로그 (SSR / API)¶
- 대상:
- SSR 요청 처리
- API Routes
- Server Actions
- 로그 수집 위치:
pm2 logs- systemd journal
- 특징:
- 요청 단위 에러 확인 가능
- 서버 부하·타임아웃 분석에 유용
운영 포인트¶
- SSR 오류는:
- 사용자 요청 시점에 즉시 발생
- 서버 로그에서만 확인 가능
- 서버 로그는:
- 실시간 장애 대응용 로그로 취급
2. 빌드 로그 (Build Time)¶
- 대상:
npm run build- 정적 페이지 생성
- ISR 초기 산출물 생성
- 로그 수집 위치:
- CI/CD 파이프라인 로그
- 빌드 서버 콘솔 출력
- 특징:
- 타입 오류
- 의존성 문제
- 빌드 설정 오류
가 주로 발생
운영 포인트¶
- 빌드 로그 오류는:
- 배포 실패로 직결
- 런타임 서버에는 아무 로그도 남기지 않음
- 빌드 성공 여부는:
- 서비스 상태 판단의 선행 조건
3. 로그 성격 비교¶
| 구분 | 런타임 로그 | 빌드 로그 |
|---|---|---|
| 발생 시점 | 요청 처리 중 | 배포 전 |
| 주요 대상 | SSR / API | SSG / ISR / 번들 |
| 장애 영향 | 부분적 | 전체 배포 차단 |
| 분석 목적 | 실시간 대응 | 사전 차단 |
4. 운영 기준 (Baseline)¶
- 빌드 로그와 런타임 로그를 명확히 분리 관리한다
- 배포 파이프라인에서는:
- 빌드 로그를 반드시 보관한다
- 장애 발생 시:
- 먼저 빌드 성공 여부를 확인
- 이후 런타임 로그를 분석한다
- pm2 로그만으로:
- 서비스 정상 여부를 판단하지 않는다
5. 운영 체크리스트¶
- pm2 / systemd 로그 수집 정상 여부 확인
- CI/CD 빌드 로그 보관 여부 확인
- 빌드 실패 시 배포 차단 로직 확인
- 장애 분석 시 로그 확인 순서 숙지