TIL - 20260808

juni·2026년 8월 8일

목록 보기

426/468

0808 인프라/DevOps 운영 심화 (7/N): 로그, 모니터링과 장애 대응 기본

✅ 1. 로그와 모니터링이란 무엇인가?

로그(Log)는 서비스에서 어떤 일이 일어났는지 시간 순서대로 남기는 기록입니다.
모니터링(Monitoring)은 서버, API, DB, 배포 상태, 에러 발생률 같은 운영 상태를 지속적으로 확인하는 체계입니다.
장애가 발생했을 때 로그와 모니터링이 없으면 원인을 감으로 추측해야 합니다.
반대로 기록이 잘 남아 있으면 “언제, 어디서, 무엇이, 왜” 문제가 되었는지 빠르게 좁힐 수 있습니다.

사용자 요청
  ↓
Nginx access log
  ↓
Backend application log
  ↓
Database query/error
  ↓
External API log
  ↓
Monitoring/Alert

➕ 1-1. 로그와 모니터링이 중요한 이유

API 장애 원인을 빠르게 찾을 수 있습니다.
배포 이후 문제가 생겼는지 확인할 수 있습니다.
상담 신청 실패, 관리자 로그인 실패 같은 핵심 문제를 추적할 수 있습니다.
서버 CPU/RAM/디스크 부족을 미리 발견할 수 있습니다.
보안 사고나 비정상 요청을 추적할 수 있습니다.
장애 대응 기록을 남겨 재발 방지에 활용할 수 있습니다.

로그/모니터링 없음:
고객이 안 된다고 말한 뒤에야 알게 됨
원인 추적이 느림
재발 방지 어려움
장애 시간 설명 어려움

로그/모니터링 있음:
에러 증가 확인
배포 시점과 비교
특정 API/사용자 흐름 추적
원인과 조치 기록 가능

✅ 2. 로그의 종류

운영 서비스에서는 여러 종류의 로그가 생깁니다.
하나만 봐서는 원인을 놓칠 수 있으므로 계층별로 봐야 합니다.

로그 종류	위치	확인 내용
Nginx access log	웹 서버	요청 경로, 상태 코드, IP
Nginx error log	웹 서버	proxy 실패, 설정 오류
Backend log	NestJS/Node	API 처리, 에러, 비즈니스 이벤트
DB log	PostgreSQL/RDS	느린 쿼리, 연결 오류
CloudFront log	CDN	정적 파일 요청, 캐시, 403/404
Application event log	앱 내부	상담 신청, 상태 변경, 로그인
Audit log	관리자 행동	누가 무엇을 변경했는지
CI/CD log	GitHub Actions	빌드/배포 성공·실패

➕ 2-1. 계층별로 봐야 하는 이유

고객 화면이 안 뜸:
CloudFront/S3/Nginx/프론트 JS 에러 확인

API가 502:
Nginx error log + Backend process 확인

API가 500:
Backend log + DB log 확인

상담 신청 실패:
Frontend event + Backend API log + DB insert log 확인

문제는 한 계층에서만 보이지 않을 수 있습니다.
예를 들어 사용자는 “신청이 안 돼요”라고 말하지만, 실제 원인은 CORS, API 500, DB 제약조건, 외부 알림톡 실패 중 하나일 수 있습니다.

✅ 3. 좋은 로그의 조건

로그는 많다고 좋은 것이 아닙니다.
문제 해결에 필요한 정보가 적절한 수준으로 남아야 합니다.

➕ 3-1. 좋은 로그

언제 발생했는지 알 수 있음
어떤 요청인지 알 수 있음
어떤 사용자 흐름인지 알 수 있음
성공/실패가 구분됨
에러 code와 message가 있음
requestId나 traceId가 있음
민감정보는 마스킹됨

➕ 3-2. 나쁜 로그

console.log("여기 탐")
console.log(response 전체)
console.log(process.env 전체)
console.log(고객 전화번호 원본)
console.log(토큰)
에러를 삼키고 아무 로그도 안 남김

➕ 3-3. 로그에 들어가면 좋은 값

timestamp
level
requestId
method
path
statusCode
durationMs
userId 또는 adminId
eventName
errorCode
message

