Apigee Edge 문서를 보고 있습니다.
Apigee X 문서로 이동하세요. info
증상
클라이언트 애플리케이션은 API 호출에 대한 응답으로 Gateway Timeout 메시지와 함께 504 HTTP 상태 코드를 수신합니다.
이 오류 응답은 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>
제한 시간이 초과되는 원인은 무엇인가요?
Edge 플랫폼을 통한 API 요청의 일반적인 경로는 다음 그림과 같이 클라이언트 > 라우터 > 메시지 프로세서 > 백엔드 서버입니다.
클라이언트, 라우터, 메시지 프로세서, 백엔드 서버를 비롯한 Apigee Edge 런타임 흐름의 모든 구성요소는 API 요청이 완료되는 데 너무 오래 걸리지 않도록 적절한 기본 제한 시간 값으로 설정됩니다. 흐름의 구성요소 중 하나가 제한 시간 구성에 지정된 기간 내에 업스트림 구성요소의 응답을 받지 못하면 해당 구성요소의 제한 시간이 초과되고 일반적으로 504 Gateway Timeout 오류가 반환됩니다.
이 플레이북에서는 라우터가 시간 초과될 때 발생하는 504 오류를 해결하는 방법을 설명합니다.
라우터에서 시간 초과
Apigee Edge의 라우터에 구성된 기본 제한 시간은 57초입니다. 이는 API 프록시가 Edge에서 API 요청을 수신한 시점부터 백엔드 응답과 실행되는 모든 정책을 포함하여 응답이 다시 전송될 때까지 실행될 수 있는 최대 시간입니다. 기본 제한 시간은 라우터에서 I/O 제한 시간 구성에 설명된 대로 라우터/가상 호스트에서 재정의할 수 있습니다.
가능한 원인
Edge에서 라우터 시간 초과로 인해 발생하는 504 Gateway Timeout 오류의 일반적인 원인은 다음과 같습니다.
| 원인 | 설명 | 다음에 관한 문제 해결 안내 |
|---|---|---|
| 라우터의 잘못된 제한 시간 구성 | 이 문제는 라우터가 잘못된 I/O 제한 시간으로 구성된 경우에 발생합니다. | Edge Public 및 Private Cloud 사용자 |
일반적인 진단 단계
다음 도구/기법 중 하나를 사용하여 이 오류를 진단하세요.
- API 모니터링
- NGINX 액세스 로그
API 모니터링
API 모니터링을 사용하여 오류를 진단하려면 다음 단계를 따르세요.
- 분석 > API 모니터링 > 조사 페이지로 이동합니다.
5xx오류를 필터링하고 기간을 선택합니다.- 시간에 대한 상태 코드를 그래프로 표시합니다.
-
504오류가 표시된 특정 셀을 클릭하여 자세한 내용을 확인하고 아래와 같이 이러한 오류에 관한 로그를 확인합니다.504 오류를 보여주는 예
- 오른쪽 창에서 로그 보기를 클릭합니다.
트래픽 로그 창에서 일부
504오류에 대해 다음 세부정보를 확인합니다.- 요청: 호출을 만드는 데 사용되는 요청 메서드와 URI를 제공합니다.
- 응답 시간: 요청에 걸린 총 시간을 제공합니다.
위의 예시에서는
- 요청 이
GET /test-timeout을 가리킵니다. - 응답 시간 은
57.001초입니다. 이는 메시지 프로세서가 응답하기 전에 라우터의 시간이 초과되었음을 나타냅니다. 값이 라우터에 설정된 기본 I/O 제한 시간인 57초에 매우 가깝기 때문입니다.
API 모니터링 GET logs API를 사용하여 모든 로그를 가져올 수도 있습니다. 예를 들어
org,env,timeRange,status의 로그를 쿼리하면 클라이언트가 타임아웃된 트랜잭션의 모든 로그를 다운로드할 수 있습니다.API 모니터링은 이러한
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 - 호스트 별칭:
myorg-test.apigee.net
-
요청 시간이 라우터/가상 호스트에 구성된 I/O 제한 시간과 동일한지 확인합니다. '예'인 경우 메시지 프로세서가 이 기간 내에 응답하지 않아 라우터의 제한 시간이 초과된 것입니다.
위의 NGINX 액세스 로그 항목 예시에서
57.001초의 요청 시간은 라우터에 설정된 기본 I/O 제한 시간과 매우 가깝습니다. 이는 메시지 프로세서가 응답하기 전에 라우터가 시간 초과되었음을 명확하게 나타냅니다. - 요청 필드의 기본 경로를 사용하여 요청이 이루어진 API 프록시를 확인합니다.
원인: 라우터의 잘못된 시간 제한 구성
진단
- 메시지 프로세서가 응답하기 전에 라우터의 시간이 초과되어
504오류가 발생하는지 확인합니다. API 모니터링의 응답 시간/라우터의 요청 시간 (두 필드는 동일한 정보를 나타내지만 이름이 다름)이 라우터/가상 호스트에 구성된 I/O 제한 시간과 동일한지, 결함 소스, 결함 프록시, 결함 코드 필드가-로 설정되어 있는지 확인하면 됩니다. 이는 일반적인 진단 단계에 설명된 대로 API 모니터링 또는 NGINX 액세스 로그를 사용하여 확인할 수 있습니다. -
라우터 또는 특정 가상 호스트에 구성된 I/O 제한 시간 값이 메시지 프로세서 또는 특정 API 프록시에 구성된 값보다 낮은지 확인합니다.
이 섹션의 단계에 따라 이 작업을 수행할 수 있습니다.
가상 호스트에서 I/O 제한 시간 확인
Edge UI
Edge UI를 사용하여 가상 호스트 제한 시간을 확인하려면 다음 단계를 따르세요.
- Edge UI에 로그인합니다.
- 관리 > 가상 호스트로 이동합니다.
- 시간 초과 문제가 발생하는 특정 환경을 선택합니다.
- I/O 제한 시간 값을 확인할 특정 가상 호스트를 선택합니다.
- 속성에서 프록시 읽기 시간 제한 값을 초 단위로 확인합니다.
위의 예에서는 프록시 읽기 시간 제한 이
120값으로 구성됩니다. 즉, 이 가상 호스트에 구성된 I/O 제한 시간은 120초입니다.
Management API
다음 관리 API를 사용하여 프록시 읽기 제한 시간을 확인할 수도 있습니다.
-
가상 호스트 가져오기 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 프록시의 ServiceCallout 정책
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 프록시의 ServiceCallout 정책에서 I/O 제한 시간 보기
- Edge UI에서 ServiceCallout 정책의 새 I/O 제한 시간 값을 보려는 특정 API 프록시를 선택합니다.
- 확인하려는 특정 ServiceCallout 정책을 선택합니다.
-
<ServiceCallout>구성 아래에 적절한 값이 있는<Timeout>요소를 참고하세요.예를 들어 다음 코드의 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 제한 시간을 구성하여 이 문제를 해결하려면 다음 단계를 따르세요.
- I/O 제한 시간 구성 권장사항을 참고하여 Apigee Edge를 통한 API 요청 흐름에 관련된 다양한 구성요소에 설정해야 하는 제한 시간 값을 알아보세요.
- 위 예에서 백엔드 서버에 더 긴 시간이 필요하므로 더 높은 제한 시간 값을 설정해야 한다고 확인하고 메시지 프로세서의 제한 시간 값을 120초로 늘린 경우 라우터에서 더 높은 제한 시간 값(예:
123 seconds)을 설정합니다. 새 제한 시간 값으로 인해 모든 API 프록시가 영향을 받지 않도록 하려면 특정 API 프록시에서 사용되는 특정 가상 호스트에만123 seconds값을 설정하세요. - 라우터에서 I/O 제한 시간 구성의 안내에 따라 가상 호스트에서 제한 시간을 설정합니다.