현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보
증상
클라이언트 애플리케이션은 API 호출에 대한 응답으로 "Gateway Timeout"이라는 메시지와 함께 HTTP 상태 코드 504를 수신합니다.
이 오류 응답은 클라이언트가 API 호출을 실행하는 동안 Apigee Edge 또는 백엔드 서버에서 적시에 응답을 받지 못했음을 나타냅니다.
오류 메시지
클라이언트 애플리케이션은 다음과 같은 응답 코드를 수신합니다.
HTTP/1.1 504 Gateway Timeout
이 코드 뒤에 아래와 유사한 오류 메시지가 표시될 수 있습니다.
<html> <head><title>504 Gateway Timeout</title></head> <body bgcolor="white"> <center><h1>504 Gateway Timeout</h1></center> </body> </html>
게이트웨이 시간 초과의 원인은 무엇인가요?
Apigee Edge를 통해 작성된 API 요청의 일반적인 경로는 아래 그림과 같이 클라이언트 -> 라우터 -> 메시지 프로세서 -> 백엔드 서버입니다.
클라이언트 애플리케이션, 라우터, 메시지 프로세서는 적절한 제한 시간 값으로 구성됩니다. Apigee Edge는 제한 시간 값을 기준으로 일정 기간 내에 모든 API 요청에 대한 응답을 예상합니다. 지정된 시간 내에 응답이 수신되지 않으면 504 Gateway Timeout 응답이 반환됩니다.
가능한 원인
Apigee Edge에서 백엔드 서버로부터 504 게이트웨이 시간 초과 응답의 일반적인 원인은 다음과 같습니다.
| 원인 | 설명 | 문제 해결 안내: |
|---|---|---|
| 백엔드 서버가 504 게이트웨이 시간 초과로 응답하는 경우 | 백엔드 서버가 타임아웃되고 메시지 프로세서에 504 Gateway Timeout 응답을 반환합니다. | 에지 프라이빗 및 퍼블릭 클라우드 사용자 |
백엔드 서버가 504 게이트웨이 시간 초과로 응답하는 경우
백엔드 서버가 HTTP 응답 코드 504 Gateway Timeout으로 응답할 수 있습니다.
진단
이 섹션에서는 504 게이트웨이 시간 초과를 올바르게 진단하는 방법을 설명합니다. 프라이빗 클라우드 및 퍼블릭 클라우드 사용자를 위한 절차가 모두 나와 있습니다.
절차 #1: Trace 사용 (비공개 및 퍼블릭 클라우드 사용자)
- Apigee UI에서 영향을 받은 API에 Trace를 사용 설정합니다.
- 백엔드 서버에 요청을 보냅니다.
- 실패한 API 요청에 Trace에서 백엔드 서버의 504 응답이 표시되면 504 게이트웨이 시간 초과의 원인이 백엔드 서버입니다.
- 응답 시간을 확인하려면 Trace에서 Response received from target server(대상 서버에서 수신된 응답) 단계를 클릭하세요. 표시된 예에서 경과된 시간은 60, 004ms입니다.
단계 세부정보 섹션에서는 추가 정보를 제공합니다.
- 백엔드 서버에서 수신된 504 Gateway Timeout 응답이 강조표시됩니다.
- 응답 콘텐츠 섹션에는 백엔드 서버 응답의 전체 본문이 표시됩니다. 앞서 언급했듯이 응답 페이로드의 형식과 콘텐츠는 백엔드 서버 구현에 따라 다를 수 있습니다.
- 응답 헤더 > 서버 섹션에는 응답이 시작된 위치가 표시될 수 있습니다.
- 애널리틱스 데이터를 보고 진단을 확인하려면 아래 그림과 같이 Trace에서 Analytics Data Recorded 단계를 클릭하세요.
단계 세부정보의 응답 헤더 섹션에는 아래 그림과 같이
X-Apigee-fault-code및X-Apigee-fault-source값이 표시됩니다.
이러한 필드에 아래 표에 표시된 값이 포함되어 있으면 504 오류 응답이 백엔드 서버에서 발생합니다.
응답 헤더 값 X-Apigee-fault-source target X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode -
프록시 체이닝을 확인합니다. 백엔드 서버가 Apigee에서 다른 프록시를 호출하는지 확인하려면 다음 단계를 따르세요.
- Request sent to target server 단계로 돌아가서 Show Curl 버튼을 클릭하여 백엔드 서버 호스트 별칭을 확인합니다.
- 백엔드 서버 호스트 별칭이 가상 호스트 별칭을 가리키는 경우 프록시 체이닝이 사용됩니다. 연결된 프록시마다 위의 단계를 반복하여 504 게이트웨이 시간 초과 오류 응답의 원인을 진단합니다. 요청/응답 주기의 다른 단계에서 연결된 프록시에서 발생하는 504 게이트웨이 시간 초과는 이 플레이북을 사용하여 진단할 수 있습니다.
- 백엔드 서버 호스트 별칭이 백엔드 서버를 가리키는 경우 해결을 진행합니다.
절차 #2: 백엔드 서버 API 직접 호출 (공개 및 프라이빗 클라우드 사용자)
백엔드 서버를 직접 호출하여 Apigee Edge를 통해 요청을 수행할 때 발생한 것과 동일한 504 게이트웨이 시간 제한 응답 동작을 확인합니다.
- 요청의 일부로 백엔드 서버에 전달하는 데 필요한 모든 헤더, 쿼리 매개변수, 사용자 인증 정보가 있는지 확인합니다.
- 백엔드 서비스에 공개적으로 액세스할 수 있으면
curl명령어, Postman 또는 기타 REST 클라이언트를 사용하여 백엔드 서버 API를 직접 호출할 수 있습니다. - 메시지 프로세서에서만 백엔드 서버에 액세스할 수 있으면
curl명령어, Postman 또는 기타 REST 클라이언트를 사용하여 메시지 프로세서에서 직접 백엔드 서버 API를 호출합니다. - 백엔드 서비스가 504 게이트웨이 시간 제한 응답을 반환하면 해결을 진행합니다.
절차 #3: NGINX 액세스 로그 확인 (프라이빗 클라우드 사용자만 해당)
NGINX 액세스 로그는 백엔드 서버에서 504 오류 응답을 보냈는지 확인하는 데 도움이 됩니다. 이 방법은 이전에 발생한 문제이거나, 간헐적으로 발생하거나 Trace에서 캡처할 수 없는 경우에 특히 유용합니다. 다음 단계에 따라 NGINX 액세스 로그를 확인합니다.
- 다음 명령어를 사용하여 NGINX 액세스 로그를 확인합니다.
/opt/apigee/var/log/edge-router/nginx/ ORG ~ENV.PORT# _access_log
- 영향을 받는 API 프록시에 504 오류 응답이 있는지 확인합니다. 특정 기간을 확인하거나 문제가 과거에 발생했는지 확인하거나 504 오류 응답으로 요청이 여전히 실패하는지 확인할 수 있습니다.
- 504 오류 응답이 있는 경우 오류 응답이 백엔드 서버에서 시작되었는지 확인합니다.
- 영향을 받는 API 프록시를 검토하여 프록시 연결이 있는지 확인합니다. 즉, 백엔드 서버/대상 엔드포인트가 Apigee에서 다른 프록시를 호출하고 있는지 확인합니다. API 프록시가 프록시 체인 을 사용하는 경우 연결된 프록시마다 위의 단계를 반복하여 504 Gateway Timeout 오류 응답의 원인을 진단합니다. 다른 단계에서 연결된 프록시에서 발생하는 504 게이트웨이 시간 초과는 이 플레이북을 사용하여 진단할 수 있습니다.
- 프록시 체이닝이 없고 504 오류 응답이 백엔드 서버에서 발생하면 해결을 진행합니다.
아래 그림은 대상 서버로 인한 504 오류 응답을 보여주는 NGINX 로그 항목의 예입니다.
X-Apigee-fault-source 및 X-Apigee-fault-code 필드에 아래 표에 표시된 값이 포함된 경우 504 응답이 백엔드 서버에서 시작됩니다.
| 응답 헤더 | 값 |
|---|---|
| X-Apigee-fault-source | target |
| X-Apigee-fault-code | messaging.adaptors.http.flow.ErrorResponseCode |
절차 #4: API 모니터링 사용 (퍼블릭 클라우드 사용자만 해당)
API 모니터링을 사용하면 문제 영역을 빠르게 격리하여 오류, 성능, 지연 시간 문제를 진단하고 개발자 앱, API 프록시, 백엔드 대상, API 플랫폼 등의 원인을 진단할 수 있습니다.
API Monitoring을 사용하여 API의 5xx 문제를 해결하는 방법을 보여주는 샘플 시나리오를 단계별로 살펴보세요. 예를 들어 504 상태 코드 수가 특정 기준을 초과하면 관리자에게 알리도록 알림을 설정할 수 있습니다.
해상도
위에서 설명한 진단 절차를 통해 백엔드 서버팀과 협력하여 백엔드 서버의 문제를 해결할 수 있습니다. 여기에는 백엔드 서버의 제한 시간 또는 대상 서버 앞에 있는 부하 분산기의 제한 시간을 조정하는 것이 포함될 수 있습니다.
진단 정보 수집
문제가 계속되면 다음 진단 정보를 Apigee 지원팀과 공유하세요.
퍼블릭 클라우드 사용자인 경우 다음 정보를 제공하세요.
- 조직 이름
- 환경 이름
- API 프록시 이름
- 504 오류 응답을 재현하는 데 사용된 전체
curl명령어 - 504 게이트웨이 시간 초과 오류 응답을 수신하는 API 요청이 있는 추적 파일
프라이빗 클라우드 사용자인 경우 다음 정보를 제공하세요.
- 실패한 요청에 대해 발견된 전체 오류 메시지
- 환경 이름
- API 프록시 번들
- 504 Gateway Timeout 오류 응답이 수신되는 API 요청이 있는 추적 파일
- NGINX 액세스 로그
/opt/apigee/var/log/edge-router/nginx/ ORG ~ENV.PORT# _access_log
- 메시지 프로세서 로그
/opt/apigee/var/log/edge-message-processor/logs/system.log