로그는 나중에 읽을 사람을 위해 남기는 기록입니다.
그 사람이 미래의 본인일 가능성이 높습니다.

✅ 4. 로그 레벨

로그에는 중요도에 따라 레벨을 둡니다.
모든 것을 console.log로 남기면 운영에서 분석이 어렵습니다.

레벨	의미	예시
debug	개발 중 상세 정보	내부 변수, 분기 확인
info	정상 이벤트	서버 시작, 상담 신청 성공
warn	주의 필요	재시도, 외부 API 일시 실패
error	실패	API 500, DB 오류
fatal	치명적 장애	서버 시작 실패, 필수 env 누락

➕ 4-1. 기준

debug:
로컬 개발용

info:
정상 운영 이벤트

warn:
즉시 장애는 아니지만 확인 필요

error:
요청 실패 또는 기능 실패

fatal:
서비스 실행 불가 수준

➕ 4-2. 예시

info:
consult.create.success

warn:
alimtalk.send.retry

error:
consult.create.failed

fatal:
env.validation.failed

운영에서는 debug 로그를 과하게 남기지 않는 것이 좋습니다.
필요한 이벤트는 info, 실제 실패는 error, 의심 상황은 warn으로 구분해야 합니다.

✅ 5. 구조화 로그

운영 로그는 문자열보다 JSON 형태의 구조화 로그가 좋습니다.
검색, 필터링, 집계가 쉬워지기 때문입니다.

➕ 5-1. 나쁜 예시

상담 신청 실패함 01012345678 중복임

문제:

검색 어려움
전화번호 원본 노출
에러 코드 없음
요청 추적 어려움

➕ 5-2. 좋은 예시

{
  "level": "warn",
  "event": "consult.create.duplicated",
  "requestId": "req_abc123",
  "path": "/api/consults",
  "statusCode": 409,
  "errorCode": "CONSULT_DUPLICATED",
  "phoneMasked": "010****5678",
  "durationMs": 83
}

구조화 로그는 나중에 CloudWatch, Datadog, ELK, Loki 같은 도구로 보내기 좋습니다.
개인정보는 원본이 아니라 마스킹된 형태로 남겨야 합니다.

✅ 6. Request ID와 Trace ID

Request ID는 하나의 요청을 추적하기 위한 고유 ID입니다.
클라이언트, Nginx, 백엔드, DB, 외부 API 로그를 연결할 때 도움이 됩니다.

사용자 요청
  ↓
requestId 생성
  ↓
Nginx log
  ↓
Backend log
  ↓
DB log
  ↓
External API log

➕ 6-1. 필요한 이유

동일한 요청의 로그를 묶어서 보기
에러 발생 요청 추적
프론트 에러와 백엔드 에러 연결
고객 문의 시 특정 시점 요청 확인

➕ 6-2. 예시

고객:
상담 신청이 안 됐어요.

확인:
시간대 + requestId 확인
  ↓
백엔드 consult.create.failed log 검색
  ↓
DB insert 실패 또는 중복 에러 확인

requestId가 없으면 같은 시간대의 여러 요청 중 어떤 요청이 문제였는지 찾기 어렵습니다.
운영 품질을 올리려면 requestId를 초기에 도입하는 것이 좋습니다.

✅ 7. NestJS 로그 기준

NestJS에서는 기본 Logger를 사용할 수도 있고, pino/winston 같은 로거를 사용할 수도 있습니다.
운영에서는 request log, error log, 비즈니스 이벤트 log를 구분하면 좋습니다.

➕ 7-1. 기본 Logger 예시

import { Logger } from '@nestjs/common';

@Injectable()
export class ConsultService {
  private readonly logger = new Logger(ConsultService.name);

  async createConsult() {
    this.logger.log('consult.create.start');

    try {
      // 상담 신청 처리
      this.logger.log('consult.create.success');
    } catch (error) {
      this.logger.error('consult.create.failed', error);
      throw error;
    }
  }
}

➕ 7-2. 운영에서 더 좋은 방향

문자열만 남기지 않기
eventName 사용
requestId 포함
errorCode 포함
durationMs 포함
민감정보 마스킹

➕ 7-3. 남기면 좋은 이벤트

