이 페이지는 Cloud Translation API를 통해 번역되었습니다.

500 내부 서버 오류 - 스트리밍 사용

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

증상

클라이언트 애플리케이션이 API 호출에 대해 내부 서버 오류 메시지가 포함된 HTTP 응답 상태 코드 500을 수신합니다.

오류 메시지

클라이언트 애플리케이션에 아래와 같은 오류 응답이 표시될 수 있습니다.

HTTP/1.1 500 Internal Server Error

그 다음에 다음과 같은 오류 메시지가 표시될 수 있습니다.

{
   "fault":{
      "faultstring":"Expecting } at line 1"
      "detail":{
         "errorcode":"Internal Server Error"
      }
   }
}

OR

{
   "fault":{
      "faultstring":"Expecting ] at line 1"
      "detail":{
         "errorcode":"Internal Server Error"
      }
   }
}

가능한 원인

500 내부 서버 오류는 다양한 원인으로 인해 발생할 수 있습니다. 이 플레이북에서는 스트리밍이 사용 설정될 때 요청/응답 페이로드에 액세스하여 발생하는 500 내부 서버 오류에 초점을 맞춥니다.

원인	설명	문제 해결 단계를 수행할 수 있는 사용자
스트리밍을 사용 설정한 상태에서 페이로드 액세스	스트리밍이 사용 설정되었을 때 요청/응답 페이로드에 액세스했기 때문에 오류가 발생했습니다.	에지 프라이빗 및 퍼블릭 클라우드 사용자

원인: 스트리밍을 사용 설정한 상태에서 페이로드 액세스

진단

절차 #1: Trace 사용

trace 세션을 사용 설정하고 API를 호출하여 문제 - 500 Internal Server Error를 재현합니다.
실패한 요청 중 하나를 선택하고 트레이스를 검사합니다.
trace의 다양한 단계를 살펴보고 실패가 발생한 위치를 찾습니다.
정책이 요청/응답 페이로드를 파싱하는 중에 이 오류가 발생했을 수 있습니다.
다음은 JSONThreatProtection 정책JSONThreatProtection 에서 JSONThreatProtection 오류를 보여주는 샘플 트레이스 스크린샷입니다.

위 스크린샷과 같이 트레이스 출력의 다음 정보를 기록해 둡니다.

실패 정책: JSONThreatProtection

흐름: 프록시 요청

실패한 정책 정의를 살펴보고 파싱되는 페이로드를 확인합니다.

예시 시나리오에서 실패한 JSON-Threat-Protection이라는 JSONThreatProtection 정책을 검토하고 <Source> 요소를 확인합니다.

<JSONThreatProtection async="false" continueOnError="false" enabled="true" name="JSON-Threat-Protection">
   <DisplayName>JSON Threat Protection</DisplayName>
   <ArrayElementCount>20</ArrayElementCount>
   <ContainerDepth>10</ContainerDepth>
   <ObjectEntryCount>15</ObjectEntryCount>
   <ObjectEntryNameLength>50</ObjectEntryNameLength>
   <Source>request</Source>
   <StringValueLength>1000</StringValueLength>
</JSONThreatProtection>

<Source> 요소는 request.를 가리킵니다. 즉, 요청 페이로드를 파싱하는 동안 오류가 발생했음을 의미합니다.

API 요청을 확인하여 파싱되는 페이로드의 유형을 확인합니다.

API 요청에서 요청 페이로드 및 Content-Type 헤더의 내용을 확인할 수 있습니다. 다음 curl 명령어 예에서는 JSON 페이로드가 사용됩니다.

curl -i https://VIRTUAL_HOST_ALIAS/BASEPATH -H "Content-Type: application/json" \
-X POST -d @request-payload.json

또한 실패한 정책을 확인하고 파싱되는 페이로드의 유형을 확인할 수도 있습니다. 위의 예시 시나리오에서는 JSON-Threat-Protection 정책이 실패합니다. 페이로드가 JSON 형식이어야 함을 나타냅니다.

페이로드가 올바른 형식인지 확인합니다. 페이로드가 유효하지 않으면 이 오류가 발생할 수 있습니다.

참고: 페이로드가 큰 경우 온라인 형식 지정 도구를 사용하여 페이로드 형식을 검증할 수 있습니다.
페이로드가 유효하지만 오류 메시지 섹션에 나열된 오류가 계속 발생하는 경우 스트리밍이 사용 설정되어 있을 때 페이로드에 액세스하는 것이 이러한 오류의 원인이 됩니다.

6단계에서 결정된 정책에 의해 파싱되는 페이로드에 따라 적절한 단계에서 Trace 도구의 페이로드 콘텐츠를 검사합니다.

예시 시나리오에서는 요청 페이로드가 파싱되므로 추적의 "Request Received from Client" 단계를 살펴보고 Request Content.

유효한 페이로드를 전송했음에도 위의 스크린샷과 같이 요청 콘텐츠가 비어 있으면 이 문제의 가능한 원인은 요청 스트리밍이 사용 설정되었기 때문일 수 있습니다.

