id: debug-mode title: Debug mode keywords:

  • API gateway
  • Apache APISIX
  • Debug mode description: Guide for enabling debug mode in Apache APISIX.

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):

basic:
  enable: true

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 Plgins 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

:::info 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:

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:

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.

:::