500 내부 서버 오류

Apigee Edge 문서입니다.
Go to the Apigee X documentation. info

동영상

500 내부 서버 오류 해결에 대해 자세히 알아보려면 다음 동영상을 시청하세요.

동영상 설명
소개 500 내부 서버 오류 및 가능한 원인을 소개합니다. 또한 오류를 해결하고 해결하는 단계와 함께 실시간 500 내부 서버 오류를 보여줍니다.
서비스 콜아웃 및 변수 추출 오류 처리 서비스 콜아웃 및 변수 추출 정책으로 인해 발생하는 두 가지 500 내부 서버 오류를 보여주고 이러한 오류를 해결하고 해결하는 방법을 보여줍니다.
자바스크립트 정책 오류 처리 자바스크립트 정책으로 인해 발생하는 500 내부 서버 오류와 이 오류를 해결하고 해결하는 단계 를 보여줍니다.
백엔드 서버의 실패 처리 백엔드 서버의 실패로 인해 발생하는 500 내부 서버 오류의 예를 보여주고 오류를 해결하는 단계를 보여줍니다.

증상

클라이언트 애플리케이션은 API 호출에 대한 응답으로 메시지 "내부 서버 오류"와 함께 HTTP 상태 코드 500을 가져옵니다. 500 내부 서버 오류는 Edge 내에서 정책을 실행하는 동안 발생하는 오류 또는 대상/백엔드 서버의 오류 로 인해 발생할 수 있습니다.

HTTP 상태 코드 500은 일반 오류 응답입니다. 이는 서버에서 요청을 수행할 수 없는 예기치 않은 조건을 발생했음을 의미합니다. 이 오류는 일반적으로 다른 오류 코드가 적합하지 않은 경우 서버에서 반환됩니다.

오류 메시지

다음 오류 메시지가 표시될 수 있습니다.

HTTP/1.1 500 Internal Server Error

경우에 따라 세부정보가 포함된 다른 오류 메시지가 표시될 수 있습니다. 다음은 샘플 오류 메시지입니다.

{
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.ExecutionFailed"
      },
      "faultstring":"Execution of ServiceCallout callWCSAuthServiceCallout failed. Reason: ResponseCode 400 is treated as error"
   }
}

가능한 원인

500 내부 서버 오류는 여러 가지 원인으로 인해 발생할 수 있습니다. Edge에서 원인은 오류가 발생한 위치에 따라 두 가지 주요 카테고리로 분류할 수 있습니다.

원인 세부정보 자세한 문제 해결 단계는 다음을 위해 제공됩니다.
Edge 정책의 실행 오류 API 프록시 내의 정책 이 어떤 이유로든 실패할 수 있습니다. Edge Private 및 Public Cloud 사용자
백엔드 서버의 오류 백엔드 서버가 어떤 이유로든 실패할 수 있습니다. Edge Private 및 Public Cloud 사용자

Edge 정책의 실행 오류

API 프록시 내의 정책이 어떤 이유로든 실패할 수 있습니다. 이 섹션에서는 정책을 실행하는 동안 500 내부 서버 오류가 발생하는 경우 문제를 해결하는 방법을 설명합니다.

진단

Private 및 Public Cloud 사용자를 위한 진단 단계

오류에 대한 Trace UI 세션이 있는 경우 다음을 수행합니다.

  1. 정책 실행으로 인해 오류가 발생했는지 확인합니다. 자세한 내용은 문제의 원인 확인을 참고하세요.
  2. 정책 실행 중에 오류가 발생한 경우 계속합니다. 백엔드 서버로 인해 오류가 발생한 경우 백엔드 서버의 오류로 이동합니다.
  3. Trace에서 500 내부 서버 오류로 실패하는 API 요청을 선택합니다.
  4. 요청을 검토하고 실패한 특정 정책 또는 Trace에서 실패한 정책 바로 다음에 나오는 "오류"라는 흐름을 선택합니다.
  5. 속성 섹션의 "오류" 필드 또는 오류 콘텐츠를 확인하여 오류에 대한 자세한 내용을 확인합니다.
  6. 오류에 대해 수집한 세부정보를 사용하여 원인을 파악해 보세요.