consult.create.success
consult.create.failed
admin.login.success
admin.login.failed
consult.status.update.success
consult.status.update.failed
export.job.created
export.job.failed
alimtalk.send.success
alimtalk.send.failed

모든 API를 과하게 로그로 남길 필요는 없습니다.
상담 신청, 로그인, 상태 변경, 엑셀 Export, 알림 발송 같은 핵심 이벤트는 남기는 것이 좋습니다.

✅ 8. API 요청 로그

API 요청 로그는 어떤 요청이 들어왔고 얼마나 걸렸는지 확인하는 데 중요합니다.

➕ 8-1. 요청 로그에 포함할 것

method
path
statusCode
durationMs
requestId
ip
userAgent
adminId 또는 userId
errorCode

➕ 8-2. 예시

{
  "level": "info",
  "event": "http.request",
  "requestId": "req_123",
  "method": "POST",
  "path": "/api/consults",
  "statusCode": 201,
  "durationMs": 92,
  "ip": "203.0.113.10"
}

➕ 8-3. 실패 예시

{
  "level": "error",
  "event": "http.request.failed",
  "requestId": "req_456",
  "method": "PATCH",
  "path": "/api/admin/consults/123/status",
  "statusCode": 500,
  "durationMs": 320,
  "errorCode": "INTERNAL_SERVER_ERROR"
}

durationMs가 있으면 느린 API를 찾을 수 있습니다.
statusCode가 있으면 4xx와 5xx 비율을 볼 수 있습니다.

✅ 9. 개인정보 로그 마스킹

온라인 휴대폰 판매몰은 이름, 전화번호, 상담 메모 같은 개인정보를 다룰 수 있습니다.
이런 값은 로그에 원본으로 남기면 안 됩니다.

➕ 9-1. 로그에 남기면 위험한 값

고객 이름 원본
전화번호 원본
주민번호
신분증 정보
상담 메모 전체
주소
계좌번호
토큰
쿠키
Authorization header
DATABASE_URL

➕ 9-2. 마스킹 예시

export function maskPhone(phone: string) {
  return phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
}

➕ 9-3. 좋은 로그

{
  "event": "consult.create.failed",
  "errorCode": "CONSULT_DUPLICATED",
  "phoneMasked": "010****5678"
}

로그는 운영 분석을 위한 것이지 개인정보 보관소가 아닙니다.
특히 외부 로그 서비스로 보내는 경우 개인정보 포함 여부를 더 조심해야 합니다.

✅ 10. Nginx 로그 활용

Nginx access log는 서버에 어떤 요청이 들어왔는지 보여줍니다.
API 서버까지 도달하지 못한 문제를 찾는 데 유용합니다.

➕ 10-1. Access log 확인

sudo tail -f /var/log/nginx/access.log

➕ 10-2. Error log 확인

sudo tail -f /var/log/nginx/error.log

➕ 10-3. 확인 포인트

요청이 들어오는가?
상태 코드가 무엇인가?
특정 API만 502/504가 나는가?
정적 파일이 404 나는가?
client IP가 비정상적으로 반복되는가?

➕ 10-4. 자주 보는 상태 코드

200:
정상

301/302:
리다이렉트

403/404:
권한/경로 문제

413:
요청 크기 초과

499:
클라이언트가 먼저 연결 종료

502:
백엔드 연결 실패

504:
백엔드 응답 지연

502/504는 백엔드 앱 상태와 timeout을 같이 봐야 합니다.
413은 업로드 크기 제한을 봐야 합니다.

✅ 11. PM2 로그 활용

PM2로 Node/NestJS 앱을 실행한다면 PM2 로그를 확인할 수 있습니다.

➕ 11-1. 상태 확인

pm2 status

➕ 11-2. 로그 확인

pm2 logs togethermall-api

➕ 11-3. 최근 로그만 보기

pm2 logs togethermall-api --lines 100

➕ 11-4. 확인할 것

앱이 재시작 반복 중인가?
Unhandled exception이 있는가?
필수 env 누락 에러가 있는가?
DB 연결 실패가 있는가?
메모리 사용량이 계속 증가하는가?

Nginx 502가 나면 PM2 앱이 살아 있는지 먼저 봐야 합니다.
앱이 계속 재시작된다면 환경변수, DB 연결, 런타임 에러 가능성이 큽니다.

