Skip to main content
Version: 3.8

Debug mode

You can use APISIX's debug mode to troubleshoot your configuration.

Basic debug mode#

You can enable the basic debug mode by adding this line to your debug configuration file (conf/debug.yaml):

conf/debug.yaml
basic:
enable: true
#END

APISIX loads the configurations of debug.yaml on startup and then checks if the file is modified on an interval of 1 second. If the file is changed, APISIX automatically applies the configuration changes.

note

For APISIX releases prior to v2.10, basic debug mode is enabled by setting apisix.enable_debug = true in your configuration file (conf/config.yaml).

If you have configured two Plugins limit-conn and limit-count on the Route /hello, you will receive a response with the header Apisix-Plugins: limit-conn, limit-count when you enable the basic debug mode.

curl http://127.0.0.1:1984/hello -i
HTTP/1.1 200 OK
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Apisix-Plugins: limit-conn, limit-count
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 1
Server: openresty

hello world
IMPORTANT

If the debug information cannot be included in a response header (for example, when the Plugin is in a stream subsystem), the debug information will be logged as an error log at a warn level.

Advanced debug mode#

You can configure advanced options in debug mode by modifying your debug configuration file (conf/debug.yaml).

The following configurations are available:

KeyRequiredDefaultDescription
hook_conf.enableTruefalseEnables/disables hook debug trace. i.e. if enabled, will print the target module function's inputs or returned value.
hook_conf.nameTrueModule list name of the hook that enabled the debug trace.
hook_conf.log_levelTruewarnLog level for input arguments & returned values.
hook_conf.is_print_input_argsTruetrueWhen set to true enables printing input arguments.
hook_conf.is_print_return_valueTruetrueWhen set to true enables printing returned values.
note

A checker would check every second for changes to the configuration file. It will only check a file if the file was updated based on its last modification time.

You can add an #END flag to indicate to the checker to only look for changes until that point.

The example below shows how you can configure advanced options in debug mode:

conf/debug.yaml
hook_conf:
enable: false # Enables/disables hook debug trace
name: hook_phase # Module list name of the hook that enabled the debug trace
log_level: warn # Log level for input arguments & returned values
is_print_input_args: true # When set to `true` enables printing input arguments
is_print_return_value: true # When set to `true` enables printing returned values

hook_phase: # Module function list, Name: hook_phase
apisix: # Referenced module name
- http_access_phase # Function names:Array
- http_header_filter_phase
- http_body_filter_phase
- http_log_phase
#END

Dynamically enable advanced debug mode#

You can also enable advanced debug mode only on particular requests.

The example below shows how you can enable it on requests with the header X-APISIX-Dynamic-Debug:

conf/debug.yaml
http_filter:
enable: true # Enable/disable advanced debug mode dynamically
enable_header_name: X-APISIX-Dynamic-Debug # Trace for the request with this header
...
#END

This will enable the advanced debug mode only for requests like:

curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo'
note

The apisix.http_access_phase module cannot be hooked for this dynamic rule as the advanced debug mode is enabled based on the request.