새벽 웹개발 배포 뒤 500 오류가 터질 때 디버깅 순서

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

배포를 마친 새벽, 모니터링 화면에 HTTP 500 오류가 연속으로 찍히면 어디부터 확인해야 할까요? 로그를 무작정 넘기거나 방금 올린 코드를 곧바로 되돌리기보다, 장애 범위를 좁히는 순서가 먼저 필요합니다. 크림코드는 백엔드 엔지니어 류선우와 함께 웹개발 배포 장애를 빠르게 진단하는 실전 질문을 나눴습니다.

코딩은 명령을 작성하는 행위이지만, 운영 환경의 프로그래밍은 코드와 데이터베이스, 네트워크, 외부 서비스가 함께 움직이는 과정입니다. 기본 개념은 지식백과의 코딩 설명과 프로그래밍 용어 해설에서도 확인할 수 있습니다.

Q. 500 오류를 발견하자마자 무엇부터 봐야 하나요?

A. 오류 한 건보다 장애의 경계부터 그려야 합니다

류선우 엔지니어는 첫 행동으로 코드 수정을 권하지 않습니다. 먼저 언제 시작됐고, 어떤 요청에서 발생하며, 모든 사용자가 영향을 받는지를 확인해야 합니다. 배포 직후라는 이유만으로 새 코드가 원인이라고 단정하면 결제사 장애나 데이터베이스 연결 고갈처럼 동시에 발생한 외부 문제를 놓칠 수 있습니다.

예를 들어 로그인은 정상인데 주문 생성만 실패한다면 서버 전체가 죽은 상황은 아닙니다. 특정 API 경로, HTTP 메서드, 사용자 권한, 요청 데이터 크기를 기준으로 오류율을 나누면 조사 대상이 빠르게 줄어듭니다. 평균 응답 시간만 보지 말고 성공 요청과 실패 요청의 지연 시간을 따로 비교해야 합니다.

장애 시각 전후 10~15분을 기준으로 배포, 환경 변수 변경, 데이터베이스 마이그레이션, 인증서 갱신 기록도 한 화면에 놓아보세요. 서로 다른 시스템의 시계가 어긋날 수 있으므로 로그의 타임존이 UTC인지 한국 표준시인지 확인하는 것도 중요합니다.

1. 장애 시작 시각과 최초 알림 시각을 구분합니다.
2. 실패한 API 경로와 정상 API 경로를 비교합니다.
3. 오류율, 응답 시간, 요청량의 변화를 함께 봅니다.
4. 직전 배포와 설정 변경 내역을 시간순으로 배치합니다.
5. 전체 장애인지 특정 사용자·기능 장애인지 표시합니다.

“첫 5분의 목표는 원인을 맞히는 것이 아니라, 영향 범위를 설명할 수 있는 상태를 만드는 것입니다.”

Q. 로그가 너무 많을 때 어떤 단서가 유효한가요?

A. 요청 식별자로 한 사용자의 흐름을 연결합니다

수천 줄의 로그에서 ‘error’만 검색하면 같은 예외가 반복되어 중요한 최초 원인이 묻힙니다. 웹 서버가 요청을 받을 때 생성한 request ID 또는 trace ID로 API 게이트웨이, 애플리케이션, 작업 큐, 데이터베이스 호출을 연결하세요. 사용자가 알려준 발생 시각과 계정 번호는 검색 범위를 줄이는 보조 조건으로 활용합니다.

좋은 오류 로그에는 요청 경로, 상태 코드, 처리 시간, 배포 버전, 실행 환경과 예외 종류가 들어갑니다. 반면 비밀번호, 세션 토큰, 주민등록번호, 카드번호 같은 민감 정보는 남기면 안 됩니다. 요청 본문 전체를 기록하기보다 필드 존재 여부, 데이터 형식, 길이처럼 진단에 필요한 정보만 구조화해 보관하는 편이 안전합니다.

스택 트레이스는 아래쪽의 긴 프레임보다 처음 발생한 예외와 원인 체인을 우선 읽습니다. ‘NullPointer’ 같은 결과만 보지 말고 그 직전에 데이터 조회 결과가 비어 있었는지, 외부 API가 예상과 다른 응답을 보냈는지 살펴야 합니다. 프로그래밍 과정이 단순 문법 입력을 넘어 문제를 절차화하는 작업이라는 점은 코딩 개념 자료와도 맞닿아 있습니다.

• 검색 키: trace ID, 사용자 ID의 비식별 값, API 경로, 배포 버전
• 시간 범위: 오류 발생 전후와 직전 정상 요청까지 포함
• 비교 대상: 같은 요청의 성공 로그와 실패 로그
• 보안 원칙: 토큰과 개인정보를 마스킹하고 접근 권한 제한

Q. 코드와 인프라 중 어느 쪽 문제인지 어떻게 나누나요?

A. 증상과 관측 지표를 짝지어 가설을 검증합니다

500 오류는 애플리케이션 예외만을 의미하지 않습니다. 연결 풀 고갈, 메모리 부족, 디스크 용량 부족, 잘못된 프록시 설정도 사용자에게는 비슷한 실패로 보입니다. 따라서 CPU가 높다는 사실 하나로 인프라 문제라고 판단하지 말고, 오류 발생 시점과 자원 변화가 실제로 일치하는지 확인해야 합니다.

