확장 프로그램 디버깅

Apigee Edge 문서입니다.
Go to the Apigee X 문서로 이동합니다. info

Trace 도구와 확장 프로그램 로그라는 두 위치에 표시되는 메시지를 사용하여 확장 프로그램을 디버그할 수 있습니다. 확장 프로그램이 작동하지 않을 때 문제를 식별하려면 두 위치의 정보가 모두 필요한 경우가 있습니다.

• Apigee Edge Trace 도구는 API 프록시 코드를 개발할 때 반복적으로 테스트하고 수정하는 곳입니다. Trace 메시지에는 API 프록시 및 정책 구성을 비롯한 API 프록시 코드의 오류가 포함됩니다.

  Trace 도구에 표시되는 확장 프로그램 관련 오류에는 일반적으로 HTTP 오류 코드와 함께 실패한 확장 프로그램 콜아웃을 나타내는 것 외에는 세부정보가 많이 포함되어 있지 않습니다. 여기에서 유용한 정보를 찾을 수 없는 경우 가장 좋은 방법은 사용 중인 확장 프로그램의 로그를 확인하는 것입니다.

• 확장 프로그램은 런타임에 로그 항목을 생성합니다. (확장 프로그램 로그는 조직 관리자만 사용할 수 있습니다.)

  이러한 로그에는 확장 프로그램이 상호작용하도록 구성된 외부 리소스에서 반환된 항목이 포함됩니다. 예를 들어 확장 프로그램에서 외부 리소스 사용자 인증 정보가 잘못 구성된 경우 오류가 여기에 표시될 가능성이 높습니다.

  로그에는 내부 확장 프로그램 코드의 항목도 포함됩니다. 로그를 살펴볼 때 일부 항목은 수정 중인 오류와 관련이 없다는 점에 유의하세요. 확장 프로그램 관련 로그 항목은 일반적으로 details라는 단어로 시작합니다. 예를 들어 Cloud Pub/Sub 확장 프로그램의 다음 로그 항목과 같습니다.

  details: 'Invalid resource name given (name=projects/example-test-123456/topic/extension-example). Refer to https://cloud.google.com/pubsub/docs/admin#resource_names for more information.'
  

오류 유형 및 원인

확장 프로그램 요청 처리 흐름은 API 프록시의 ExtensionCallout 정책에서 확장 프로그램을 거쳐 외부 리소스로 이동한 후 다시 돌아옵니다. 따라서 이러한 위치 중 하나에서 오류가 발생할 수 있습니다.

표시되는 오류는 다음 카테고리에 속할 수 있습니다.

확장 프로그램 구성 오류

이는 조직 관리자가 환경에 확장 프로그램을 추가할 때 수행하는 구성입니다.

예를 들어 잘못된 Google Cloud 프로젝트 ID로 Cloud Logging 확장 프로그램을 구성하면 Google Cloud Logging에서 확장 프로그램에 오류를 반환합니다. 이러한 오류에 대한 세부정보는 일반적으로 확장 프로그램 로그에 있습니다.

Trace 도구의 증거

프록시 편집기에서 이러한 오류는 일반적으로 4xx- 또는 5xx-수준 오류로 표시됩니다. 하지만 프록시 편집기에는 확장 프로그램에서 오류를 반환했다는 것 외에는 오류의 원인에 대한 세부정보가 표시되지 않습니다.

{
  "fault": {
    "faultstring":"Execution of ConnectorCallout Logging-Extension failed. Reason: Connector returned error statuscode=500",
    "detail": {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

확장 프로그램 로그의 증거

이러한 종류의 오류에 대한 세부정보가 있으면 확장 프로그램의 로그 항목에 표시됩니다. Cloud Pub/Sub 서비스에서 반환된 다음 오류 메시지는 잘못된 프로젝트 ID로 인해 발생합니다.

details: 'Project does not exist: example-test-12345'

ExtensionCallout 정책 구성 오류

이러한 오류는 ExtensionCallout 정책이 정책 구성 구문 오류 또는 잘못된 구성 키 또는 값을 통해 잘못 구성된 경우에 발생합니다. 이러한 오류는 정책이 구성된 방식에 따라 두 가지 형태로 나타납니다.

• 외부 리소스에서 평가한 잘못된 값

  이는 구성 오류가 확장 프로그램에는 유효한 것으로 보이지만 외부 리소스에는 유효하지 않은 경우에 발생할 수 있습니다. 예를 들어 확장 프로그램에서 잘못된 데이터베이스 ID를 Cloud Spanner에 전달하면 Cloud Spanner에서 확장 프로그램 로그에 기록되는 오류를 반환합니다.

  details: 'Database not found: projects/example-test-123456/instances/spanner-extension-example-db/databases/my-business-d'
  

  이 오류는 정책의 <Input> 요소에 잘못된 구성 JSON이 있는 경우에도 발생할 수 있습니다. 일부 확장 프로그램의 경우 JSON의 일부는 확장 프로그램에서 처리되고 일부는 리소스에 전달됩니다. 예를 들어 Cloud Logging 확장 프로그램 구성 JSON에는 콘텐츠가 Cloud Logging에 전달되는 metadata 객체가 포함되어 있습니다. 잘못된 키 이름(예: type 대신 typ)이 있으면 확장 프로그램 로그에 항목으로 표시되는 외부 리소스의 오류가 반환될 수 있습니다.

  details: 'Resource type cannot be empty'
  

• 확장 프로그램에서 평가한 잘못된 값

  이러한 오류에는 <Input> 요소 JSON의 정책 평가 부분에 있는 구문 오류, <Action> 요소의 작업 이름 철자 오류 등이 포함됩니다. 이러한 오류는 일반적으로 Trace 도구에 표시되지만 확장 프로그램 로그에는 표시되지 않습니다.

Trace 도구의 증거

프록시 편집기에서 이러한 오류는 일반적으로 4xx- 또는 5xx-수준 오류로 표시됩니다. 하지만 프록시 편집기에는 확장 프로그램에서 오류를 반환했다는 것 외에는 오류의 원인에 대한 세부정보가 표시되지 않습니다. Cloud Firestore 확장 프로그램에서 작업 이름을 잘못 입력하면 Trace 도구에 다음 오류가 표시됩니다.

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404","detail":
    {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

예를 들어 Cloud Spanner 확장 프로그램을 사용하여 데이터베이스에 행을 추가하지만 행의 기본 키 값이 기존 행에서 이미 사용되고 있다고 가정해 보겠습니다. Cloud Spanner에서 확장 프로그램에 오류를 반환하고 확장 프로그램에서 확장 프로그램 로그에 오류를 추가합니다.

Trace 도구의 증거

프록시 편집기에서 이러한 오류는 일반적으로 4xx- 또는 5xx-수준 오류로 표시됩니다. 하지만 프록시 편집기에는 확장 프로그램에서 오류를 반환했다는 것 외에는 오류의 원인에 대한 세부정보가 표시되지 않습니다.

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404",
    "detail":{
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

확장 프로그램 로그의 증거

로그에는 일반적으로 외부 리소스 자체의 메시지가 포함된 항목이 있습니다. Cloud Spanner의 다음 로그 메시지는 기존 기본 키 값 오류를 설명합니다.

details: 'Row [jonesy42] in table user already exists'