To debug a request, add the following request headers:
- At a minimum, you should set the
X-Kong-Request-Debug
header.
- If the requests originate from anywhere other than the loopback addresses, you also need the
X-Kong-Request-Debug-Token
header.
If the X-Kong-Request-Debug
header is set to *
, timing information will be collected and exported for the current request.
You can also specify a comma-separated list of filters to reduce the scope of the time information that is collected. Each filter specifies which phase to collect timing information from. The following filters are supported:
rewrite
access
balancer
response
header_filter
body_filter
upstream
log
If this header isn’t present or contains an unknown value, timing information will not be collected for the current request.
If the X-Kong-Request-Debug-Log
header is set to true, timing information will also be logged in the Kong Gateway error log with a log level of notice
. By default, the X-Kong-Request-Debug-Log
header is set to false
. The log line will have the [request-debug]
prefix to aid in searching.
The X-Kong-Request-Debug-Token
is the token used to authenticate the client and make debug request. This prevents debugging abuse. Debug requests originating from loopback addresses don’t require this 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
.
The log line produced by the debug header as well as the debug response header contains the request ID. You can use this to search for the debug header output using a log viewer UI. This is especially useful when the debug output is too long to fit in the response header. You can see an example log line that includes the request ID in the Truncation for large debugging output debug request example.