跳到主要内容

使用调试模式

APISIX提供了一个调试模式,帮助开发者更好地理解和排除网关的运行时行为. 完整的配置选项可以在debug.yaml中找到.

此指南将显示如何让调试模式检查所请求的路由中启用的插件,以及如何在日志输入参数和APISIX模块函数的返回值中添加钩子.

先决条件​

  • 安装 Docker。
  • 安装 cURL，用于向 APISIX 发送验证请求。
  • 按照快速入门教程在 Docker 或 Kubernetes 中启动新的 APISIX 实例。

启用基本调试模式​

启用基本的调试模式将允许您检查Apisix-Plugins请求头中请求的路由中启用的插件 。

默认情况下,调试模式会关闭. 要启用调试模式, 您可以在您的basic.enable文件内设置true到debug.yaml。

docker exec apisix-quickstart /bin/sh -c "echo '
basic:
  enable: true
#END
' > /usr/local/apisix/conf/debug.yaml"

debug.yaml文件在启动时被装入内存,并在正常间隔时监视更改,这样在更新文件后不需要手动重新装入APISIX.

信息

debug.yaml配置应该以#END结尾,否则APISIX不会加载配置.

也可以使用#END旗作为APISIX仅加载到指定点的配置的断点.

要校验, 请创建一条没有插件的路由 :

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "getting-started-anything",
  "uri": "/anything",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

向路由发送请求 :

curl -i "http://127.0.0.1:9080/anything"

您应当收到HTTP/1.1 200 OK响应,并观察以下请求头:

Content-Type: application/json
Content-Length: 390
Connection: keep-alive
Apisix-Plugins: no plugin
...

以插件更新路由 :

curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-anything" -X PATCH -d '
{
  "plugins": {
    "limit-count": {
      "count": 5,
      "time_window": 10,
      "rejected_code": 429
    }
  }
}'

此外,增加一个全局插件:

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT -d '{
  "id": "global-prometheus",
  "plugins": {
    "prometheus":{}
  }
}'

向路由发送另一个请求 :

curl -i "http://127.0.0.1:9080/anything"

您应该收到一个HTTP/1.1 200 OK的响应,其请求头类似于以下内容:

Content-Type: application/json
Content-Length: 388
Connection: keep-alive
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 10
Apisix-Plugins: limit-count, prometheus
...
信息

如果插件信息无法包含在响应头(例如L4流插件)中,调试信息将在错误日志中记录在warn重级.

配置高级调试模式​

debug.yaml中还有其他几个高级选项可以配置.

日志函数输入参数和返回的值​

你可以在 APISIX 阶段中添加钩子，记录输入参数和返回值，配置如下：

debug.yaml
basic:
  enable: true
hook_conf:
  enable: true
  name: hook_phase
  log_level: warn
  is_print_input_args: true
  is_print_return_value: true
hook_phase:
  apisix:
    - http_access_phase
    - http_header_filter_phase
    - http_body_filter_phase
    - http_log_phase
#END

❶ 启用钩调试跟踪以登录目标模块函数的输入参数或返回的值.

❷ 模块名称和函数列表 。

❸ 输入参数和返回错误日志中值的高度 。

❹ 记录输入参数。

❺ 记录返回值。

❻ 模块名称和函数列表 。

为了核实,向路由发送请求:

curl -i "http://127.0.0.1:9080/anything"

您应当收到HTTP/1.1 200 OK响应,并在错误日志中查看以下信息:

call require("apisix").http_access_phase() args:{}
call require("apisix").http_access_phase() return:{}
call require("apisix").http_header_filter_phase() args:{}
call require("apisix").http_header_filter_phase() return:{}
call require("apisix").http_body_filter_phase() args:{}
call require("apisix").http_body_filter_phase() return:{}
call require("apisix").http_log_phase() args:{}
call require("apisix").http_log_phase() return:{}

动态应用高级调试设置​

当某个请求头带有以下配置时,您也可以动态日志函数输入参数并返回值:

debug.yaml
docker exec apisix-quickstart /bin/sh -c "echo '
basic:
  enable: true
http_filter:
  enable: true
  enable_header_name: X-APISIX-Dynamic-Debug
hook_conf:
  enable: true
  name: hook_phase
  log_level: warn
  is_print_input_args: true
  is_print_return_value: true
hook_phase:
  apisix:
    - http_access_phase
    - http_header_filter_phase
    - http_body_filter_phase
    - http_log_phase
#END

❶ 启用 HTTP 过滤器以动态应用高级调试设置 。

❷ 日志输入参数和返回值, 只有当请求有X-APISIX-Dynamic-Debug头时。

为核实, 请将请求发送到没有请求头的路由 :

curl -i "http://127.0.0.1:9080/anything"

您应该收到HTTP/1.1 200 OK响应, 但不会在错误日志中看到调试信息 。

用调试头发送另一个请求 :

curl -i "http://127.0.0.1:9080/anything" -H "X-APISIX-Dynamic-Debug: 1"

您应当收到HTTP/1.1 200 OK响应,并在错误日志中查看以下信息:

call require("apisix").http_access_phase() args:{}
call require("apisix").http_access_phase() return:{}
call require("apisix").http_header_filter_phase() args:{}
call require("apisix").http_header_filter_phase() return:{}
call require("apisix").http_body_filter_phase() args:{}
call require("apisix").http_body_filter_phase() return:{}
call require("apisix").http_log_phase() args:{}
call require("apisix").http_log_phase() return:{}

由环境管理debug.yaml​

您不妨为每种环境拥有不同的debug.yaml文件,例如使用conf/debug-dev.yaml进行开发,使用conf/debug-prod.yaml进行生产. 这可以通过设置APISIX_PROFILE变量来实现.

详情请参阅按环境管理配置文件。

下一步​

现在你已经了解如何使用 APISIX 调试模式进行故障排查，以及该模式提供的各项调试功能。完整配置选项请参阅 debug.yaml。