503 서비스를 사용할 수 없음 - 백엔드 서버

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

동영상

다음 동영상에서 503 서비스를 사용할 수 없음 오류 해결에 대해 자세히 알아보세요.

동영상 설명
백엔드 서버에서 503 서비스를 사용할 수 없음 오류 다음에 대해 알아보세요.
  • Apigee Edge의 503 서비스를 사용할 수 없음 오류 소개
  • 백엔드 서버에서 실시간 503 서비스를 사용할 수 없는 경우의 문제 해결 및 해결

증상

클라이언트 애플리케이션은 API 프록시 호출 후 Service Unavailable 메시지와 함께 HTTP 응답 상태 503을 수신합니다.

오류 메시지

다음 오류 메시지 중 하나가 표시됩니다.

HTTP/1.1 503 Service Unavailable

HTTP/1.1 503 Service Unavailable: Back-end server is at capacity

또한 HTTP 응답에 다음과 같은 오류 메시지가 표시될 수 있습니다.

The server is temporarily unable to service your request due to
maintenance downtime or capacity problems. Please try again later.

참고: 위의 응답 코드와 오류 메시지는 예시일 뿐입니다. 경우에 따라 오류 메시지 없이 오류 응답 코드만 수신될 수 있습니다. 오류 응답 코드와 오류 메시지의 형식과 내용은 백엔드 서버 구현에 따라 다를 수 있습니다.

원인

HTTP 상태 코드 503은 서버에서 현재 수신 요청을 처리할 수 없음을 의미합니다. 일반적으로 이 오류는 서버가 너무 많거나 유지보수를 위해 일시적으로 다운되었을 때 발생합니다.

503 Service Unavailable 응답의 가능한 원인은 다음과 같습니다.

원인 설명 문제 해결 단계를 수행할 수 있는 사용자
과부하된 서버 백엔드 서버가 과부하되었거나 용량을 초과하여 새로 수신되는 클라이언트 요청을 처리할 수 없습니다. Edge 퍼블릭 및 프라이빗 클라우드 사용자
서버 유지보수 중 백엔드 서버가 일시적으로 유지보수 중일 수 있습니다. Edge 퍼블릭 및 프라이빗 클라우드 사용자

원인: 유지보수 중 과부하된 서버/서버

Apigee Edge에서는 다음과 같은 경우 백엔드 서버에서 503 서비스를 사용할 수 없음 오류가 반환될 수 있습니다.

  • 백엔드 서버가 과부하 상태이거나 사용 중이어서 새 요청을 처리할 수 없습니다.
  • 백엔드 서버가 유지보수로 인해 일시적으로 다운됩니다.

진단

다음 세 가지 방법 중 하나를 사용하여 오류를 진단할 수 있습니다.

  • 추적 도구
  • NGINX 액세스 로그
  • 백엔드 서버에 직접 호출

각 방법에 대해 자세히 알아보려면 아래의 탭을 클릭하세요.

추적 도구

  1. 추적 세션을 사용 설정하고 API를 호출하여 문제(503 서비스를 사용할 수 없음)를 재현합니다.
  2. 실패한 요청 중 하나를 선택하고 트레이스를 검사합니다.
  3. trace의 다양한 단계를 살펴보고 실패가 발생한 위치를 찾습니다.
  4. 대상 서버의 응답으로 503 오류가 반환된다면 503 오류의 원인은 대상 서버입니다.

    다음은 대상 서버에서 수신한 503 Service Unavailable 응답을 보여주는 샘플 trace 스크린샷입니다.

  5. 대상 서버에서 받은 응답 단계를 클릭하고 응답 헤더 및 응답 콘텐츠 섹션을 살펴보고 유용한 정보가 있는지 확인합니다.
    • 응답 헤더에는 오류 응답이 전송된 위치를 나타내는 서버 헤더가 포함될 수 있습니다.
    • 응답 콘텐츠에는 타겟 서버가 503 응답 코드를 전송한 이유에 대한 추가 정보가 포함될 수 있습니다.
  6. 아래 단계에 따라 trace의 AX(애널리틱스 데이터 기록됨) 단계에서 X-Apigee-fault-source 및 X-Apigee-fault-code의 값을 확인하여 503 오류가 대상 서버에서 발생했는지 확인합니다.
    1. 아래 스크린샷과 같이 AX (애널리틱스 데이터 기록됨) 단계를 클릭합니다.
    2. 단계 세부정보까지 아래로 스크롤하고 아래와 같이 X-Apigee-fault-code 및 X-Apigee-fault-source의 값을 결정합니다.
    3. X-Apigee-fault-source 및 X-Apigee-fault-code의 값이 아래 표에 표시된 값과 일치하면 503 오류가 대상 서버에서 발생한 것을 확인할 수 있습니다.
      응답 헤더 값
      X-Apigee-fault-source target
      X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode
  7. 프록시 체이닝을 사용 중인지, 즉 대상 서버/대상 엔드포인트가 Apigee에서 다른 프록시를 호출하고 있는지 확인하세요. 이를 확인하려면 다음 안내를 따르세요.
    1. Request sent to target server 단계로 돌아가서 Show Curl 버튼을 클릭하고 대상 서버 호스트 별칭을 결정합니다.
    2. 대상 서버 호스트 별칭이 가상 호스트 별칭을 가리키면 프록시 체이닝이 됩니다. 이 경우 실제로 503 Service Unavailable 오류를 일으키는 원인을 확인할 때까지 연결된 프록시에 위의 모든 단계를 반복해야 합니다. 이 경우 이 플레이북을 사용하여 진단할 수 있는 다른 단계에 있는 다른 체인 프록시에서도 503 Service 사용 불가 오류가 발생할 수 있습니다.
    3. 대상 서버 호스트 별칭이 백엔드 서버를 가리키는 경우 해결로 이동합니다.