Private Cloud 사용자 전용 진단 단계

Trace UI 세션이 없는 경우 다음을 수행합니다.

  1. 정책을 실행하는 동안 오류가 발생했는지 확인합니다. 자세한 내용은 문제의 원인 확인을 참고하세요.
  2. 정책 실행으로 인해 오류가 발생한 경우 계속합니다. 정책 실행 중에 오류가 발생한 경우 계속합니다. 백엔드 서버로 인해 오류가 발생한 경우 백엔드 서버의 오류로 이동합니다.
  3. 문제의 원인 확인에 설명된 대로 NGINX 액세스 로그를 사용하여 API 프록시에서 실패한 정책과 고유한 요청 메시지 ID를 확인합니다.
  4. 메시지 프로세서 로그 (/opt/apigee/var/log/edge-message-processor/logs/system.log)를 확인하고 고유한 요청 메시지 ID를 검색합니다.
  5. 고유한 요청 메시지 ID를 찾은 경우 실패 원인에 대한 자세한 정보를 확인할 수 있는지 확인합니다.

해상도

정책의 문제 원인을 파악한 경우 정책을 수정하고 프록시를 다시 배포하여 문제를 해결해 보세요.

다음 예에서는 다양한 문제의 원인과 해결 방법을 확인하는 방법을 보여줍니다.

500 내부 서버 오류 문제 해결에 추가 지원이 필요하거나 Edge 내에 문제가 있다고 생각되면 Apigee 지원팀에 문의하세요.

예 1: 백엔드 서버의 오류로 인한 서비스 콜아웃 정책 실패

서비스 콜아웃 정책 내에서 백엔드 서버 호출이 4XX 또는 5XX와 같은 오류로 실패하면 500 내부 서버 오류로 처리됩니다.

  1. 다음은 서비스 콜아웃 정책 내에서 백엔드 서비스가 404 오류로 실패하는 예입니다. 다음 오류 메시지가 최종 사용자에게 전송됩니다. 
    {
"fault":
     { "detail":
           { "errorcode":"steps.servicecallout.ExecutionFailed"
           },"faultstring":"Execution of ServiceCallout service_callout_v3_store_by_lat_lon
 failed. Reason: ResponseCode 404 is treated as error"
          }
     }
}
  2. 다음 Trace UI 세션은 서비스 콜아웃 정책의 오류로 인해 발생하는 500 상태 코드를 보여줍니다.

  3. 이 예에서 "오류" 속성은 서비스 콜아웃 정책 실패의 원인을 "ResponseCode 404가 오류로 처리됨"으로 나열합니다. 이 오류는 서비스 콜아웃 정책의 백엔드 서버 URL을 통해 액세스되는 리소스를 사용할 수 없는 경우 발생할 수 있습니다.
  4. 백엔드 서버에서 리소스의 가용성을 확인합니다. 일시적 또는 영구적으로 사용할 수 없거나 다른 위치로 이동했을 수 있습니다.

예 1 해결 방법

  1. 백엔드 서버에서 리소스의 가용성을 확인합니다. 일시적 또는 영구적으로 사용할 수 없거나 다른 위치로 이동했을 수 있습니다.
  2. 서비스 콜아웃 정책에서 백엔드 서버 URL을 수정하여 유효하고 기존 리소스를 가리키도록 합니다.
  3. 리소스가 일시적으로만 사용할 수 없는 경우 리소스를 사용할 수 있게 되면 리소스를 사용할 수 있게 되면 API 요청을 해 보세요.

예 2: 변수 추출 정책 실패

