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

  1. basic:
  2. enable: true
  3. #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.

Debug mode - 图1note

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.

  1. curl http://127.0.0.1:1984/hello -i
  1. HTTP/1.1 200 OK
  2. Content-Type: text/plain
  3. Transfer-Encoding: chunked
  4. Connection: keep-alive
  5. Apisix-Plugins: limit-conn, limit-count
  6. X-RateLimit-Limit: 2
  7. X-RateLimit-Remaining: 1
  8. Server: openresty
  9. hello world
Debug mode - 图2IMPORTANT

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.
Debug mode - 图3note

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

  1. hook_conf:
  2. enable: false # Enables/disables hook debug trace
  3. name: hook_phase # Module list name of the hook that enabled the debug trace
  4. log_level: warn # Log level for input arguments & returned values
  5. is_print_input_args: true # When set to `true` enables printing input arguments
  6. is_print_return_value: true # When set to `true` enables printing returned values
  7. hook_phase: # Module function list, Name: hook_phase
  8. apisix: # Referenced module name
  9. - http_access_phase # Function names:Array
  10. - http_header_filter_phase
  11. - http_body_filter_phase
  12. - http_log_phase
  13. #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

  1. http_filter:
  2. enable: true # Enable/disable advanced debug mode dynamically
  3. enable_header_name: X-APISIX-Dynamic-Debug # Trace for the request with this header
  4. ...
  5. #END

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

  1. curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo'
Debug mode - 图4note

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