問題を報告するデバッグリクエスト
Kong Gateway管理者は、特定のリクエストに関するタイミング情報をオンデマンドで収集することにより、リクエストをデバッグできます。リクエストのデバッグは安全なトークンを使用してトリガーされ、結果のデータは X-Kong-Request-Debug-Output という名前の応答ヘッダーで返されます。
リクエストのデバッグでは、次の分析情報が提供されます。
- プラグイン、DNS 解決、ロードバランシングなどのさまざまな Kong Gateway コンポーネントで使用した時間。
- これらのプロセス中に試行されたドメイン名などの文脈情報。
注： この機能はライブデバッグ用です。タイミングを含むヘッダーのJSONスキーマは決して静的と見なすべきではなく、常に変更される可能性があります。
警告: ループバックアドレスから生成されたデバッグ要求は X-Kong-Request-Debug-Token で保護されていません。 他のプロキシの後ろに Kong Gateway を配置することは、認証なしにデバッグインターフェイスを公開することは危険です。
リクエストのデバッグを有効にする
リクエストのデバッグはデフォルトで有効になっており、 kong.confでは次の構成になっています。
request_debug = on | off # enable or disable request debugging
request_debug_token <token id="sl-md0000000"> # Set debug token explicitly. Otherwise, it will be generated randomly when Kong starts, restarts, and reloads.
デバッグトークン（request-debug-token）を使用すると、権限のある人だけがデバッグリクエストを発行できるため、機能の乱用を防ぐことができます。
デバッグトークンは次の場所にあります。
-
Kong Gateway エラーログ: Kong Gateway の起動、再起動、またはリロード時に、デバッグトークンがエラーログ（通知レベル）に記録されます。検索を容易にするために、ログ行には
[request-debug]プレフィックスが付けられます。 -
ファイルシステム： デバッグトークンは
{prefix}/.request_debug_tokenにあるファイルにも保存され、Kong Gatewayの起動時、再起動時、または再読み込み時に更新されます。
デバッグリクエストの構成
リクエストをデバッグするには、次のリクエストヘッダーを追加します。
- 少なくとも、
X-Kong-Request-Debugヘッダーを設定する必要があります。 - リクエストがループバックアドレス以外から送信された場合は、
X-Kong-Request-Debug-Tokenヘッダーも設定する必要があります。
X-Kong-Request-Debug ヘッダー
X-Kong-Request-Debug ヘッダーが * に設定されている場合、現在のリクエストのタイミング情報が収集され、エクスポートされます。
Kong Gateway Enterpriseで、収集される時間情報の範囲をフィルタリングするために、フィルターをカンマで区切ったリストで指定することもできます。各フィルターは時間情報を収集するフェーズを指定します。サポートされるフィルターは以下のとおりです。
rewriteaccessbalancerresponseheader_filterbody_filterupstreamlog
このヘッダーが存在しないか不明な値を含んでいる場合、タイミング情報は現在のリクエストに対して収集されません。
X-Kong-Request-Debug-Log header
X-Kong-Request-Debug-Log ヘッダーが true に設定されている場合、タイミング情報はログレベル notice で Kong Gateway エラーログにも記録されます。デフォルトでは、X-Kong-Request-Debug-Log ヘッダーは false に設定されています。ログラインには、検索を容易にするためのプレフィックス [request-debug] が含まれます。
X-Kong-Request-Debug-Token ヘッダー
The X-Kong-Request-Debug-Token is a token for authenticating the client and making the debug request to prevent abuse. Debug requests originating from loopback addresses don’t require this header.
X-Kong-Request-Id header
The X-Kong-Request-Id header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If Kong Gateway returns an error by calling the PDK kong.response.error, the request ID will also be included in the response body generated by Kong Gateway. In addition, any Kong Gateway error log generated will contain the same request ID, with the format: request_id: xxx.
デバッグヘッダーとデバッグレスポンスヘッダーによって生成されるログ行には、リクエスト ID が含まれています。これを使用すると、ログビューアー UI でデバッグヘッダー出力を検索できます。これは、デバッグ出力が長すぎてレスポンスヘッダーに収まらない場合に特に便利です。大規模なデバッグ出力の一部切り取りに示すデバッグリクエストの例では、リクエスト ID を含むログ行の例を確認できます。
デバッグリクエストの例
以下はデバッグリクエストの例です。
curl http://localhost:8000/example \
-H "X-Kong-Request-Debug: *" \
-H "X-Kong-Request-Debug-Token: xxxxxx"
レスポンスヘッダーの出力例を次に示します。
{
"child": {
"rewrite": {
"total_time": 0
},
"access": {
"child": {
"dns": {
"child": {
"example.com": {
"child": {
"resolve": {
"total_time": 0,
"cache_hit": true
}
},
"total_time": 0
}
},
"total_time": 0
},
"plugins": {
"child": {
"rate-limiting": {
"child": {
"176928d4-0949-47c8-8114-19cac8f86aab": {
"child": {
"redis": {
"total_time": 1,
"child": {
"connections": {
"child": {
"tcp://localhost:6379": {
"child": {
"connect": {
"child": {
"dns": {
"child": {
"localhost": {
"child": {
"resolve": {
"total_time": 0,
"cache_hit": true
}
},
"total_time": 0
}
},
"total_time": 0
}
},
"total_time": 0
}
},
"total_time": 0
}
},
"total_time": 0
}
}
}
},
"total_time": 2
}
},
"total_time": 2
},
"request-transformer": {
"child": {
"cfd2d953-ad82-453c-9979-b7573f52c226": {
"total_time": 0
}
},
"total_time": 0
}
},
"total_time": 2
}
},
"total_time": 3
},
"log": {
"child": {
"plugins": {
"child": {
"http-log": {
"child": {
"22906259-2963-4c6d-96a1-6d36d21714e3": {
"total_time": 4
}
},
"total_time": 4
}
},
"total_time": 4
}
},
"total_time": 4
},
"header_filter": {
"child": {
"plugins": {
"child": {
"response-transformer": {
"child": {
"dee98076-a58f-490d-8f7b-8523506bf96d": {
"total_time": 1
}
},
"total_time": 1
}
},
"total_time": 1
}
},
"total_time": 1
},
"body_filter": {
"child": {
"plugins": {
"child": {
"response-transformer": {
"child": {
"dee98076-a58f-490d-8f7b-8523506bf96d": {
"total_time": 0
}
},
"total_time": 1
}
},
"total_time": 1
}
},
"total_time": 1
},
"balancer": {
"total_time": 0
},
"upstream": {
"total_time": 152,
"child": {
"time_to_first_byte": {
"total_time": 151
},
"streaming": {
"total_time": 1
}
}
}
},
"request_id": "0208903e83001d216bee5435dbc5ed25"
}
デバッグ出力の例を分析すると、次のことがわかります。
-
total_timeの単位はmillisecondです。 -
example.hostの DNS 解決がキャッシュされているため、この例では非常に高速です。 - このリクエストではアップストリームに 100 ミリ秒かかりました。
- Kong Gatewayがアップストリームにリクエストを送信してからKong Gatewayが最初のバイトを受信するまでの経過時間は20ミリ秒です。
- アップストリームからの最初のバイトから最後のバイトまでの経過時間は 80 ミリ秒です。
デバッグ出力をフィルタリングすることもできます。
curl http://localhost:8000/example \
-H "X-Kong-Request-Debug: upstream" \
-H "X-Kong-Request-Debug-Token: xxxxxx"
次のような結果が返されます。
{
"request_id": "a1a1530f8ddb6f6f2462916ae002b715",
"child": {
"upstream": {
"total_time": 363,
"child": {
"time_to_first_byte": {
"total_time": 363
}
}
}
}
}
大きなデバッグ出力の切り捨て
ダウンストリームのシステムでは、応答ヘッダーにサイズ制限が課せられている場合があり、Kong GatewayはX-Kong-Request-Outputが2KBを超えるとをこれを切り捨てます。この切り捨てられた出力は、無条件にerror_logに記録されます。
curl http://localhost:8000/large_debugging_output \
-H "X-Kong-Request-Debug: *" \
-H "X-Kong-Request-Debug-Token: xxxxxx"
次のような結果が返されます。
{
"request_id": "60ca0a4f8e5e936c43692f49b27d2932",
"truncated": true,
"message": "Output is truncated, please check the error_log for full output by filtering with the request_id."
}
デバッグリクエストの出力が 3KB を超える場合、request_id を識別子として複数の部分に分割されます。
注: デバッグ出力には一貫したパターンがなく、将来変更される可能性があります。自動化されたツールで処理するようには設計されていません。むしろ、人間が読みやすいように意図されていました。