이제 변수 추출 정책의 오류로 인해 500 내부 서버 오류가 발생하는 또 다른 예를 살펴보고 문제를 해결하고 해결하는 방법을 알아보겠습니다.

  1. UI 세션의 다음 Trace는 변수 추출 정책의 오류로 인해 발생하는 500 상태 코드를 보여줍니다.

  2. 실패한 변수 추출 정책을 선택하고 아래로 스크롤하여 "오류 콘텐츠" 섹션에서 자세한 내용을 확인합니다:

  3. 오류 콘텐츠는 변수 추출 정책에서 "serviceCallout.oamCookieValidationResponse" 변수를 사용할 수 없음을 나타냅니다. 변수 이름에서 알 수 있듯이 이전 서비스 콜아웃 정책의 응답을 보유해야 합니다.
  4. Trace에서 서비스 콜아웃 정책을 선택하면 "serviceCallout.oamCookieValidationResponse" 변수가 설정되지 않은 것을 확인할 수 있습니다. 이는 백엔드 서비스 호출이 실패하여 빈 응답 변수가 발생했음을 나타냅니다.
  5. 서비스 콜아웃 정책이 실패했지만 아래와 같이 서비스 콜아웃 정책의 'continueOnError' 플래그가 true로 설정되어 있으므로 서비스 콜아웃 정책 이후의 정책 실행이 계속됩니다:

    <ServiceCallout async="false" continueOnError="true" enabled="true" name="Callout.OamCookieValidation">
  <DisplayName>Callout.OamCookieValidation</DisplayName>
  <Properties />
  <Request clearPayload="true" variable="serviceCallout.oamCookieValidationRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  </Request>
  <Response>serviceCallout.oamCookieValidationResponse</Response>
  <HTTPTargetConnection>
    <Properties />
    <URL>http://{Url}</URL>
  </HTTPTargetConnection>
</ServiceCallout>
  6. 다음과 같이 Trace에서 이 특정 API 요청의 고유한 메시지 ID "X-Apigee.Message-ID" 를 기록합니다.
    1. 요청에서 '애널리틱스 데이터 기록됨' 단계를 선택합니다.
    2. 아래로 스크롤하여 X-Apigee.Message-ID 값을 기록합니다.

  7. 메시지 프로세서 로그 (/opt/apigee/var/log/edge-message-processor/system.log)를 보고 6단계에서 기록한 고유한 메시지 ID를 검색합니다. 특정 API 요청에 대해 다음 오류 메시지가 관찰되었습니다. 
    2017-05-05 07:48:18,653 org:myorg env:prod api:myapi rev:834 messageid:rrt-04984fed9e5ad3551-c-wo-32168-77563  NIOThread@5 ERROR HTTP.CLIENT - HTTPClient$Context.onTimeout() : ClientChannel[C:]@149081 useCount=1 bytesRead=0 bytesWritten=0 age=3002ms lastIO=3002ms .onConnectTimeout connectAddress=mybackend.domain.com/XX.XX.XX.XX:443 resolvedAddress=mybackend.domain.com/XX.XX.XX.XX

    위의 오류는 백엔드 서버에 연결하는 동안 연결 시간 초과 오류로 인해 서비스 콜아웃 정책이 실패했음을 나타냅니다.

  8. 연결 시간 초과 오류의 원인을 파악하기 위해 메시지 프로세서에서 백엔드 서버로 telnet 명령어를 실행했습니다. 텔넷 명령어는 아래와 같이 '연결 시간 초과' 오류를 발생시켰습니다. 
    telnet mybackend.domain.com 443
Trying XX.XX.XX.XX...
telnet: connect to address XX.XX.XX.XX: Connection timed out

    일반적으로 이 오류는 다음과 같은 상황에서 관찰됩니다.

    • 백엔드 서버가 Edge 메시지 프로세서의 트래픽을 허용하도록 구성되지 않은 경우
    • 백엔드 서버가 특정 포트에서 리슨하지 않는 경우

    위의 예에서 변수 추출 정책이 실패했지만 실제 원인은 Edge가 서비스 콜아웃 정책에서 백엔드 서버에 연결할 수 없다는 것입니다. 이 실패의 원인은 백엔드 서버가 Edge 메시지 프로세서의 트래픽을 허용하도록 구성되지 않았기 때문입니다.

    자체 변수 추출 정책은 다르게 동작하며 다른 이유로 실패할 수 있습니다. **오류** 속성의 메시지를 확인하여 변수 추출 정책의 실패 원인에 따라 문제를 적절하게 해결할 수 있습니다.

