feat(debug-mode): add dynamic debug mode

apisix/debug.lua

@@ -17,9 +17,8 @@
 local require      = require
 local yaml         = require("tinyyaml")
 local log          = require("apisix.core.log")
-local json         = require("apisix.core.json")
 local profile      = require("apisix.core.profile")
-local process      = require("ngx.process")
+local request      = require("apisix.core.request")
 local lfs          = require("lfs")
 local io           = io
 local ngx          = ngx
@@ -30,6 +29,7 @@ local setmetatable = setmetatable
 local pcall        = pcall
 local ipairs       = ipairs
 local unpack       = unpack
+local inspect      = require "inspect"
 local debug_yaml_path = profile:yaml_path("debug")
 local debug_yaml
 local debug_yaml_ctime
@@ -126,13 +126,13 @@ local function apple_new_fun(module, fun_name, file_path, hook_conf)
         local arg = {...}
         if hook_conf.is_print_input_args then
             log[log_level]("call require(\"", file_path, "\").", fun_name,
-                           "() args:", json.delay_encode(arg, true))
+                    "() args:", inspect(arg))
         end
 
         local ret = {self.fun_org(...)}
         if hook_conf.is_print_return_value then
             log[log_level]("call require(\"", file_path, "\").", fun_name,
-                           "() return:", json.delay_encode(ret, true))
+                    "() return:", inspect(ret))
         end
         return unpack(ret)
     end
@@ -148,7 +148,9 @@ end
 
 function sync_debug_hooks()
     if not debug_yaml_ctime or debug_yaml_ctime == pre_mtime then
-        return
+        if not (debug_yaml and debug_yaml.http and debug_yaml.http.dynamic) then
+            return
+        end
     end
 
     for _, hook in pairs(enabled_hooks) do
@@ -200,7 +202,43 @@ local function sync_debug_status(premature)
 end
 
 
+local function check()
+    if not debug_yaml or not debug_yaml.http then
+        return false
+    end
+
+    local http = debug_yaml.http
+    if not http or not http.enable_header_name or not http.dynamic then
+        return false
+    end
+
+    return true
+end
+
+function _M.dynamic_enable(api_ctx)
+    if not check() then
+        return
+    end
+
+    if request.header(api_ctx, debug_yaml.http.enable_header_name) then
+        debug_yaml.hook_conf.enable = true
+        sync_debug_hooks()
+    end
+end
+
+
+function _M.dynamic_disable()
+    if not check() then
+        return
+    end
+
+    debug_yaml.hook_conf.enable = false
+    sync_debug_hooks()
+end
+
+
 function _M.init_worker()
+    local process = require("ngx.process")
     if process.type() ~= "worker" then
         return
     end

apisix/init.lua

@@ -30,6 +30,7 @@ local upstream_util   = require("apisix.utils.upstream")
 local ctxdump         = require("resty.ctxdump")
 local ipmatcher       = require("resty.ipmatcher")
 local ngx_balancer    = require("ngx.balancer")
+local debug           = require("apisix.debug")
 local ngx             = ngx
 local get_method      = ngx.req.get_method
 local ngx_exit        = ngx.exit
@@ -353,6 +354,8 @@ function _M.http_access_phase()
 
     core.ctx.set_vars_meta(api_ctx)
 
+    debug.dynamic_enable(api_ctx)
+
     local uri = api_ctx.var.uri
     if local_conf.apisix and local_conf.apisix.delete_uri_tail_slash then
         if str_byte(uri, #uri) == str_byte("/") then
@@ -704,6 +707,8 @@ function _M.http_log_phase()
         core.tablepool.release("matched_route_record", api_ctx.curr_req_matched)
     end
 
+    debug.dynamic_disable()
+
     core.tablepool.release("api_ctx", api_ctx)
 end
 

conf/debug.yaml

@@ -14,6 +14,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+http:
+  dynamic: false         # enable or disable this feature
+  enable_header_name: X-APISIX-Dynamic-Debug # the header name of dynamic enable
 hook_conf:
   enable: false                 # enable or disable this feature
   name: hook_phase              # the name of module and function list

docs/en/latest/architecture-design/debug-mode.md

@@ -76,3 +76,25 @@ hook_phase: # Module Function List, Name: hook_phase
     - http_log_phase
 #END
 ```
+
+### Dynamic Advanced Debug Mode
+
+Dynamic advanced debug mode is based on advanced debug mode, which can be enabled dynamically by a single request and turned off automatically when the request ends.
+
+Example:
+
+```yaml
+http:
+  dynamic: true # 是否动态开启高级调试模式
+  enable_header_name: X-APISIX-Dynamic-Debug # 对携带此 header 的请求开启高级调试模式
+......
+#END
+```
+
+Dynamically enable advanced debugging mode, example:
+
+```shell
+curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo'
+```
+
+Notice: Dynamic advanced debug mode cannot debug the `apisix.http_access_phase` module (because the request enters the `apisix.http_access_phase` module before it determines whether advanced debug mode is dynamically enabled).

docs/zh/latest/architecture-design/debug-mode.md

@@ -78,3 +78,25 @@ hook_phase: # 模块函数列表，名字：hook_phase
     - http_log_phase
 #END
 ```
+
+### 动态高级调试模式
+
+动态高级调试模式是基于高级调试模式，可以由单个请求动态开启高级调试模式，请求结束后自动关闭。设置 `conf/debug.yaml` 中的选项。
+
+示例：
+
+```yaml
+http:
+  dynamic: true # 是否动态开启高级调试模式
+  enable_header_name: X-APISIX-Dynamic-Debug # 对携带此 header 的请求开启高级调试模式
+......
+#END
+```
+
+动态开启高级调试模式，示例：
+
+```shell
+curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo'
+```
+
+注意：动态高级调试模式无法调试 `apisix.http_access_phase` 模块（因为请求进入 `apisix.http_access_phase` 模块后，才会判断是否动态开启高级调试模式）。

rockspec/apisix-master-0.rockspec

@@ -69,6 +69,7 @@ dependencies = {
     "ext-plugin-proto = 0.3.0",
     "casbin = 1.26.0",
     "api7-snowflake = 2.0-1",
+    "inspect == 3.1.1",
 }
 
 build = {