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

Apigee Edge 문서입니다.
Go to the Apigee X 문서로 이동합니다. info

동영상

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

동영상 설명
백엔드 서버의 503 서비스를 사용할 수 없음 오류 다음을 알아봅니다.
  • Apigee Edge의 503 서비스를 사용할 수 없음 오류 소개
  • 백엔드 서버의 실시간 503 서비스를 사용할 수 없음 문제 해결 및 해결

증상

클라이언트 애플리케이션은 API 프록시 호출 후 서비스를 사용할 수 없음 메시지와 함께 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 서비스를 사용할 수 없음 응답의 가능한 원인은 다음과 같습니다.

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

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

Apigee Edge에서 503 서비스를 사용할 수 없음 오류는 다음 상황 중 하나에서 백엔드 서버에서 반환될 수 있습니다.

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

진단

오류를 진단하려면 다음 세 가지 방법 중 하나를 사용하면 됩니다.

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

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

trace 도구

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

    다음은 대상 서버에서 수신된 503 서비스를 사용할 수 없음 응답을 보여주는 샘플 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 대상
      X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode
  7. 프록시 체이닝을 사용하고 있는지, 즉 대상 서버/대상 엔드포인트가 다른 프록시를 호출하는지 확인합니다. 이를 확인하려면 다음 단계를 따르세요.
    1. 대상 서버에 전송된 요청 단계로 돌아가서 Curl 표시 버튼을 클릭하고 대상 서버 호스트 별칭을 확인합니다.
    2. 대상 서버 호스트 별칭이 가상 호스트 별칭을 가리키는 경우 프록시 체이닝입니다. 프록시 체이닝입니다. 이 경우 503 서비스를 사용할 수 없음 오류를 실제로 일으키는 원인을 확인할 때까지 체이닝된 프록시에 대해 위의 모든 단계를 반복해야 합니다. 이러한 경우 503 서비스를 사용할 수 없음 오류가 다른 단계의 다른 체이닝된 프록시에서도 발생할 수 있으며 이 플레이북을 사용하여 진단할 수 있습니다.
    3. 대상 서버 호스트 별칭이 백엔드 서버를 가리키면 해결 방법으로 이동합니다.

NGINX 액세스 로그

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

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

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

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

백엔드 서버 호출

백엔드 서버를 직접 호출하고 Apigee Edge를 통해 요청이 이루어졌을 때 수신된 것과 동일한 503 서비스를 사용할 수 없음 응답을 수신하는지 확인할 수 있습니다.

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

해결 방법

503 오류가 백엔드 서버에서 발생한 것임을 확인한 경우 다음을 수행하여 문제를 해결할 수 있습니다.

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

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

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

API 모니터링을 사용하여 API의 5xx 문제를 해결하는 방법을 보여주는 샘플 시나리오를 살펴보세요. 예를 들어 messaging.adaptors.http.flow.ErrorResponseCode 오류 수가 특정 기준을 초과할 때 알림을 받도록 알림을 설정할 수 있습니다.

진단 정보 수집 필요

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

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

  • 조직 이름
  • 환경 이름
  • API 프록시 이름
  • 503 오류를 재현하는 전체 curl 명령어
  • 503 서비스를 사용할 수 없음 오류가 있는 요청이 포함된 trace 파일
  • 503 오류가 현재 발생하지 않는 경우 과거에 503 오류가 발생한 시간대 정보가 포함된 기간을 제공합니다.

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

  • 실패한 요청에 대해 관찰된 전체 오류 메시지
  • 503 오류가 관찰되는 조직, 환경 이름, API 프록시 이름
  • API 프록시 번들
  • 503 서비스를 사용할 수 없음 오류가 있는 요청이 포함된 trace 파일
  • NGINX 액세스 로그 
    /opt/apigee/var/log/edge-router/nginx/<org>~<env>.<port#>_access_log
  • 메시지 프로세서 로그 
    /opt/apigee/var/log/edge-message-processor/logs/system.log
  • 503 오류가 발생한 시간대 정보가 포함된 기간