스트리밍이 사용 설정되면 요청 페이로드가 trace에 표시되지 않기 때문입니다.

마찬가지로 오류 발생 시 응답 페이로드가 파싱되는 경우 '응답 대상 서버에서 수신된 응답' 단계에서 응답 콘텐츠를 확인합니다.
그런 다음 실패한 정책이 API 프록시 흐름에서 사용되는 위치에 따라 프록시 및 대상 엔드포인트 정의를 살펴봅니다. 스트리밍이 사용 설정되었는지 확인합니다.

예시 시나리오에서 실패 정책은 위의 5단계에서 결정된 대로 프록시 요청 흐름에서 실행되었습니다. 따라서 프록시 엔드포인트를 검사합니다.
```
<ProxyEndpoint name="default">
...
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <VirtualHost>secure</VirtualHost>
    <Properties>
      <Property name="response.streaming.enabled">true</Property>
      <Property name="request.streaming.enabled">true</Property>
    </Properties>
  </HTTPProxyConnection>
</ProxyEndpoint>
```
위 예시에서와 같이 속성 "request.streaming.enabled"가 true로 설정된 대로 요청 스트리밍이 사용 설정되었습니다.

따라서 스트리밍이 사용 설정되었을 때 요청 페이로드에 액세스하는 API 프록시의 JSONThreatProtection 정책을 사용하는 것이 오류의 원인입니다. 이는 API 프록시에서 버퍼링을 트리거하고 Apigee Edge에서 스트리밍을 사용하는 목적을 무효화하기 때문에 오류가 발생합니다.

이 오류는 작은 페이로드에서는 표시되지 않을 수 있지만 더 큰 페이로드를 사용하면 이러한 오류를 볼 수 있습니다.
아래 단계에 따라 추적의 'AX'(애널리틱스 데이터 기록됨) 단계에서 "X-Apigee-fault-source" 값을 확인하여 500 오류가 정책으로 인해 발생했는지 확인할 수 있습니다.
1. 아래 스크린샷에 나와 있는 것처럼 'AX' (애널리틱스 데이터 기록됨) 단계를 클릭합니다.
2. 단계 세부정보에서 '오류 헤더' 섹션까지 아래로 스크롤하고 아래와 같이 'X-Apigee-fault-code', 'X-Apigee-fault-source', 'X-Apigee-fault-policy'의 값을 확인합니다.
3. 위 그림과 같이 "X-Apigee-fault-source"의 값이 "policy"이면 스트리밍이 사용 설정되었을 때 페이로드에 액세스하는 정책으로 인해 오류가 발생했음을 나타냅니다.

해상도

스트리밍이 사용 설정된 상태에서 페이로드에 액세스하는 것은 안티패턴: 스트리밍이 사용 설정된 경우 요청/응답 페이로드에 액세스에 설명된 안티패턴입니다.

페이로드를 처리하려면 아래 ProxyEndpoint 예시와 같이 "request.streaming.enabled" and "response.streaming.enabled" 속성을 삭제하여 프록시/대상 엔드포인트에서 스트리밍을 중지해야 합니다.
```
<ProxyEndpoint name="default">
...
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
</ProxyEndpoint>
```
또는
API 프록시에 스트리밍을 사용하려면 요청/응답 페이로드에 액세스하는 API 프록시에서 어떠한 정책도 사용하지 마세요.

참고:

이 플레이북에서는 예시 시나리오에서 스트리밍이 사용 설정된 상태로 요청 페이로드를 처리하는 데 JSONThreatProtection 정책을 사용했습니다. 이로 인해 여러 오류로 인해 500 내부 서버 오류가 발생했습니다.
이러한 오류는 스트리밍이 사용 설정된 경우 요청 또는 응답 페이로드를 처리하는 JSONToXML 및 XMLToJSON과 같은 정책에서도 나타날 수 있습니다.
스트리밍이 사용 설정된 경우 페이로드에 액세스해야 하는 프록시에는 이러한 정책을 사용하지 않는 것이 좋습니다.
이는 피해야 할 패턴: 스트리밍이 사용 설정된 경우 요청/응답 페이로드에 액세스에 설명된 안티패턴입니다.

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

프라이빗 클라우드 사용자는 이 절차를 건너뛰세요.

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

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

정책에서 500 오류 응답이 발생할 때 알림을 받으려면 오류 소스를 프록시로 하여 500 상태 코드에 대한 알림을 설정해야 합니다.

진단 정보 수집 필수

위 지침을 따른 후에도 문제가 지속되면 다음 진단 정보를 수집하세요. Apigee 지원팀에 연락하여 공유하세요.

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

조직 이름
환경 이름
API 프록시 이름
요청 페이로드 (있는 경우)와 함께 curl 명령어를 완성하여 500 오류를 재현합니다.
500 내부 서버 오류가 있는 요청이 포함된 추적 파일입니다.
현재 500 오류가 발생하지 않는 경우 이전에 500 오류가 발생했을 때의 시간대 정보를 입력합니다.

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

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