ttipo
bf102d758f
운영에서 조용히 문제를 일으킬 수 있는 지점들을 정리한다. - env 검증(fail-fast): 설정이 잘못되면 서버가 뜨지 않는다. 운영에서 DB_* 누락과 'change-me' 같은 예시 값 배포를 차단하고, 문제를 하나씩이 아니라 한 번에 모아 보여준다. DB_PASSWORD 가 없을 때 'password' 로 조용히 동작하던 폴백도 제거. - graceful shutdown: SIGTERM 시 요청·커넥션을 정리한 뒤 종료한다. 종료 로그는 OnApplicationShutdown 훅으로 남긴다 — process.on(signal) 로 직접 잡으면 Nest 의 종료 흐름에 간섭해 종료 코드가 달라진다. - 헬스체크 두 가지 결함 수정: pingCheck 기본 타임아웃 1초가 짧아 유휴 커넥션 재연결 시 정상 DB 를 down 으로 오판했고, 실패 응답이 SYS_001 로 덮여 어느 구성요소가 죽었는지 알 수 없었다. 모니터링이 읽는 엔드포인트이므로 표준 래퍼·에러 코드에서 제외한다. - Rate limiting 을 @nestjs/throttler 로 일원화 (express-rate-limit 제거). 두 리미터가 겹쳐 헤더의 한도와 실제 동작이 어긋나 있었다. - e2e 를 응답 계약 검증으로 교체. 기존 테스트는 없는 경로를 검사해 이미 실패 상태였다. - 로깅 규칙(logging.md) 신설 — 레벨 기준·민감정보 마스킹·traceId Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.5 KiB
2.5 KiB
로깅 규칙
console.log 사용 금지. 백엔드는 winston(shared/logger/winston.config.ts), Nest 내부는 Logger 를 쓴다.
레벨 기준
| 레벨 | 쓰는 상황 | 예 |
|---|---|---|
error |
서버 책임 오류(5xx), 즉시 조치가 필요한 실패 | 미정의 예외, DB 커넥션 실패 |
warn |
사용자 책임 실패(4xx), 예상된 비정상 | 검증 실패, 권한 없음, Rate Limit 초과 |
log(info) |
상태 변화가 있는 주요 이벤트 | 서버 기동, 가입 완료, 결제 승인 |
debug |
개발 환경 진단 | 외부 API 요청/응답 요약 |
- 4xx 를
error로 남기지 않는다 — 알림 피로도가 올라가 진짜 장애를 놓친다. - 반복되는 정상 흐름(헬스체크, 폴링)은 로그를 남기지 않는다.
필수 포함 정보
모든 에러 로그에는 에러 코드와 추적 ID를 함께 남긴다.
[RES_001][3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d] GET /api/users/1 {"userId":1}
- 추적 ID는
RequestIdMiddleware가 발급하는x-request-id이며, 실패 응답의error.traceId와 같은 값이다. - 사용자 문의가 들어오면 이 값으로 로그를 검색한다 (error-codes).
- 개발자용 컨텍스트는
BusinessException의context에 담는다 — 로그에만 남고 응답에는 포함되지 않는다.
민감정보 마스킹 (필수)
아래 값은 어떤 레벨에서도 원문 그대로 남기지 않는다.
- 비밀번호, 토큰(JWT·리프레시·API 키), 쿠키,
Authorization헤더 - 주민등록번호·카드번호·계좌번호 등 개인 식별/금융 정보
- 요청 본문 전체 덤프 (
JSON.stringify(req.body)금지 — 필요한 필드만 선택해 남긴다)
// ❌ 금지
this.logger.log(`로그인 시도: ${JSON.stringify(dto)}`);
// ✅ 필요한 식별자만
this.logger.log(`로그인 시도: email=${maskEmail(dto.email)}`);
- 마스킹 유틸은 순수 함수로
shared/utils/에 둔다 (coding-common).
클라이언트 로깅
- 프론트/앱에서 사용자 정보를 콘솔에 출력하지 않는다. 운영 빌드에는 디버그 로그를 남기지 않는다.
- 사용자 노출 문구는 로그가 아니라 에러 사전에서 온다 (error-codes).
운영 확장
- 운영 환경은 JSON 포맷 + 외부 수집기(Loki/ELK/CloudWatch) 연동을 권장한다.
- 파일로 남길 경우 로테이션(
winston-daily-rotate-file)을 적용하고 보존 기간을 정한다.