✅ 12. Docker 로그 활용

Docker Compose로 백엔드, DB, Redis를 운영한다면 compose 로그를 확인해야 합니다.

➕ 12-1. 전체 로그

docker compose logs -f

➕ 12-2. 특정 서비스 로그

docker compose logs -f backend

docker compose logs -f postgres

➕ 12-3. 상태 확인

docker compose ps

➕ 12-4. 확인할 것

컨테이너가 restarting 상태인가?
backend가 DB 연결 실패 중인가?
postgres가 정상 ready 상태인가?
redis ping이 가능한가?
health check가 실패하는가?

Docker 환경에서는 localhost와 service name 문제도 함께 봐야 합니다.
백엔드 컨테이너에서 DB host가 localhost로 되어 있으면 연결이 실패할 수 있습니다.

✅ 13. CloudWatch Logs

AWS 환경에서는 CloudWatch Logs를 많이 사용합니다.
EC2, ECS, Lambda, RDS, CloudFront 등 다양한 로그를 모을 수 있습니다.

➕ 13-1. CloudWatch Logs의 역할

서버 로그 수집
애플리케이션 로그 저장
로그 검색
에러 패턴 확인
알람 조건 연결
보관 기간 설정

➕ 13-2. 활용 예시

API 500 에러 검색
특정 requestId 검색
배포 이후 error 증가 확인
상담 신청 실패 로그 확인
worker job 실패 확인

➕ 13-3. 주의

로그 저장 비용 발생 가능
민감정보 로그 전송 금지
보관 기간 설정 필요
로그 그룹/스트림 이름 규칙 필요

CloudWatch는 강력하지만 로그를 무제한 쌓으면 비용과 보안 문제가 생길 수 있습니다.
필요한 로그를 적절한 기간만 보관하는 기준이 필요합니다.

✅ 14. 모니터링 지표

모니터링은 로그만 보는 것이 아니라 숫자로 서비스 상태를 보는 것입니다.
API, 서버, DB, 사용자 행동 지표를 함께 봐야 합니다.

➕ 14-1. 서버 지표

CPU 사용률
Memory 사용률
Disk 사용률
Network 사용량
Process restart 횟수

➕ 14-2. API 지표

요청 수
응답 시간
5xx 에러율
4xx 에러율
timeout 수
특정 endpoint 실패율

➕ 14-3. DB 지표

DB connection 수
slow query
CPU/Memory
storage 사용량
lock/deadlock
replication lag

➕ 14-4. 비즈니스 지표

상담 신청 수
상담 신청 실패 수
관리자 로그인 실패 수
상태 변경 실패 수
알림톡 발송 실패 수
엑셀 Export 실패 수

기술 지표만 보면 실제 서비스 영향이 보이지 않을 수 있습니다.
비즈니스 지표를 같이 봐야 “고객이 실제로 불편한지” 판단할 수 있습니다.

✅ 15. 알림 기준

모든 에러에 알림을 걸면 알림 피로가 생깁니다.
즉시 대응이 필요한 것과 나중에 봐도 되는 것을 구분해야 합니다.

➕ 15-1. 즉시 알림 후보

API 5xx 급증
헬스체크 실패
서버 CPU/RAM 임계치 초과
디스크 사용량 80~90% 이상
DB 연결 실패
상담 신청 API 실패율 증가
관리자 로그인 전체 실패
배포 실패

➕ 15-2. 나중에 봐도 되는 것

단발성 404
사용자 입력 오류 400
권한 없음 403
소량의 중복 신청 409
봇 요청으로 보이는 비정상 경로

➕ 15-3. 기준

단발성보다 지속성
낮은 중요도보다 고객 영향
기술 에러보다 핵심 기능 실패
알림 발생 시 할 수 있는 조치가 있어야 함

알림은 울렸을 때 행동할 수 있어야 의미가 있습니다.
“왜 울렸는지 모르겠고 할 것도 없는 알림”은 줄여야 합니다.

✅ 16. Health Check

Health Check는 서비스가 정상인지 확인하는 endpoint입니다.
배포 후 확인, 모니터링, 로드밸런서 상태 확인에 사용됩니다.

➕ 16-1. 기본 health endpoint