예 2 해결 방법

  1. 변수 추출 정책의 오류 또는 실패 원인을 적절하게 해결합니다.
  2. 위의 예에서 해결 방법은 Edge 메시지 프로세서의 트래픽을 백엔드 서버로 허용하도록 네트워크 구성을 수정하는 것이었습니다. 이는 특정 백엔드 서버에서 메시지 프로세서의 IP 주소를 허용 목록에 추가하여 수행되었습니다. 예를 들어, Linux에서는 iptables 를 사용하여 백엔드 서버에서 메시지 프로세서의 IP 주소의 트래픽을 허용할 수 있습니다.

예 3: JavaCallout 정책 실패

이제 Java 콜아웃 정책의 오류로 인해 500 내부 서버 오류가 발생하는 또 다른 예를 살펴보고 문제를 해결하고 해결하는 방법을 알아보겠습니다.

  1. 다음 UI Trace는 Java 콜아웃 정책의 오류로 인해 발생하는 500 상태 코드를 보여줍니다.

  2. 실패한 Java 콜아웃 정책 다음에 "오류"라는 흐름을 선택하여 아래 그림과 같이 오류 세부정보를 확인합니다.

  3. 이 예에서 속성 섹션의 "오류" 속성은 JavaCallout 정책 내에서 Oracle 데이터베이스에 연결하는 동안 만료된 비밀번호가 사용되어 실패가 발생했음을 보여줍니다. 자체 Java 콜아웃은 다르게 동작하며 다른 메시지를 오류 속성에 채웁니다.
  4. JavaCallout 정책 코드를 확인하고 사용해야 하는 올바른 구성을 확인합니다.

예 3 해결 방법

런타임 예외를 방지하려면 Java 콜아웃 코드 또는 구성을 적절하게 수정합니다. 위의 Java 콜아웃 실패 예에서 문제를 해결하려면 Oracle 데이터베이스에 연결할 때 올바른 비밀번호를 사용해야 합니다.

백엔드 서버의 오류

500 내부 서버 오류는 백엔드 서버에서 발생할 수도 있습니다. 이 섹션 에서는 백엔드 서버에서 오류가 발생하는 경우 문제를 해결하는 방법을 설명합니다.

진단

모든 사용자를 위한 진단 단계

다른 백엔드 오류의 원인은 매우 다양할 수 있습니다. 각 상황을 독립적으로 진단해야 합니다.

  1. 백엔드 서버로 인해 오류가 발생했는지 확인합니다. 자세한 내용은 문제의 원인 확인을 참고하세요.
  2. 백엔드 서버로 인해 오류가 발생한 경우 계속합니다. 정책 실행 중에 오류가 발생한 경우 Edge 정책의 실행 오류로 이동합니다.
  3. 실패한 API의 Trace 세션에 액세스할 수 있는지 또는 백엔드가 Node.js 서버인지에 따라 아래 단계를 따르세요.

실패한 API 호출에 대한 Trace 세션이 없는 경우:

  1. 실패한 요청에 UI Trace를 사용할 수 없는 경우 백엔드 서버 로그를 확인하여 오류에 대한 세부정보를 확인합니다.
  2. 가능한 경우 백엔드 서버에서 디버그 모드를 사용 설정하여 오류 및 원인에 대한 자세한 내용을 확인합니다.

실패한 API 호출에 대한 Trace 세션이 있는 경우:

Trace 세션이 있는 경우 다음 단계에 따라 문제를 진단할 수 있습니다.

  1. Trace 도구에서 500 내부 서버 오류로 실패한 API 요청을 선택합니다.
  2. 아래 그림과 같이 실패한 API 요청에서 "대상 서버에서 수신된 응답" 단계를 선택합니다.

  3. "응답 콘텐츠" 섹션을 확인하여 오류에 대한 세부정보를 확인합니다.

  4. 이 예에서 SOAP 봉투인 응답 콘텐츠는 오류 문자열을 "인증되지 않음" 메시지로 보여줍니다. 이 문제의 가장 가능성이 높은 원인은 사용자가 백엔드 서버에 적절한 사용자 인증 정보 (사용자 이름/비밀번호, 액세스 토큰 등)를 전달하지 않는 것입니다. 이 문제는 백엔드 서버에 올바른 사용자 인증 정보를 전달하여 해결할 수 있습니다.

