Project: APISIX (Orchestration & Management / API Gateway)
File: debug-mode.md

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. You can enable the basic debug mode by adding this line to your debug configuration file (`conf/debug.yaml`): ```yaml title="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 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. ```shell curl http://127.0.0.1:1984/hello -i ``` ```shell 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. ::: 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. | | hookconf.loglevel | True | warn | Log level for input arguments & returned values. | | hookconf.isprintinputargs | True | true | When set to `true` enables printing input arguments. | | hookconf.isprintreturnvalue | 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: ```yaml title="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 isprintinput_args: true # When set to `true` enables printing input arguments isprintreturn_value: true # When set to `true` enables printing returned values hookphase: # Module function list, Name: hookphase apisix: # Referenced module name httpaccessphase # Function namesArray httpheaderfilter_phase httpbodyfilter_phase httplogphase ``` 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`: ```yaml title="conf/debug.yaml" http_filter: enable: true # Enable/disable advanced debug mode dynamically enableheadername: X-APISIX-Dynamic-Debug # Trace for the request with this header ... ``` This will enable the advanced debug mode only for requests like: ```shell curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo' ``` :::note The `apisix.httpaccessphase` module cannot be hooked for this dynamic rule as the advanced debug mode is enabled based on the request. :::