Version: 3.11

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:

Key	Required	Default	Description
hook_conf.enable	True	false	Enables/disables hook debug trace. i.e. if enabled, will print the target module function's inputs or returned value.
hook_conf.name	True		Module list name of the hook that enabled the debug trace.
hook_conf.log_level	True	warn	Log level for input arguments & returned values.
hook_conf.is_print_input_args	True	true	When set to `true` enables printing input arguments.
hook_conf.is_print_return_value	True	true	When 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.