GET /health

응답:
200 OK

➕ 16-2. 더 좋은 health check

{
  "status": "ok",
  "timestamp": "2026-08-08T09:00:00.000Z",
  "version": "abc1234",
  "checks": {
    "database": "ok",
    "redis": "ok"
  }
}

➕ 16-3. 포함하면 좋은 것

서버 상태
DB 연결 상태
Redis 연결 상태
필수 외부 서비스 상태
배포 버전
응답 시간

➕ 16-4. 주의

민감정보 노출 금지
너무 무거운 쿼리 금지
외부 서비스 장애가 전체 health 실패로 이어질지 기준 필요
관리자용 상세 health와 public health 분리 고려

health check는 가벼워야 합니다.
단순 서버 생존 확인과 상세 의존성 확인을 분리해도 좋습니다.

✅ 17. 장애란 무엇인가?

장애는 서비스가 기대한 수준으로 동작하지 않아 사용자나 운영에 영향을 주는 상태입니다.
서버가 완전히 꺼진 것만 장애가 아닙니다.
상담 신청만 실패하거나, 관리자 상태 변경만 안 되거나, 특정 모바일 화면에서 버튼이 눌리지 않는 것도 장애입니다.

➕ 17-1. 장애 예시

고객 상담 신청 API 500 발생
관리자 로그인 불가
상품 상세 이미지 전체 미노출
CloudFront 캐시 문제로 이전 JS 로딩
DB connection pool 고갈
알림톡 발송 실패
엑셀 ExportJob 계속 실패
Nginx 502 발생

➕ 17-2. 장애 판단 기준

고객 신청에 영향이 있는가?
운영자가 업무를 못 하는가?
개인정보/보안 위험이 있는가?
데이터 정합성 문제가 있는가?
장애가 지속 또는 반복되는가?

장애 대응은 “기술적으로 큰 문제인가”보다 “사용자와 운영에 영향이 있는가”를 기준으로 봐야 합니다.

✅ 18. 장애 대응 기본 순서

장애가 발생하면 당황해서 바로 코드를 고치기보다 순서를 지켜야 합니다.

1. 증상 확인
2. 영향 범위 파악
3. 최근 변경 확인
4. 로그/모니터링 확인
5. 임시 대응
6. 원인 분석
7. 근본 수정
8. 재발 방지 기록

➕ 18-1. 증상 확인

어떤 화면인가?
어떤 API인가?
언제부터인가?
모든 사용자인가 일부 사용자인가?
모바일/PC 중 어디인가?

➕ 18-2. 영향 범위

고객 화면 전체인가?
상담 신청만인가?
관리자만인가?
특정 권한만인가?
특정 브라우저만인가?

➕ 18-3. 최근 변경

최근 배포
환경변수 변경
DB migration
Nginx 설정 변경
CloudFront invalidation
외부 API 변경

운영 장애의 상당수는 최근 변경과 관련됩니다.
“마지막으로 바꾼 것”부터 확인하는 습관이 좋습니다.

✅ 19. 장애 대응 시 먼저 보는 명령어

➕ 19-1. 서버 상태

uptime
df -h
free -m
top

➕ 19-2. Nginx

sudo nginx -t
sudo systemctl status nginx
sudo tail -n 100 /var/log/nginx/error.log
sudo tail -n 100 /var/log/nginx/access.log

➕ 19-3. PM2

pm2 status
pm2 logs togethermall-api --lines 100

➕ 19-4. Docker

docker compose ps
docker compose logs --tail=100 backend
docker compose logs --tail=100 postgres

➕ 19-5. API health

curl -f https://api.example.com/health
curl -f http://localhost:3000/health

외부 URL health와 서버 내부 localhost health를 둘 다 보면 Nginx 문제인지 앱 문제인지 구분할 수 있습니다.

✅ 20. 장애 등급 나누기

모든 장애를 같은 급으로 대응하면 우선순위가 흐려집니다.
심각도 기준을 간단히 나눠두면 좋습니다.

등급	의미	예시
P0	즉시 대응	전체 서비스 접속 불가, DB 장애
P1	매우 중요	상담 신청 불가, 관리자 로그인 불가
P2	중요	특정 관리자 기능 실패, 일부 API 오류
P3	낮음	일부 UI 깨짐, 문구 오류
P4	개선	성능 저하, UX 개선 필요

