CloudWatch 로그만으로 문제 구간 좁히기

AWS 실전 운영 시리즈 6/12

운영 중 문제가 생기면 가장 먼저 보는 것은 로그다.

하지만 로그가 있다고 해서 바로 원인을 알 수 있는 것은 아니다.

중요한 것은 어떤 순서로 볼 것인가다.

React SPA, CloudFront, API Gateway, Lambda, 애플리케이션 서버, 데이터베이스가 이어진 구조에서는 증상을 계층별로 나눠 봐야 한다.

문제 상황

운영 콘솔에서 사용자가 이렇게 말할 수 있다.

• 화면이 안 떠요.
• 데이터가 안 바뀌어요.
• 다운로드가 계속 기다려요.
• 버튼을 눌렀는데 아무 일도 안 일어나요.
• 어제는 됐는데 오늘은 안 돼요.

이 말만 듣고 원인을 알 수는 없다.

브라우저 문제일 수도 있고, CloudFront 캐시 문제일 수도 있고, API Gateway 설정 문제일 수도 있고, Lambda 오류일 수도 있고, DB 연결 실패일 수도 있다.

그래서 로그를 계층별로 확인해야 한다.

전체 요청 경로를 먼저 그린다

먼저 사용자의 요청이 어떤 경로를 지나는지 그린다.

상주 API 서버가 있다면 경로는 이렇게 될 수 있다.

요청 경로를 모르면 로그도 어디서부터 봐야 할지 모른다.

1단계. 브라우저에서 확인한다

가장 먼저 볼 곳은 브라우저 DevTools다.

Console과 Network를 확인한다.

확인할 것:

• JavaScript 오류가 있는가
• API 요청이 나갔는가
• status code가 무엇인가
• CORS 오류인가
• 요청 URL이 올바른가
• 응답 body에 오류 메시지가 있는가
• 정적 파일이 404인지
• 이전 JS 파일을 받고 있는지

브라우저에서 API 요청이 아예 나가지 않았다면 프론트엔드 문제일 수 있다.

API 요청이 나갔고 4xx/5xx가 돌아왔다면 다음 계층으로 간다.

2단계. CloudFront를 확인한다

화면 자체가 안 뜨거나 배포한 내용이 반영되지 않는다면 CloudFront를 본다.

확인할 것:

• 정적 파일 응답이 200인가
• cache hit인가 miss인가
• index.html이 최신인가
• SPA fallback이 동작하는가
• S3 origin에 파일이 존재하는가
• invalidation이 필요한가

CloudFront 문제는 애플리케이션 코드 오류처럼 보일 수 있다.

예를 들어 새 배포 후 이전 JS 파일과 새 HTML이 섞이면 화면이 깨질 수 있다.

이때는 Lambda 로그를 봐도 답이 없다.

3단계. API Gateway를 확인한다

API 요청이 실패했다면 Gateway를 본다.

확인할 것:

• 요청이 Gateway까지 도달했는가
• path와 method가 맞는가
• OPTIONS preflight가 성공했는가
• stage 배포가 되었는가
• Gateway에서 4xx/5xx가 발생했는가
• Lambda integration이 연결되어 있는가
• request/response mapping 문제가 있는가

CORS 오류라면 특히 OPTIONS method와 MOCK Integration을 확인한다.

Gateway 설정을 바꾼 뒤 stage 배포를 하지 않으면 변경이 반영되지 않을 수 있다.

4단계. Lambda CloudWatch Logs를 확인한다

Gateway를 통과했다면 Lambda 로그를 본다.

확인할 것:

• Lambda가 호출되었는가
• import 오류가 있는가
• 환경 변수가 누락되었는가
• timeout이 발생했는가
• 권한 오류가 있는가
• DB 연결 실패가 있는가
• S3 접근 실패가 있는가
• 예외 stack trace가 있는가

Lambda 로그에서는 request id가 중요하다.

가능하면 API 응답이나 로그에 request id를 남겨 추적할 수 있게 하는 것이 좋다.

5단계. 데이터 저장소를 확인한다

Lambda가 정상 호출되었지만 데이터가 이상하다면 저장소를 본다.

S3라면:

• 파일이 존재하는가
• 마지막 수정 시간이 기대와 맞는가
• JSON 형식이 정상인가
• public 데이터와 internal 데이터가 섞이지 않았는가
• latest와 monthly 중 어느 것을 화면이 읽는가

DB라면:

• 연결이 가능한가
• 쿼리가 timeout 되는가
• 필요한 row가 있는가
• 작업 상태가 멈춰 있는가
• read/write host를 혼동하지 않았는가

데이터 문제는 API 문제가 아니라 원천 데이터 문제일 수 있다.

6단계. 상주 API 서버 로그를 확인한다

일부 API가 Lambda가 아니라 Node/Express 같은 상주 서버를 거친다면 별도로 봐야 한다.

확인할 것:

• container가 실행 중인가
• health check가 성공하는가
• DB connection pool이 정상인가
• 인증 쿠키가 전달되는가
• CORS 설정이 맞는가
• 서버 로그에 예외가 있는가

상주 서버는 Lambda와 다르게 인스턴스 상태, process 상태, container 상태도 확인해야 한다.

증상별 시작점

증상에 따라 먼저 볼 곳이 다르다.

증상	먼저 볼 곳
화면 흰 화면	브라우저 Console, CloudFront 정적 파일
새 배포 미반영	CloudFront cache, S3 파일
CORS 오류	브라우저 Network, API Gateway OPTIONS
API 500	Lambda Logs 또는 API 서버 로그
다운로드 대기	job table, worker Lambda logs
데이터 미갱신	원천 데이터, sync logs, S3 timestamp
인증 실패	cookie 전달, API 서버 auth logs

이 표를 운영 문서에 두면 장애 대응이 빨라진다.

로그 위치를 문서에 남긴다

로그는 위치를 알아야 쓸 수 있다.

• CloudFront access log 위치
• API Gateway access log 위치
• Lambda log group 이름
• EC2 또는 container 로그 확인 방법
• Apps Script 실행 로그 위치
• DB 로그 또는 metric 위치

로그만으로 부족한 것

CloudWatch Logs만으로 모든 것을 해결할 수는 없다.

필요하면 metric과 tracing도 봐야 한다.

• Lambda duration
• Lambda error count
• Lambda throttle
• API Gateway 4xx/5xx
• CloudFront cache hit ratio
• DB connection count
• DB slow query

하지만 작은 운영 콘솔에서는 우선 로그 위치와 확인 순서만 잘 정리해도 큰 도움이 된다.

정리

문제가 생겼을 때 로그를 많이 보는 것보다 중요한 것은 순서다.

브라우저에서 시작해 CloudFront, API Gateway, Lambda, 저장소, 상주 서버로 내려가며 요청이 어디까지 갔는지 확인한다.

좋은 운영 문서는 다음을 알려준다.

• 요청 경로
• 계층별 로그 위치
• 증상별 첫 확인 지점
• 자주 발생하는 원인
• 다음 계층으로 넘어가는 기준

CloudWatch 로그는 단순 기록이 아니다.

운영 중 문제 구간을 좁히는 지도다.

함께 볼 GitHub 저장소

• aws-console-operations-notes