현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보
증상
클라이언트 애플리케이션은 API 호출에 대한 응답으로 Gateway Timeout 메시지와 함께 HTTP 상태 코드 504를 수신합니다.
이 오류 응답은 클라이언트가 API 호출을 실행하는 동안 Apigee Edge 또는 백엔드 서버에서 적시에 응답을 받지 못했음을 나타냅니다.
오류 메시지
클라이언트 애플리케이션은 다음 응답 코드를 가져옵니다.
HTTP/1.1 504 Gateway Time-out
cURL 또는 웹브라우저를 사용하여 이러한 프록시를 호출하면 다음과 같은 오류가 발생할 수 있습니다.
<!DOCTYPE html>
<html>
<head>
<title>Error</title>
<style>
body {
width: 35em;
margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif;
}
</style>
</head>
<body>
<h1>An error occurred.</h1>
<p>Sorry, the page you are looking for is currently unavailable.<br/>
Please try again later.</p>
</body>
</html>
시간 초과의 원인은 무엇인가요?
에지 플랫폼을 통한 API 요청의 일반적인 경로는 다음 그림과 같이 클라이언트 > 라우터 > 메시지 프로세서 > 백엔드 서버입니다.
클라이언트, 라우터, 메시지 프로세서, 백엔드 서버를 포함한 Apigee Edge 런타임 흐름의 모든 구성요소는 API 요청을 완료하는 데 너무 오래 걸리지 않도록 적절한 기본 제한 시간 값으로 설정됩니다. 흐름의 구성요소가 제한 시간 구성에 지정된 시간 내에 업스트림 구성요소에서 응답을 받지 못하면 해당 구성요소가 시간 제한을 초과하고 일반적으로 504 Gateway Timeout 오류를 반환합니다.
이 플레이북에서는 라우터 시간 초과 시 발생하는 504 오류를 해결하는 방법을 설명합니다.
라우터 시간 초과
Apigee Edge의 라우터에 구성된 기본 제한 시간은 57초입니다. Edge에서 API 요청이 수신된 시점부터 응답이 다시 전송될 때까지 API 프록시를 실행할 수 있는 최대 시간으로, 백엔드 응답 및 실행된 모든 정책이 포함됩니다. 기본 제한 시간은 라우터의 I/O 시간 제한 구성에 설명된 대로 라우터/가상 호스트에서 재정의할 수 있습니다.
가능한 원인
Edge에서 라우터 시간 초과로 인해 발생하는 504 Gateway Timeout 오류의 일반적인 원인은 다음과 같습니다.
| 원인 | 설명 | 다음에 관한 문제 해결 안내 |
|---|---|---|
| 라우터의 시간 제한 구성이 잘못됨 | 이 문제는 라우터가 잘못된 I/O 시간 제한 시간으로 구성된 경우에 발생합니다. | Edge 퍼블릭 및 프라이빗 클라우드 사용자 |
일반적인 진단 단계
다음 도구/기술 중 하나를 사용하여 이 오류를 진단하세요.
- API 모니터링
- NGINX 액세스 로그
API 모니터링
API 모니터링을 사용하여 오류를 진단하려면 다음 안내를 따르세요.
- 분석 > API 모니터링 > 조사 페이지로 이동합니다.
- 오류
5xx개를 필터링하고 기간을 선택합니다. - 시간을 기준으로 상태 코드를 표시합니다.
-
504오류를 표시하는 특정 셀을 클릭하여 자세한 내용을 확인하고 이러한 오류에 대한 로그를 아래와 같이 확인합니다.504 오류를 보여주는 예
- 오른쪽 창에서 로그 보기를 클릭합니다.
트래픽 로그 창에서 일부
504오류에 대한 다음 세부정보를 확인합니다.- 요청: 호출하는 데 사용되는 요청 메서드와 URI를 제공합니다.
- 응답 시간: 요청에 경과된 총 시간을 제공합니다.
위의 예에서
- 요청 이
GET /test-timeout를 가리킵니다. - 응답 시간 :
57.001초 이는 메시지 프로세서가 다시 응답할 수 있게 되기 전에 라우터가 시간 초과되었음을 나타냅니다. 값이 라우터에 설정된 기본 I/O 시간 제한( 57초)에 매우 가깝기 때문입니다.
API Monitoring GET logs API를 사용하여 모든 로그를 가져올 수도 있습니다. 예를 들어
org,env,timeRange,status의 로그를 쿼리하면 클라이언트가 타임아웃된 트랜잭션의 모든 로그를 다운로드할 수 있습니다.API Monitoring은 이러한
504오류의 경우 프록시를-(not set)으로 설정하므로 API (로그 API)를 사용하여 가상 호스트 및 경로의 연결된 프록시를 가져올 수 있습니다.For example :
curl "https://apimonitoring.enterprise.apigee.com/logs/apiproxies?org=ORG&env=ENV&select=https
- 추가
504오류가 있는지 응답 시간을 검토하고 모든504오류에서 응답 시간이 일관적인지 (라우터에 설정된 I/O 시간 제한 값은 57초) 확인합니다.
NGINX 액세스 로그
NGINX 액세스 로그를 사용하여 오류를 진단하려면 다음 안내를 따르세요.
- NGINX 액세스 로그를 확인합니다.
/opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log - 특정 기간 동안
504오류가 있었는지(과거에 문제가 발생한 경우)504와 함께 여전히 실패하는 요청이 있는지 검색합니다. - 일부
504오류의 경우 다음 정보를 참고하세요.- 응답 시간
- 요청 URI
이 예에는 다음 정보가 표시됩니다.
-
요청 시간:
57.001초 이는 라우터가 57.001초 후에 타임아웃되었음을 나타냅니다. - 요청:
GET /test-timeout - Host Alias(호스트 별칭):
myorg-test.apigee.net
-
요청 시간이 라우터/가상 호스트에 구성된 I/O 시간 제한과 동일한지 확인합니다. 그렇다면 메시지 프로세서가 이 시간 내에 응답하지 않기 전에 라우터가 타임아웃되었다는 의미입니다.
위에 표시된 NGINX 액세스 로그 항목 예시에서 요청 시간
57.001초는 라우터에 설정된 기본 I/O 시간 초과와 매우 가깝습니다. 이는 메시지 프로세서가 다시 응답하기 전에 라우터가 타임아웃되었음을 명확히 나타냅니다. - Request 필드의 기본 경로를 사용하여 요청이 이루어진 API 프록시를 확인합니다.
원인: 라우터의 시간 제한 구성이 잘못됨
진단
- 메시지 프로세서가 다시 응답하기 전에 라우터가 타임아웃되었기 때문에
504오류가 발생했는지 확인합니다. API 모니터링의 응답 시간/라우터의 요청 시간 (두 필드 모두 동일한 정보를 나타내지만 서로 다른 이름으로 호출됨)이 라우터/가상 호스트에 구성된 I/O 시간 초과와 동일한지, 그리고 오류 소스, 오류 프록시, 오류 코드 필드가 의 일반 진단 또는 NGINX 액세스 로그를 사용하여-로 설정되어 있는지 확인하면 됩니다. -
라우터 또는 특정 가상 호스트에 구성된 I/O 시간 제한 값이 메시지 프로세서나 특정 API 프록시에 구성된 값보다 낮은지 확인합니다.
이 섹션의 단계를 따르면 됩니다.
가상 호스트의 I/O 제한 시간 확인
Edge UI
Edge UI를 사용하여 가상 호스트 시간 제한을 확인하려면 다음 안내를 따르세요.
- Edge UI에 로그인합니다.
- 관리자 > 가상 호스트로 이동합니다.
- 시간 초과 문제가 발생하는 특정 환경을 선택합니다.
- I/O 제한 시간 값을 확인할 특정 가상 호스트를 선택합니다.
- 속성에서 프록시 읽기 시간 제한 값(초)을 확인합니다.
위의 예에서 프록시 읽기 시간 제한 은
120값으로 구성됩니다. 즉, 이 가상 호스트에 구성된 I/O 제한 시간은 120초입니다.
Management API
다음 관리 API를 사용하여 프록시 읽기 시간 제한을 확인할 수도 있습니다.
-
아래와 같이 Get virtual host API를 실행하여
virtualhost구성을 가져옵니다.퍼블릭 클라우드 사용자
curl -v -X GET https://api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/virtualhosts/VIRTUALHOST_NAME -u USERNAME
Private Cloud 사용자
curl -v -X GET http://MANAGEMENT_SERVER_HOST:PORT#/v1/organizations/ORGANIZATION_NAME/environments/v/virtualhosts/VIRTUALHOST_NAME -u USERNAME
각 항목의 의미는 다음과 같습니다.
ORGANIZATION_NAME은 조직 이름입니다.
ENVIRONMENT_NAME은 환경 이름입니다.
VIRTUALHOST_NAME은 가상 호스트의 이름입니다.
-
proxy_read_timeout속성에 구성된 값을 확인합니다.샘플 가상 호스트 정의
{ "hostAliases": [ "api.myCompany,com", ], "interfaces": [], "listenOptions": [], "name": "secure", "port": "443", "retryOptions": [], "properties": { "property": [ { "name": "proxy_read_timeout", "value": "120" } ] }, "sSLInfo": { "ciphers": [], "clientAuthEnabled": "false", "enabled": "true", "ignoreValidationErrors": false, "keyAlias": "myCompanyKeyAlias", "keyStore": "ref://myCompanyKeystoreref", "protocols": [] }, "useBuiltInFreeTrialCert": false }위의 예에서
proxy_read_timeout은120값으로 구성됩니다. 즉, 이 가상 호스트에 구성된 I/O 제한 시간이 120초입니다.
Router.properties 파일의 I/O 제한 시간 확인
- 라우터 머신에 로그인합니다.
/opt/nginx/conf.d디렉터리에서proxy_read_timeout속성을 검색하여 다음과 같이 새 값으로 설정되어 있는지 확인합니다.grep -ri "proxy_read_timeout" /opt/nginx/conf.d
-
특정 가상 호스트 구성 파일에서
proxy_read_timeout속성에 설정된 값을 확인합니다.grep 명령어의 샘플 결과
/opt/nginx/conf.d/0-default.conf:proxy_read_timeout 57; /opt/nginx/conf.d/0-edge-health.conf:proxy_read_timeout 1s;
위의 출력 예에서
proxy_read_timeout속성이 기본 가상 호스트의 구성 파일인0-default.conf의 새 값57로 설정된 것을 볼 수 있습니다. 이는 기본 가상 호스트의 라우터에서 I/O 시간 제한이 57초로 구성되었음을 나타냅니다. 가상 호스트가 여러 개인 경우 각 호스트의 정보가 표시됩니다.504오류로 실패한 API 호출을 실행하는 데 사용한 특정 가상 호스트의proxy_read_timeout값을 가져옵니다.
API 프록시에서 I/O 제한 시간 확인
다음에서 I/O 제한 시간을 볼 수 있습니다.
- API 프록시의 대상 엔드포인트
- API 프록시의 Service콜아웃 정책
API 프록시의 대상 엔드포인트에서 I/O 제한 시간 보기
- Edge UI에서 I/O 제한 시간 값을 확인할 특정 API 프록시를 선택합니다.
- 확인할 특정 대상 엔드포인트를 선택합니다.
TargetEndpoint구성의<HTTPTargetConnection>요소 아래에서 적절한 값이 있는io.timeout.millis속성을 참고하세요.예를 들어 다음 코드의 I/O 제한 시간은 120초로 설정됩니다.
<Properties> <Property name="io.timeout.millis">120000</Property> </Properties>
API 프록시의 Service콜아웃 정책에서 I/O 제한 시간 보기
- Edge UI에서 ServiceCall 정책의 새 I/O 제한 시간 값을 볼 특정 API 프록시를 선택합니다.
- 확인하려는 특정 Service콜 정책을 선택하세요.
-
<Timeout>요소를<ServiceCallout>구성에서 적절한 값과 함께 참고하세요.예를 들어 다음 코드의 I/O 제한 시간은 120초입니다.
<Timeout>120000</Timeout>
메시지 프로세서의 I/O 제한 시간 확인
- 메시지 프로세서 머신에 로그인합니다.
-
다음 명령어를 사용하여
/opt/apigee/edge-message-processor/conf디렉터리에서HTTPTransport.io.timeout.millis속성을 검색합니다.grep -ri "HTTPTransport.io.timeout.millis" /opt/apigee/edge-message-processor/conf
샘플 출력
/opt/apigee/edge-message-processor/conf/http.properties:HTTPTransport.io.timeout.millis=55000
- 위의 출력 예에서
HTTPTransport.io.timeout.millis속성이http.properties의55000값으로 설정되어 있음을 알 수 있습니다. 이는 메시지 프로세서에서 I/O 제한 시간이 55초로 성공적으로 구성되었음을 나타냅니다.
라우터 및 메시지 프로세서에 구성된 제한 시간을 확인했으면 라우터/가상 호스트가 메시지 프로세서/API 프록시보다 낮은 제한 시간 값으로 구성되었는지 확인합니다.
아래 표에 표시된 대로 모든 레이어에 설정된 값을 기록해 둡니다.
| 라우터 시간 초과 (초) | 가상 호스트의 제한 시간 (초) | 메시지 프로세서의 제한 시간 (초) | API 프록시 제한 시간 (초) |
|---|---|---|---|
| 57 | - | 55 | 120 |
이 예시에서 보면,
- 라우터에 기본값 57초가 구성되어 있습니다.
- 특정 가상 호스트에 제한 시간 값이 설정되지 않았습니다. 즉, 라우터 자체에 구성된 기본값인 57초가 사용됩니다.
- 메시지 프로세서에서 기본값 55초가 구성됩니다.
- 그러나 특정 API 프록시에서는 값이 120초로 구성되어 있습니다.
더 높은 제한 시간 값은 API 프록시에서만 구성되지만 라우터는 여전히 57초로 구성됩니다. 따라서 메시지 프로세서/백엔드가 계속 요청을 처리하는 동안 라우터는 57초 후에 타임아웃됩니다. 이렇게 하면 라우터가 클라이언트 애플리케이션에 504 Gateway Timeout 오류와 함께 응답합니다.
해상도
이 문제를 해결하려면 다음 단계에 따라 라우터 및 메시지 프로세서에 적절한 I/O 시간 제한을 구성하세요.
- Apigee Edge를 통한 API 요청 흐름과 관련된 여러 구성요소에 설정해야 하는 제한 시간 값을 알아보려면 I/O 제한 시간 구성 권장사항을 참조하세요.
- 위의 예시에서는 백엔드 서버에 더 긴 시간이 필요하기 때문에 시간 제한 값을 더 높게 설정해야 한다는 확신이 들어서 메시지 프로세서의 시간 제한 값을 120초로 늘린 다음 더 높은 시간 제한 값을 설정합니다(예: 라우터의
123 seconds). 새로운 제한 시간 값으로 인해 모든 API 프록시에 영향을 주지 않으려면 특정 API 프록시에서 사용되는 특정 가상 호스트에서만123 seconds값을 설정합니다. - 라우터의 I/O 시간 제한 구성의 안내에 따라 가상 호스트의 제한 시간을 설정합니다.