NGINX 액세스 로그

NGINX 시트 로그를 참조하여 백엔드 서버에서 503 상태 코드를 보냈는지 확인할 수도 있습니다. 이 방법은 과거에 문제가 발생한 적이 있거나 문제가 간헐적으로 발생하고 UI에서 트레이스를 캡처할 수 없는 경우 특히 유용합니다. NGINX 액세스 로그에서 이 정보를 확인하려면 다음 단계를 따르세요.

  1. NGINX 액세스 로그를 확인합니다. 
    /opt/apigee/var/log/edge-router/nginx/<org>~<env>.<port#>_access_log
  2. 특정 기간 동안 특정 API 프록시에 대한 503 오류(과거에 문제가 발생한 경우) 또는 여전히 503과 함께 실패하는 요청에 대한 503 오류를 검색합니다.
  3. 503 오류가 발생한 경우 백엔드 서버에서 오류가 발생했는지 확인합니다. X-Apigee-fault-source 및 X-Apigee-fault-code 값이 아래 표에 표시된 값과 일치하면 백엔드 서버에서 503 오류가 발생한 것입니다.
    응답 헤더 값
    X-Apigee-fault-source target
    X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode

    다음은 대상 서버로 인해 발생한 503 오류를 보여주는 샘플 항목입니다.

  4. 특정 API 프록시를 검토하고 프록시 체인(예: 대상 서버/대상 엔드포인트가 Apigee에서 다른 프록시를 호출하지 않는 경우에 한합니다. 프록시 체이닝을 사용 중인 경우 실제로 503 Service Unavailable 오류를 일으키는 원인을 확인할 때까지 연결된 프록시에 위의 모든 단계를 반복해야 합니다. 이 경우 다른 단계의 다른 연결된 프록시에서도 503 Service Unavailable이 발생할 수 있으며, 이 경우 이 플레이북을 사용하여 진단할 수 있습니다.
  5. 프록시 체이닝을 사용하지 않는 것을 확인하고 백엔드 서버에서 503 오류가 발생한다면 해결로 이동합니다.

백엔드 서버 호출

백엔드 서버를 직접 호출하여 Apigee Edge를 통해 요청을 할 때 수신한 것과 동일한 503 Service Unavailable 응답을 받는지 확인할 수 있습니다.

  1. 요청의 일부로 백엔드 서버에 전달해야 하는 모든 필수 헤더, 쿼리 매개변수, 사용자 인증 정보가 있는지 확인합니다.
  2. 백엔드 서비스에 공개적으로 액세스할 수 있는 경우 curl 명령어, Postman 또는 기타 REST 클라이언트를 사용하여 백엔드 서버 API를 직접 호출할 수 있습니다.
  3. 메시지 프로세서에서만 백엔드 서버에 액세스할 수 있는 경우 curl 명령어, Postman 또는 기타 REST 클라이언트를 사용하여 메시지 프로세서에서 직접 백엔드 서버 API를 호출할 수 있습니다.
  4. 백엔드 서비스가 실제로 503 Service Unavailable 오류를 반환하는지 확인합니다.

해상도

백엔드 서버에서 503 오류가 발생한 것이 확실하다면 다음 단계에 따라 문제를 해결할 수 있습니다.

  • 백엔드 서버가 유지보수를 위해 다운되어 문제가 발생한 경우 유지보수 기간이 지난 후 백엔드 서버를 온라인으로 전환할 수 있습니다.
  • 백엔드 서버가 과부하되어 문제가 발생한 경우 백엔드 서버에 액세스할 수 있는 경우 문제를 해결합니다. 그렇지 않으면 백엔드 서버팀과 협력하여 문제를 해결해야 할 수 있습니다.

API 모니터링을 사용한 문제 진단

API 모니터링을 사용하면 문제 영역을 빠르게 격리하여 오류, 성능, 지연 시간 문제를 진단하고 개발자 앱, API 프록시, 백엔드 대상, API 플랫폼 등의 원인을 진단할 수 있습니다.

API Monitoring을 사용하여 API의 5xx 문제를 해결하는 방법을 보여주는 샘플 시나리오를 단계별로 살펴보세요. 예를 들어 Messaging.adaptors.http.flow.ErrorResponseCode 결함의 수가 특정 기준점을 초과하면 알림을 받도록 알림을 설정할 수 있습니다.

진단 정보 수집 필요

위의 안내를 따른 후에도 문제가 지속되면 다음 진단 정보를 수집한 후 Apigee 지원팀에 문의하세요.

퍼블릭 클라우드 사용자인 경우 다음 정보를 제공하세요.

  • 조직 이름
  • 환경 이름
  • API 프록시 이름
  • 503 오류를 재현하기 위한 curl 명령어 완료
  • 503 Service Unavailable 오류가 발생한 요청이 포함된 추적 파일
  • 현재 503 오류가 발생하지 않는 경우 이전에 503 오류가 발생했을 때의 시간대 정보를 제공합니다.

프라이빗 클라우드 사용자인 경우 다음 정보를 제공하세요.

  • 실패한 요청에 대해 관찰된 전체 오류 메시지입니다.
  • 503 오류가 발생한 조직, 환경 이름, API 프록시 이름입니다.
  • API 프록시 번들입니다.
  • 503 Service Unavailable 오류가 발생한 요청이 포함된 추적 파일입니다.
  • NGINX 액세스 로그 
    /opt/apigee/var/log/edge-router/nginx/<org>~<env>.<port#>_access_log
  • 메시지 프로세서 로그 
    /opt/apigee/var/log/edge-message-processor/logs/system.log
  • 503 오류가 발생한 시간대 정보가 포함된 기간입니다.