➕ 20-1. 온라인 판매몰 기준

P0:
고객 사이트 전체 접속 불가

P1:
상담 신청 불가
관리자 상담 처리 불가

P2:
엑셀 다운로드 실패
알림톡 일부 실패
상품 이미지 일부 오류

P3:
일부 배너 깨짐
모바일 특정 영역 여백 문제

P4:
개선성 UX/성능 이슈

고객 신청과 관리자 처리 흐름은 높은 우선순위로 봐야 합니다.
디자인 미세 이슈와 신청 불가 장애를 같은 급으로 보면 안 됩니다.

✅ 21. 임시 대응과 근본 해결

장애 대응에는 임시 대응과 근본 해결이 있습니다.
운영 중에는 먼저 피해를 줄이고, 이후 원인을 제대로 고쳐야 합니다.

➕ 21-1. 임시 대응

이전 버전 롤백
문제 기능 임시 비활성화
CloudFront invalidation
서버 재시작
트래픽 차단
고객 안내 문구 노출
수동 처리로 전환

➕ 21-2. 근본 해결

버그 수정
테스트 추가
모니터링 추가
DB 인덱스 추가
timeout 구조 개선
Queue/Worker 분리
배포 체크리스트 보강

➕ 21-3. 예시

문제:
상담 신청 API 500

임시 대응:
이전 버전 롤백 또는 문제 validation 우회

근본 해결:
에러 원인 수정
CONSULT_DUPLICATED 테스트 추가
에러 로그와 알림 추가
배포 전 상담 신청 Smoke Test 추가

임시 대응으로 서비스는 살릴 수 있지만, 근본 해결을 안 하면 반복됩니다.
장애 후 기록과 재발 방지가 중요한 이유입니다.

✅ 22. 장애 기록 Postmortem

장애가 끝나면 기록을 남겨야 합니다.
이것을 Postmortem 또는 장애 회고라고 부릅니다.
목적은 책임 추궁이 아니라 재발 방지입니다.

➕ 22-1. 장애 기록 템플릿

# 장애 기록

## 요약
- 

## 발생 시간
- 시작:
- 감지:
- 복구:

## 영향 범위
- 고객 화면:
- 관리자 화면:
- API:
- 데이터 영향:

## 증상
- 

## 원인
- 

## 대응
- 

## 재발 방지
- [ ] 테스트 추가
- [ ] 모니터링 추가
- [ ] 배포 체크리스트 보강
- [ ] 문서 업데이트

## 관련 커밋/배포
-

➕ 22-2. 기록해야 하는 이유

같은 장애 반복 방지
배포 품질 개선
운영 신뢰도 향상
성과 자료로 활용
미래의 내가 원인 빠르게 이해

작은 장애라도 짧게 기록하면 좋습니다.
“왜 생겼고, 다음에 어떻게 막을지”만 남겨도 충분합니다.

✅ 23. 장애 대응 Runbook

Runbook은 장애 상황에서 따라 할 절차서입니다.
장애가 났을 때 매번 처음부터 생각하지 않게 도와줍니다.

➕ 23-1. Runbook 예시: API 502

# Runbook: API 502 Bad Gateway

## 증상
- API 요청 시 502 발생
- Nginx에서 upstream 연결 실패

## 확인 순서
1. `sudo systemctl status nginx`
2. `sudo tail -n 100 /var/log/nginx/error.log`
3. `curl http://localhost:3000/health`
4. `pm2 status` 또는 `docker compose ps`
5. 백엔드 로그 확인

## 임시 대응
- 백엔드 프로세스 재시작
- 최근 배포 롤백
- Nginx reload

## 재발 방지
- health check 추가
- 배포 후 자동 health check
- 프로세스 재시작 알림

➕ 23-2. Runbook 예시: 상담 신청 실패

# Runbook: 상담 신청 실패

## 확인 순서
1. 프론트 Console 확인
2. Network에서 POST /consults 상태 코드 확인
3. 백엔드 consult.create.failed 로그 확인
4. DB insert 오류 확인
5. 중복 신청 409인지 서버 오류 500인지 구분
6. 알림톡 실패가 신청 실패와 연결되어 있는지 확인

