跳到主要内容
版本:3.20.0

使用调试模式

APISIX 提供调试模式,帮助开发者更好地了解和排查网关的运行时行为。完整配置选项请参阅 debug.yaml。

本指南介绍如何启用调试模式,并按执行顺序检查插件阶段函数;还会说明如何添加钩子,将 APISIX 模块函数的输入参数和返回值写入日志。

前置条件​

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

启用基本调试模式​

基本调试模式会在 Apisix-Plugins 响应头中报告插件阶段函数。每个条目使用 plugin-name#phase 形式;条目按运行时执行顺序排列,而不是按插件配置顺序排列。

调试模式默认关闭。要启用基本调试模式,请在 debug.yaml 中将 basic.enable 设为 true。

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

APISIX 会在启动时将 debug.yaml 加载到内存,并定期检查文件变更,因此更新该文件后无需手动重新加载 APISIX。

信息

debug.yaml 配置应以 #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#access
...
信息

在发送响应头之前运行的阶段函数会被直接追踪。对于匹配的 Route 插件,由于 body_filter、delayed_body_filter 和 log 阶段稍后才运行,APISIX 会在发送响应头前推断这些条目。推断条目预期会执行,但仍可能在运行时被跳过,例如被 _meta.filter 跳过。

APISIX 无法在响应头之前追踪或推断的阶段函数会以 warn 级别写入错误日志。在此示例中,全局 Prometheus 插件在响应头之后运行,因此错误日志包含:

Apisix-Plugins: prometheus#log

由于 L4 流量没有 HTTP 响应头,Stream 插件阶段也会在错误日志中报告。

配置高级调试模式​

debug.yaml 还提供了其他高级配置选项。

记录函数输入参数和返回值​

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

debug.yaml
basic:
enable: true
http_filter:
enable: false
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:{}

动态应用高级调试设置​

你也可以在请求包含特定请求头时,动态记录函数输入参数和返回值:

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
' > /usr/local/apisix/conf/debug.yaml"

❶ 启用 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。