Next.js 헬스 체크 및 관측 가능성 스킬 (nextjs-healthcheck)
Next.js App Router 애플리케이션에 걸쳐 헬스 체크 엔드포인트 (/api/health), 제로-의존성 Docker Compose 헬스 프로브, Node.js 런타임 메트릭을 생성하고 유지 관리하기 위한 모듈식의 프로덕션 지원 워크플로우입니다.
워크플로우 개요
flowchart TD
A["1. 프로젝트 스캔<br/>(데이터베이스 및 Docker Compose)"] --> B["2. /api/health 생성<br/>(메트릭이 포함된 템플릿)"]
B --> C["3. Docker 프로브 주입<br/>(docker-compose.yml)"]
C --> D["4. 확인 및 검증<br/>(curl 및 docker compose ps)"]
단계별 실행 런북
순차적으로 이 체크리스트를 따라 애플리케이션 헬스 모니터링을 구현하고 확인합니다:
1. 프로젝트 탐색 및 의존성 검사
- 라우트 핸들러 경로 찾기: 프로젝트가
app/또는src/app/디렉토리를 사용하는지 확인합니다 (대상:app/api/health/route.ts또는src/app/api/health/route.ts). - 데이터베이스 / 외부 저장소 감지:
package.json에서 ORM 및 클라이언트(Prisma, Drizzle, Supabase, Mongoose, PostgreSQL, Redis)를 스캔합니다. database-probes.md를 참조하세요. - Docker Compose 파일 찾기:
docker-compose.yml,docker-compose.prod.yml또는 기타 컴포즈 스택을 발견합니다. docker-compose-probes.md를 참조하세요.
2. 헬스 체크 라우트 핸들러 구현
- 라우트 템플릿 선택:
- 데이터베이스 없음: route-no-db.ts.template을 배포합니다.
- 데이터베이스 있음: route-with-db.ts.template을 배포하고 프로젝트별 DB 클라이언트와 엄격한 2초 타임아웃을 연결합니다.
- 동적 실행 강제:
export const dynamic = "force-dynamic";및Cache-Control: no-store, no-cache, must-revalidate헤더가 있는지 확인합니다. - 비차단 메트릭 구성: V8 힙 사용률, 이벤트 루프 지연 (
perf_hooks를 통한 $p99$ 지연), 프로세스 가동 시간을 수집합니다. status-and-metrics.md를 참조하세요. - HTTP 상태 코드 규칙 강제:
healthy/degraded상태는200 OK,unhealthy상태는503 Service Unavailable을 반환합니다.
3. Docker Compose 헬스 프로브 구성
- Next.js 서비스 식별: 감지된 컴포즈 파일에서 Next.js 서비스 블록 (
nextjs-app,web,app)을 검사합니다. - 헬스체크 블록 주입: docker-compose.healthcheck.template.yml에서 제로-의존성 Node.js fetch 헬스 프로브를 추가합니다.
4. 확인 및 테스트
- 로컬 API 테스트:
유효한 JSON 페이로드 (curl -i http://localhost:3000/api/healthstatus,timestamp,uptimeSeconds,checks)와 함께 HTTP 200 응답을 확인합니다. - 컴포즈 헬스 상태 확인:
초기 시작 기간 후 서비스 상태가docker compose ps(healthy)로 전환되는지 확인합니다.
엣지 케이스 및 알려진 AI 함정
[!WARNING]
force-dynamic누락:export const dynamic = "force-dynamic"이 생략되면 Next.js App Router가 라우트 응답을 정적으로 평가하거나 캐시하여 타임스탬프가 고정되고 가동 시간 메트릭이 멈출 수 있습니다.- 데이터베이스 연결 중단: 타임아웃(최대 2000ms) 없이 외부 데이터베이스를 쿼리하지 마십시오. 처리되지 않은 네트워크 지연은 요청 풀 고갈로 이어질 수 있습니다.
- 컨테이너 내 외부 도구 의존성: Docker 헬스 체크에서
curl또는wget에 의존하지 마십시오. 프로덕션 최소 이미지(예:node:alpine또는 distroless)에는 이러한 도구가 없는 경우가 많습니다.node -e를 통해 Node.js 네이티브fetch를 사용하세요.- 비밀 정보 유출: 공개
/api/health응답 페이로드에 데이터베이스 연결 URL, 비밀번호 또는 내부 원시 오류 추적을 절대 출력하지 마십시오.
출력 요약 스키마
헬스 체크 설정이 완료되면 간결한 요약 보고서를 제공합니다:
### 헬스 모니터링 구성 완료
- **라우트 핸들러**: `[app/api/health/route.ts](file:///...)`
- **데이터베이스 프로브**: [구성됨: Prisma / Drizzle / 없음] (타임아웃: 2000ms)
- **런타임 메트릭**: V8 힙 사용률 및 이벤트 루프 지연 (p99)
- **업데이트된 Docker Compose 스택**: `docker-compose.yml`, `docker-compose.prod.yml`
- **확인 상태**: 통과 (HTTP 200 / 컨테이너 정상)
참고 가이드 및 템플릿
- 상태 코드 및 메트릭 참조 — 아키텍처 상태 매트릭스, 메모리 공식 및 지연 임계값.
- 데이터베이스 프로브 참조 — 감지 체크리스트, 타임아웃 래핑 및 ORM 프로브 패턴.
- Docker Compose 프로브 참조 — 서비스 매칭 규칙 및 제로-의존성 fetch 정의.
- 라우트 템플릿 (DB 없음) — 상태 비저장 앱을 위한 완전한 라우트 핸들러.
- 라우트 템플릿 (DB 있음) — 의존성 프로브가 포함된 완전한 라우트 핸들러.
- Docker Compose 헬스체크 템플릿 — 재사용 가능한 컴포즈 스니펫.