새 버전 인스턴스에서만 오류가 나고 이전 버전은 정상이라면 코드나 설정 차이가 유력합니다. 모든 버전에서 데이터베이스 타임아웃이 동시에 늘었다면 공용 저장소나 네트워크를 의심할 수 있습니다. 특정 입력에서만 재현된다면 유효성 검사, 문자 인코딩, 날짜 형식, 빈 값 처리처럼 요청 데이터에 의존하는 로직을 살펴봅니다.

다음 비교표처럼 증상을 가설과 연결하면 팀원끼리 같은 기준으로 움직일 수 있습니다. 단, 표는 확정 판정표가 아니라 조사 우선순위입니다. 실제 원인은 로그, 메트릭, 변경 이력이라는 세 가지 증거가 만나는 지점에서 확정해야 합니다.

• 배포 버전별로 트래픽과 오류율을 분리합니다.
• 애플리케이션 지표와 서버 자원 지표의 시각을 맞춥니다.
• 외부 서비스 호출에는 타임아웃과 재시도 횟수를 표시합니다.
• 재현 입력은 개인정보를 제거한 뒤 별도 테스트 환경에서 사용합니다.

Q. 즉시 롤백할지 현장에서 고칠지 판단 기준은 무엇인가요?

A. 복구 시간과 데이터 위험을 먼저 계산합니다

사용자 영향이 크고 이전 버전으로 안전하게 돌아갈 수 있다면 롤백이 빠른 선택입니다. 특히 로그인, 결제, 주문처럼 핵심 기능의 실패율이 계속 오를 때는 완벽한 원인 규명보다 서비스 복구가 우선입니다. 반대로 데이터베이스 스키마가 이미 비호환 방식으로 변경됐거나 새 버전이 생성한 데이터를 이전 코드가 읽지 못한다면 단순 롤백이 더 큰 장애를 만들 수 있습니다.

핫픽스는 수정 범위가 작고 재현 테스트가 가능하며 배포 경로가 검증됐을 때 선택합니다. 조건문 한 줄처럼 보여도 리뷰 없이 운영 서버에서 직접 수정해서는 안 됩니다. 최소한 실패 사례 테스트, 정상 경로 회귀 테스트, 배포 후 관측 지표와 되돌리기 조건을 준비해야 합니다.

기능 플래그가 있다면 문제가 된 기능만 끄는 방법도 유용합니다. 전체 서비스를 내리지 않고 위험한 경로를 차단할 수 있기 때문입니다. 다만 플래그가 데이터 쓰기 중간에 작동하면 불완전한 상태가 남을 수 있으므로, 요청 단위로 일관되게 적용되는지 확인해야 합니다.

• 롤백: 영향이 크고 이전 버전과 데이터 호환성이 보장될 때
• 핫픽스: 원인이 명확하고 수정·검증·재배포 시간이 짧을 때
• 기능 차단: 특정 기능만 분리할 수 있고 핵심 서비스는 유지해야 할 때
• 트래픽 축소: 과부하가 원인이며 일부 요청을 지연 처리할 수 있을 때

“복구 결정에는 ‘무엇을 바꿀까’뿐 아니라 ‘몇 분 안에 어떤 지표가 회복되지 않으면 되돌릴까’까지 포함돼야 합니다.”

Q. 같은 500 오류가 다음 배포에서 또 나오지 않게 하려면요?

A. 재발 방지는 테스트 한 개보다 배포 안전장치의 조합입니다

독자들이 가장 자주 묻는 질문은 “이번 버그를 테스트로 추가하면 충분한가요?”입니다. 해당 입력을 재현하는 테스트는 반드시 필요하지만 그것만으로는 부족합니다. 장애는 코드 결함과 운영 조건이 겹쳐 나타나는 경우가 많으므로 자동 테스트, 점진 배포, 관측 가능성, 복구 연습을 함께 개선해야 합니다.

우선 실패 요청을 개인정보가 제거된 테스트 데이터로 바꾸고, 수정 전에는 실패하며 수정 후에는 통과하는 회귀 테스트를 만듭니다. 이어 소수 인스턴스에만 새 버전을 보내는 카나리 배포를 적용해 기존 버전과 오류율을 비교합니다. 오류율이나 지연 시간이 기준을 넘으면 자동 중단되도록 설정하면 새벽 담당자의 감각에만 의존하지 않을 수 있습니다.

장애 기록에는 담당자를 탓하는 표현 대신 탐지가 늦어진 이유, 복구를 지연한 정보, 안전장치가 작동하지 않은 조건을 적습니다. 예를 들어 “개발자가 환경 변수를 빠뜨렸다”보다 “필수 환경 변수 검증이 시작 단계에 없었다”라고 써야 다음 행동이 분명해집니다. 수정 작업마다 담당자와 기한을 붙이고, 다음 배포 전에 실제로 완료됐는지 확인하세요.

1. 실패 사례를 회귀 테스트로 고정하고 정상 경로도 함께 검사합니다.
2. 애플리케이션 시작 시 필수 설정과 데이터베이스 연결을 검증합니다.
3. 배포 버전별 오류율을 비교하는 대시보드와 경보를 만듭니다.
4. 카나리 배포의 중단 기준과 자동 롤백 조건을 수치로 정합니다.
5. 복구 절차를 문서에만 두지 말고 정기적으로 실행해 시간을 측정합니다.
6. 재발 방지 항목이 끝날 때까지 장애 기록의 상태를 닫지 않습니다.