백엔드가 Node.js 서버인 경우:

  1. 백엔드가 Node.js 백엔드 서버인 경우 Edge UI에서 특정 API 프록시에 대한 Node.js 로그를 확인합니다 (Public 및 Private Cloud 사용자 모두 Node.js 로그를 확인할 수 있음). Edge Private Cloud 사용자인 경우 메시지 프로세서 로그(/opt/apigee/var/log/edge-message-processor/logs/system.log)에서 오류에 대한 자세한 내용을 확인할 수도 있습니다.

    Edge UI의 NodeJS 로그 옵션 - API 프록시의 개요 탭

해상도

  1. 오류의 원인을 파악한 후 백엔드 서버에서 문제를 해결합니다.
  2. Node.js 백엔드 서버인 경우:
    1. 오류가 커스텀 코드에서 발생했는지 확인하고 가능한 경우 문제를 해결합니다.
    2. 오류가 커스텀 코드에서 발생하지 않거나 지원이 필요한 경우 Apigee 지원팀에 문의하세요.

500 내부 서버 오류 문제 해결에 추가 지원이 필요하거나 Edge 내에 문제가 있다고 생각되면 Apigee 지원팀에 문의하세요.

문제의 원인 확인

다음 절차 중 하나를 사용하여 API 프록시 내에서 정책을 실행하는 동안 또는 백엔드 서버에서 500 내부 서버 오류가 발생했는지 확인합니다.

UI에서 Trace 사용

참고: 이 섹션의 단계는 Public 및 Private Cloud 사용자 모두 수행할 수 있습니다.

  1. 문제가 계속 발생하면 영향을 받는 API의 UI에서 Trace를 사용 설정합니다.
  2. Trace를 캡처한 후 응답 코드가 500으로 표시되는 API 요청을 선택합니다.
  3. 실패한 API 요청의 모든 단계를 탐색하고 500 내부 서버 오류를 반환하는 단계를 확인합니다.
    1. 정책을 실행하는 동안 오류가 발생하면 Edge 정책의 실행 오류로 진행합니다.
    2. 백엔드 서버가 500 내부 서버로 응답한 경우 백엔드 서버의 오류로 진행합니다.

API 모니터링 사용

참고: 이 섹션의 단계는 Public Cloud 사용자만 수행할 수 있습니다.

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

API 모니터링을 사용하여 API의 5xx 문제를 해결하는 방법을 보여주는 샘플 시나리오를 단계별로 설명합니다. 예를 들어 500 상태 코드 또는 steps.servicecallout.ExecutionFailed 오류 수가 특정 기준을 초과할 때 알림을 받도록 알림을 설정할 수 있습니다.

NGINX 액세스 로그 사용

참고: 이 섹션의 단계는 Edge Private Cloud 사용자 만 해당합니다.

NGINX 액세스 로그를 참조하여 API 프록시 내에서 정책을 실행하는 동안 또는 백엔드 서버에서 500 상태 코드가 발생했는지 확인할 수도 있습니다. 이는 문제가 과거에 발생했거나 문제가 간헐적이고 UI에서 Trace를 캡처할 수 없는 경우 특히 유용합니다. 다음 단계에 따라 NGINX 액세스 로그에서 이 정보를 확인합니다.

  1. NGINX 액세스 로그 (/opt/apigee/var/log/edge-router/nginx/ <org>~ <env>.<port#>_access_log )를 확인합니다.
  2. 특정 기간에 특정 API 프록시에 500 오류가 있는지 검색합니다.
  3. 500 오류가 있는 경우 아래와 같이 오류가 정책 오류인지 대상 서버 오류인지 확인합니다.

    정책 오류를 보여주는 샘플 항목

    대상 서버 오류를 보여주는 샘플 항목

  4. 정책 오류인지 대상 서버 오류인지 확인한 후 다음을 수행합니다.
    1. 정책 오류인 경우 Edge 정책의 실행 오류로 진행합니다.
    2. 대상 서버 오류인 경우 백0}백엔드 서버의 오류로 진행합니다.