Skip to content

Latest commit

 

History

History
140 lines (104 loc) · 5.31 KB

debug-mode.md

File metadata and controls

140 lines (104 loc) · 5.31 KB
Raw
id title keywords description
debug-mode
Debug mode
API gateway
Apache APISIX
Debug mode
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
#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

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

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:

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.

:::