HTTP 5xx 서버 오류: 의미, 진단 및 해결 방법

이 오류의 의미와 확인 방법

다음 증상 중 하나 이상이 나타날 수 있습니다.

• 웹사이트 또는 API가 500부터 599까지의 HTTP 상태 코드를 반환합니다.
• 응답이 일반적인 서버 오류, 애플리케이션 오류 또는 브랜드가 표시된 reverse proxy, load balancer나 CDN 페이지로 나타납니다.
• 다른 페이지는 계속 작동하지만 특정 route, 작업 또는 API endpoint 하나만 실패합니다.
• 전체 서비스를 이용할 수 없거나 간헐적으로 오류가 반환됩니다.
• 요청이 느려진 후 504 또는 다른 게이트웨이 관련 5xx 응답으로 종료됩니다.
• 응답에 요청 ID, upstream 식별자 또는 응답을 생성한 계층을 파악하는 데 도움이 되는 서버별 오류 헤더가 포함됩니다.

가능성이 높은 순서의 주요 원인

일반적인 원인부터 덜 일반적인 원인 순으로 다음을 들 수 있습니다.

1. 애플리케이션 예외 또는 요청 처리 실패. 처리되지 않은 애플리케이션 오류, 잘못된 입력 경로 또는 문제가 있는 코드 변경으로 인해 500 응답이 발생할 수 있습니다.
2. 최근 배포 또는 구성 변경. 릴리스, 환경 변수 변경, 라우팅 변경 또는 서버 구성 오류가 특정 route나 전체 서비스에 영향을 줄 수 있습니다.
3. 비정상적인 백엔드 프로세스. 중지되었거나 충돌했거나 과부하 상태이거나 연결할 수 없는 애플리케이션 프로세스로 인해 프록시가 502 또는 503을 반환할 수 있습니다.
4. 종속성 장애. 데이터베이스 오류, 사용할 수 없는 내부 서비스, 느린 외부 서비스 또는 고갈된 연결 풀이 여러 종류의 5xx 코드로 나타날 수 있습니다.
5. 계층 간 타임아웃. upstream 서비스가 구성된 타임아웃 내에 응답하지 않으면 게이트웨이가 504를 반환할 수 있으며, 느린 종속성이 근본 원인일 수 있습니다.
6. 리소스 부족. 높은 CPU 또는 메모리 사용량, worker 포화, 디스크 공간 고갈 또는 연결 제한으로 인해 서비스를 이용할 수 없게 되거나 요청이 타임아웃될 수 있습니다.
7. 유지 관리 또는 의도적인 보호 조치. 서비스가 유지 관리 중이거나, 트래픽을 정리하고 있거나, rate limit을 적용 중이거나, 과부하로부터 보호하는 중일 때 503을 반환할 수 있습니다.
8. 계층별 상태 코드 동작. 동일한 근본 장애라도 애플리케이션, 웹 서버, reverse proxy, load balancer 또는 CDN 중 어느 계층이 응답을 생성했는지에 따라 서로 다른 코드가 반환될 수 있습니다.

해결 방법

1. 장애를 정확하게 기록하세요

정확한 상태 코드, 영향을 받는 URL 또는 API 작업, 시간대가 포함된 시각, 발생 빈도, 응답 본문 및 관련 응답 헤더를 기록하세요. 요청 ID 또는 trace ID가 있으면 보존하세요. 사이트를 방문하는 사용자라면 서버 설정을 변경하지 말고 이 정보를 서비스 운영자에게 전달하세요.

2. 응답을 생성한 계층을 확인하세요

오류 페이지 또는 JSON 본문, 헤더, 쿠키 및 서버 식별자를 정상적으로 성공한 응답과 비교하세요. 프레임워크별 오류 본문은 애플리케이션을 가리킬 수 있으며, 게이트웨이 또는 CDN 브랜드가 표시된 페이지는 origin이 응답을 생성하기 전에 요청이 실패했음을 의미할 수 있습니다. origin 로그에 일치하는 요청이 없으면 reverse proxy, load balancer 또는 CDN 로그를 확인하세요.

3. 광범위한 장애와 특정 route 장애를 구분하세요

승인된 영향이 적은 health endpoint와 정상 작동이 확인된 route를 테스트하세요. 특정 route 하나만 실패한다면 해당 route의 애플리케이션 코드, 데이터 접근 및 요청별 종속성을 점검하세요. 모든 route가 실패한다면 프로세스 상태, 배포 상태, 라우팅, 용량 및 공유 종속성을 우선적으로 확인하세요. health check를 대신해 프로덕션 endpoint를 반복해서 새로 고치지 마세요.

4. 동일한 타임스탬프의 로그를 서로 대조하세요