## 임시 대응
- 문제 배포 롤백
- 알림톡 실패와 신청 저장을 분리
- 수동 접수 안내

## 재발 방지
- 상담 신청 E2E 또는 smoke test 추가
- CONSULT_DUPLICATED 처리 테스트 추가
- 실패율 알림 추가

자주 발생할 수 있는 장애는 Runbook으로 만들어두는 것이 좋습니다.
1인 개발자라도 Runbook이 있으면 대응 속도가 빨라집니다.

✅ 24. 배포와 모니터링 연결

장애를 분석할 때 배포 시점이 매우 중요합니다.
배포 직후 에러율이 올라갔다면 최근 변경이 원인일 가능성이 큽니다.

➕ 24-1. 배포 기록에 남길 것

배포 시간
배포한 commit hash
배포자
변경 요약
환경변수 변경 여부
DB migration 여부
CloudFront invalidation 여부
Smoke Test 결과

➕ 24-2. 장애 분석 흐름

에러율 증가
  ↓
최근 배포 시간 확인
  ↓
해당 commit diff 확인
  ↓
변경된 API/UI/env 확인
  ↓
롤백 또는 hotfix 판단

배포 기록이 없으면 장애 원인 추적이 느려집니다.
GitHub Actions, 커밋, 릴리즈 노트, 작업 로그를 연결하는 것이 좋습니다.

✅ 25. 1인 개발자 기준 최소 모니터링 체계

처음부터 Datadog, Grafana, ELK 같은 큰 체계를 만들 필요는 없습니다.
최소한 핵심 흐름을 확인할 수 있으면 됩니다.

➕ 25-1. 최소 구성

백엔드 health endpoint
Nginx access/error log 확인
PM2 또는 Docker 로그 확인
GitHub Actions 배포 로그
CloudWatch 또는 서버 로그 보관
상담 신청 실패 로그
관리자 로그인 실패 로그
상태 변경 실패 로그
디스크 용량 확인

➕ 25-2. 알림 최소 구성

서버 다운
API health check 실패
디스크 사용량 위험
배포 실패
상담 신청 API 5xx 증가

➕ 25-3. 이후 확장

Sentry:
프론트/백엔드 에러 추적

CloudWatch:
AWS 로그/지표/알람

Grafana/Loki:
로그/메트릭 시각화

Uptime Kuma:
외부 health check

Datadog:
통합 APM/로그/모니터링

지금은 작게 시작해도 됩니다.
핵심은 “장애를 고객보다 먼저 알 수 있는가”입니다.

✅ 26. AI에게 로그/장애 분석을 맡길 때 좋은 질문법

AI에게 장애 분석을 요청할 때는 증상, 시간, 최근 변경, 로그, 상태 코드, 환경을 함께 줘야 합니다.
Secret과 개인정보는 반드시 마스킹해야 합니다.

➕ 26-1. 좋은 질문 예시

온라인 휴대폰 판매몰 NestJS API에서 상담 신청 실패가 발생했어.

상황:
1. 고객 화면에서 상담 신청 버튼을 누르면 실패 메시지가 뜸
2. 발생 시간은 2026-08-08 10:20~10:35
3. 최근 배포는 2026-08-08 10:10에 있었음
4. 프론트 Network에서는 POST /api/consults가 500을 반환함
5. Nginx access log 일부는 아래와 같음
6. 백엔드 error log 일부는 아래와 같음
7. DB 연결은 health check에서 정상임
8. 개인정보와 Secret은 마스킹했음

요청:
- 가장 가능성 높은 원인
- 먼저 확인할 로그
- 임시 대응 방법
- 근본 해결 방법
- 추가해야 할 테스트
- 추가해야 할 모니터링/알림
- 장애 기록 템플릿
순서로 정리해줘.

➕ 26-2. AI 답변 검증 기준

실제 Secret이나 개인정보를 요구하지 않는가?
최근 배포와 장애 발생 시간을 비교하는가?
프론트 문제와 백엔드/API 문제를 구분하는가?
Nginx/Backend/DB 로그를 계층별로 보라고 하는가?
임시 대응과 근본 해결을 구분하는가?
테스트와 모니터링 재발 방지를 제안하는가?
무작정 서버 재시작만 권하지 않는가?
운영 DB를 위험하게 조작하라고 하지 않는가?

