IBM API Connect Debugヘッダー

はじめに

IBM API Connectの問題解析をする際、APIリクエストにあるHTTPヘッダーを付加すると、デバッグっぽい情報が出力されるので、何かの役にたつ(かもしない)という記事です。

前提条件

2019/12時点のIBM Cloud API Connectサービスを利用します。
IBM CloudのAPI Connectは v5ベースになります。

さっそく実行

HTTPヘッダーに、APIm-Debug:trueを付加すると、APICの分析情報にデバッグらしき情報が出力されます。

リンク先の記事で作成したAPIに、上記HTTPヘッダーを付加して、実行します。

今回は、curlコマンドに-vオプションをつけて、レスポンスのHTTPヘッダーも眺めてみます。

API実行結果サンプル

curl -v -H "APIm-Debug:true" https://api.us-south.apiconnect.appdomain.cloud/xxx/env1/env-api/go

*   Trying 104.19.237.26...
===省略===
< apim-debug-filename: temporary:///apimdebug.json
< apim-debug-trans-id: 10.121.103.141-bdc11955-ba23-484d-81af-ff944c0eab25
===省略===

'{"message" : "stub1だよ" }'

apim-debug-xxxというヘッダーが出力されていることがわかります。

分析情報のダウンロード

デバッグ情報を見るためには、分析情報をレコード単位で参照する必要があります。
画面では、レコード単位の情報を直接参照できませんが、ダウンロードがは能です。
※なお、APIC v2018では、画面から参照可能になっています

ダウンロードは、APIを実行したカタログを選択し、Analytics(日本語では分析)タブから、下図赤枠の操作で可能です。

「analytics_export.csv」というファイル名でダウンロードされます。

デバッグ情報

CSVファイルは、1行目が列名になっており、その中にdebug列があります。

macのNumbersで、CSVファイルを参照した際のスクショです。
1行目のレコードが、APIm-Debug:trueを付加したAPIリクエストのものです。
2、３行目はヘッダーを付与しなかったため、debug列は出力されていません。

1行目のdebug列を整形した結果が以下のとおりです。
アセンブルのポリシーごとに入出力結果が出力されています。
今回実行したAPIのアセンブルは、invokeポリシーが一つだけなので、1セットだけ出力されています。

また、出力先頭のtransidに、APIレスポンスのHTTPヘッダー(apim-debug-trans-id)の値も出力されているので、値を控えておけば、APIリクエストとの紐付けも可能です。

分析情報-debug列

[
  {
    "transid": "10.121.103.141-bdc11955-ba23-484d-81af-ff944c0eab25"
  },
  {
    "input": {
      "parameters": {
        "properties": [
          {
            "request": {
              "request-uri": "https://169.55.21.6:443/xxx/env1/env-api/go",
              "org": "xxx",
              "env": "env1"
            },
            "application": {
              "client-id": "",
              "app-type": "PRODUCTION",
              "app-name": ""
            },
            "api": {
              "basepath": "env-api",
              "name": "env-api",
              "type": "REST",
              "version": "1.0.0",
              "operation": "go"
            },
            "plan": {
              "name": "",
              "id": "",
              "version": ""
            }
          }
        ]
      }
    },
    "name": "API Information"
  },
  {
    "output": {
      "response": {
        "headers": {
          "APIm-Debug-Filename": "temporary:///apimdebug.json",
          "CF-IPCountry": "US",
          "Server": "cloudflare",
          "CF-RAY": "53fc8779d99cc7c5-DEN",
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "GET",
          "X-Forwarded-Proto": "https",
          "CF-Visitor": "{\"scheme\":\"https\"}",
          "CDN-Loop": "cloudflare; subreqs=1",
          "X-Global-Transaction-ID": "0e4c94ff5de7732c0f2a9fd3",
          "Accept-Encoding": "gzip",
          "APIm-Debug-Trans-Id": "10.121.103.141-64ed978e-1017-4628-86af-ff944c0ea185",
          "CF-Connecting-IP": "169.55.21.6",
          "Date": "Wed, 04 Dec 2019 08:49:49 GMT",
          "accept": "*/*",
          "Via": "1.1 BQAAAPKBlio-,1.1 BQAAAPWBlio-",
          "Access-Control-Expose-Headers": "APIm-Debug-Trans-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Global-Transaction-ID,APIm-Debug-Trans-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Global-Transaction-ID",
          "CF-Cache-Status": "DYNAMIC",
          "Cache-Control": "no-transform",
          "apim-debug": "true",
          "X-Forwarded-For": "203.141.91.14,169.55.21.6",
          "Set-Cookie": "__cfduid=d4781c2ba2a41b7119a3862fc4df61ff41575449389; expires=Fri, 03-Jan-20 08:49:49 GMT; path=/; domain=.apiconnect.appdomain.cloud; HttpOnly",
          "Content-Type": "unknown",
          "Expect-CT": "max-age=604800, report-uri=\"https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct\""
        },
        "body": "Not JSON, XML, or text data",
        "status": {
          "code": 200,
          "status": "OK"
        }
      }
    },
    "result": "OK",
    "input": {
      "request": {
        "headers": {
          "CF-IPCountry": "JP",
          "CF-RAY": "53fc877588c5a5b8-NRT",
          "X-Forwarded-Proto": "https",
          "CF-Visitor": "{\"scheme\":\"https\"}",
          "CDN-Loop": "cloudflare",
          "Accept-Encoding": "gzip",
          "X-Global-Transaction-ID": "0e4c94ff5de7732c0f2a9fd3",
          "CF-Connecting-IP": "203.141.91.14",
          "X-Client-IP": "162.158.118.207",
          "accept": "*/*",
          "Via": "1.1 BQAAAPKBlio-",
          "apim-debug": "true",
          "X-Forwarded-For": "203.141.91.14",
          "user-agent": "curl/7.54.0"
        },
        "body": ""
      }
    },
    "endpoint": "https://api.us-south.apiconnect.appdomain.cloud/xxx/sb/env-api-stub1/stub",
    "name": "invoke backend",
    "properties": {
      "verb": "GET",
      "target-url": "https://api.us-south.apiconnect.appdomain.cloud/xxx/sb/env-api-stub1/stub",
      "title": "invoke backend"
    }
  }
]

まとめ

今回は、API実行時のデバッグ情報を出力するためのHTTPヘッダーと、デバッグ情報の参照方法をご紹介しました。
通常、APICのビルトインポリシーは、開発者で任意のログを出力することはできないので(GatewayScriptポリシーを除く)、それらポリシーの処理結果を参照したい場合には有効な手段です。