애플리케이션, 웹 서버, proxy/load balancer 및 종속성 로그를 함께 검토하세요. 먼저 요청 ID로 검색한 다음 타임스탬프와 endpoint를 기준으로 범위를 좁히세요. stack trace, 프로세스 재시작, connection refused 메시지, upstream 상태 코드, 타임아웃 메시지, 실패한 데이터베이스 호출 및 거부된 연결을 확인하세요. 로그를 공유하기 전에 자격 증명, 토큰 및 민감한 요청 데이터를 삭제하거나 마스킹하세요.

5. 최근 변경 사항과 서비스 상태를 확인하세요

장애가 시작되기 직전에 이루어진 배포, feature flag, 구성 변경, 인증서 또는 라우팅 업데이트, 유지 관리 활동 및 종속성 변경을 검토하세요. 백엔드 프로세스가 실행 중이고 health check를 통과하는지 확인하세요. 최근 변경 사항과 장애 사이에 강한 상관관계가 있다면 서비스에서 승인된 rollback 절차와 권한을 사용하세요. 운영 승인을 받지 않고 프로덕션 시스템을 재시작하거나 rollback하지 마세요.

6. 종속성과 리소스 부족을 확인하세요

데이터베이스 연결 가능 여부와 지연 시간, 내부 서비스 상태, 외부 종속성 응답, connection pool 사용량, queue 깊이, CPU, 메모리, 디스크 공간, worker 가용성 및 연결 제한을 점검하세요. 애플리케이션 프로세스 자체가 실행 중이어도 단순히 느린 종속성으로 인해 504가 발생할 수 있습니다. 타임아웃을 무작정 늘려 증상을 감추기보다 제한되었거나 실패한 구성 요소를 해결하세요.

7. 상태 코드로 조사 범위를 좁히세요

• 500 Internal Server Error: 애플리케이션 로그, 서버 오류, 실패한 route 및 최근 코드나 구성 변경부터 확인하세요.
• 502 Bad Gateway: 프록시와 upstream 간 연결 및 upstream 응답을 점검하세요. 백엔드가 중단되었는지, 연결을 종료하는지, 형식이 잘못된 데이터를 반환하는지 또는 잘못된 route를 통해 접근되고 있는지 확인하세요.
• 503 Service Unavailable: 유지 관리 상태, readiness 또는 health check, 과부하 제어, 프로세스 가용성 및 공유 종속성을 확인하세요.
• 504 Gateway Timeout: 시간이 어느 지점에서 소요되는지 측정하세요. upstream 지연 시간, 데이터베이스 또는 외부 호출, connection pool 및 각 계층의 타임아웃 설정을 확인하세요.
• 기타 5xx 상태: 정확한 상태 정의와 해당 상태를 생성한 구성 요소를 기준으로 조사하세요. 모든 5xx 응답의 원인이 같다고 가정하지 마세요.

8. 권한이 부여된 가장 제한적인 수정 사항을 적용하고 안전하게 확인하세요

환경의 change-control 프로세스에 따라 확인된 애플리케이션, 구성, 종속성 또는 용량 문제를 수정하세요. 이후 간단한 health endpoint, 이전에 실패한 작업 및 대표적인 종속 기능을 확인하세요. 중복 쓰기나 추가 부하를 발생시키지 않으면서 5xx 비율과 지연 시간이 정상으로 돌아왔는지 확인하세요. 프로세스 재시작, 트래픽 정리 또는 타임아웃 변경처럼 상태를 변경하는 작업이 포함된다면 예상되는 영향을 문서화하고 먼저 승인을 받으세요.

예방 및 해결 확인 방법

• route, 서비스 및 응답을 생성한 계층별로 5xx 비율, 지연 시간 및 가용성을 모니터링하세요.
• 과도한 부하를 만들지 않으면서 실제 종속성 요구 사항을 반영하는 readiness 및 liveness check를 사용하세요.
• 프록시, 애플리케이션 및 종속성 전반에서 요청 ID 또는 trace ID를 일관되게 유지하세요.
• 각 서비스 경계에서 제한이 설정되고 검토된 타임아웃과 연결 제한을 사용하세요. 느린 외부 호출로 모든 worker가 소모되지 않도록 하세요.
• 광범위한 장애로 이어지기 전에 리소스 포화, 프로세스 충돌, 데이터베이스 지연 시간, connection pool 고갈 및 디스크 부족에 대해 알림을 설정하세요.
• 단계적 배포, 상태 기반 트래픽 전환 및 검증된 rollback 절차를 사용하세요.
• 각 프록시, 애플리케이션 및 종속성이 어떤 5xx 코드를 생성할 수 있는지 문서화하여 대응 담당자가 500, 502, 503 및 504를 서로 같은 것으로 취급하지 않도록 하세요.
• 권한이 부여된 환경에서 종속성 저하 및 과부하 상황에 대한 동작을 정기적으로 테스트하세요.

자주 묻는 질문