拡張機能のデバッグ

拡張機能は、Trace ツールと拡張機能ログの 2 か所に表示されるメッセージを使用してデバッグできます。拡張機能が機能しない場合、この両方からの情報が問題の特定に必要になることがあります。

  • Apigee Edge Trace ツールは、開発の際に API プロキシコードを繰り返しテストし、編集するツールです。トレース メッセージには、API プロキシコード(API プロキシやポリシー構成など)からのエラーが含まれます。

    Trace ツールに表示される拡張機能関連のエラーには通常、HTTP エラーコードに加えて拡張機能の呼び出しが失敗したということ以外、詳細な情報はあまり含まれていません。ここで何か役に立つ情報が見つからない場合、次に確認すべきものは、使用中の拡張機能のログです。

  • 拡張機能は、実行時にログエントリを生成します(拡張機能のログを使用できるのは、組織管理者だけです)。

    このログには、拡張機能がやりとりするように構成されている外部リソースから返されたエントリが含まれます。たとえば、拡張機能で外部リソースの認証情報が誤って構成されていると、ここにエラーが表示される可能性があります。

    ログには、内部の拡張機能コードからのエントリも含まれます。ログを調べているとき、エントリのうちのいくつかは、修正中のエラーに関係しないことに注意してください。拡張機能関連のログエントリは通常、次に示す Cloud Pub/Sub 拡張機能からのログエントリのように、先頭が details になります。

    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 プロキシの Extension Callout ポリシーから、拡張機能を介して外部リソースに流れ、その後再び戻ります。そのため、このうちのどこかでエラーが発生するおそれがあります。

表示されるエラーは、次のカテゴリに分類されます。

拡張機能構成のエラー

これは、環境に拡張機能を追加するときに組織管理者が行う構成です。

たとえば、正しくない GCP プロジェクト ID で Stackdriver Logging 拡張機能を構成した場合、Google Stackdriver が拡張機能にエラーを返します。このエラーの詳細情報は通常、拡張機能ログにあります。

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'
    

Extension Callout ポリシー構成のエラー

このエラーは、ポリシー構成の構文エラーまたは正しくない構成キーや値による、Extension Callout ポリシーの構成ミスの場合に発生します。このエラーは、ポリシーの構成方法に応じて 2 つの形式をとります。

  • 外部リソースによって評価される正しくない値

    これは、構成エラーが拡張機能には有効であるように見えたものの、外部リソースに対しては無効であった場合に発生する可能性があります。たとえば、拡張機能が正しくないデータベース 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 の一部が拡張機能によって処理され、一部がリソースに渡されるものもあります。たとえば Stackdriver Logging 拡張機能の構成 JSON には、コンテンツが Stackdriver 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'