Debug Mode

Basic Debug Mode

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

  1. basic:
  2.   enable: true

Note: Before Apache APISIX 2.10, basic debug mode was enabled by setting apisix.enable_debug = true in the conf/config.yaml file.

For example, if we are using two plugins limit-conn and limit-count for a Route /hello, we will receive a response with the header Apisix-Plugins: limit-conn, limit-count when we enable the basic debug mode.

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

If the debug information cannot be included in a response header (say when the plugin is in a stream subsystem), the information will be logged in the error log at a warn level.

Advanced Debug Mode

Advanced debug mode can also be enabled by modifying the configuration in the conf/debug.yaml file.

Enable advanced debug mode by modifying the configuration in conf/debug.yaml file.

The checker checks every second for changes to the configuration files. An #END flag is added to let the checker know that it should only look for changes till that point.

The checker would only check this if the file was updated by checking its last modification time.

KeyOptionalDescriptionDefault
hook_conf.enablerequiredEnable/Disable hook debug trace. Target module function’s input arguments or returned value would be printed once this option is enabled.false
hook_conf.namerequiredThe module list name of the hook which has enabled debug trace.
hook_conf.log_levelrequiredLogging levels for input arguments & returned values.warn
hook_conf.is_print_input_argsrequiredEnable/Disable printing input arguments.true
hook_conf.is_print_return_valuerequiredEnable/Disable printing returned values.true

Example:

  1. hook_conf:
  2.   enable: false # Enable/Disable Hook Debug Trace
  3.   name: hook_phase # The Module List Name of Hook which has enabled Debug Trace
  4.   log_level: warn # Logging Levels
  5.   is_print_input_args: true # Enable/Disable Input Arguments Print
  6.   is_print_return_value: true # Enable/Disable Returned Value Print
  8. hook_phase: # Module Function List, Name: hook_phase
  9.   apisix: # Referenced Module Name
  10.     - http_access_phase # Function Names：Array
  11.     - http_header_filter_phase
  12.     - http_body_filter_phase
  13.     - http_log_phase
  14. #END

Enable Advanced Debug Mode Dynamically

You can also enable the advanced debug mode to take effect on particular requests.

For example, to dynamically enable advanced debugging mode on requests with a particular header name X-APISIX-Dynamic-Debug you can configure:

  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 for requests like:

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

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