✅ 27. 실무 체크리스트

➕ 27-1. 로그 체크리스트

API 요청 로그에 method/path/status/duration이 남는가?
requestId 또는 traceId가 있는가?
상담 신청/상태 변경/로그인 같은 핵심 이벤트 로그가 있는가?
에러 로그에 errorCode가 남는가?
개인정보가 마스킹되는가?
토큰/쿠키/Secret이 로그에 남지 않는가?
Nginx access/error log를 확인할 수 있는가?
PM2 또는 Docker 로그 확인 방법이 문서화되어 있는가?

➕ 27-2. 모니터링 체크리스트

/health endpoint가 있는가?
DB/Redis 연결 상태를 확인할 수 있는가?
API 5xx 증가를 감지할 수 있는가?
서버 CPU/RAM/Disk 상태를 확인할 수 있는가?
배포 실패를 알 수 있는가?
상담 신청 실패율을 확인할 수 있는가?
관리자 주요 액션 실패를 확인할 수 있는가?
로그 보관 기간이 정해져 있는가?

➕ 27-3. 장애 대응 체크리스트

장애 등급 기준이 있는가?
최근 배포와 장애 발생 시간을 비교하는가?
임시 대응과 근본 해결을 구분하는가?
롤백 기준이 있는가?
Runbook이 있는가?
장애 기록 템플릿이 있는가?
장애 후 테스트/모니터링을 보강하는가?
재발 방지 TODO가 실제로 처리되는가?

➕ 27-4. 보안 체크리스트

로그에 전화번호 원본이 남지 않는가?
로그에 이름/상담 메모 전체가 남지 않는가?
Authorization header가 남지 않는가?
DATABASE_URL이나 JWT Secret이 남지 않는가?
외부 로그 도구로 개인정보가 전송되지 않는가?
관리자 행동 로그가 필요한 범위에서 남는가?
로그 접근 권한이 제한되어 있는가?
장애 분석용 로그 공유 시 마스킹하는가?

📌 요약

로그는 서비스에서 어떤 일이 일어났는지 남기는 기록이고, 모니터링은 서버/API/DB/사용자 흐름 상태를 지속적으로 확인하는 체계입니다.
장애 대응에서 중요한 것은 감으로 추측하는 것이 아니라 Nginx, 백엔드, DB, CloudFront, CI/CD 로그를 계층별로 확인하는 것입니다.
좋은 로그는 timestamp, level, requestId, method, path, statusCode, durationMs, errorCode를 포함하고, 개인정보와 Secret은 반드시 마스킹해야 합니다.
상담 신청, 관리자 로그인, 상담 상태 변경, 엑셀 Export, 알림톡 발송 같은 핵심 이벤트는 성공/실패 로그를 남기는 것이 좋습니다.
Request ID가 있으면 프론트, Nginx, 백엔드, DB, 외부 API 로그를 하나의 요청 흐름으로 연결해 추적할 수 있습니다.
모니터링 지표는 CPU/RAM/Disk 같은 서버 지표뿐 아니라 API 5xx, 응답 시간, DB connection, 상담 신청 실패율 같은 서비스 지표까지 포함해야 합니다.
알림은 모든 에러에 거는 것이 아니라 고객 신청 실패, API 5xx 급증, health check 실패, 디스크 부족, 배포 실패처럼 실제 대응이 필요한 것에 걸어야 합니다.
장애 대응은 증상 확인 → 영향 범위 파악 → 최근 변경 확인 → 로그 확인 → 임시 대응 → 원인 분석 → 근본 해결 → 재발 방지 기록 순서로 진행하는 것이 좋습니다.
장애 후에는 Postmortem을 남겨 원인, 대응, 재발 방지 항목을 정리해야 같은 문제가 반복되지 않습니다.
1인 개발자 기준 최소 체계는 /health, Nginx/PM2/Docker 로그 확인법, 핵심 API 실패 로그, 배포 기록, 상담 신청 실패 알림부터 시작하면 충분합니다.

juni

이전 포스트

TIL - 20260807

다음 포스트