跳到主要内容

error-log-collect

error-log-collect 插件捕获网关在处理匹配请求时产生的错误日志，并将其写入网关错误日志（error.log）。捕获的日志条目包括 INFO、DEBUG 等所配置的错误日志级别通常会丢弃的低级别日志。这使你能够针对部分目标流量收集详细的、按请求维度的诊断日志，而无需为所有请求降低全局错误日志级别。

每条捕获的日志均以 error 级别写入，并带有 [error-log-collect] 前缀和请求 ID，便于你在网关日志中过滤和关联这些条目。使用 vars 将收集范围限定为满足条件的请求，使用 sample_ratio 在高流量路由上仅捕获一部分请求。

该插件配置在路由或服务上，自 API7 企业版 3.10.0 版本起可用。

示例​

以下示例演示了如何在不同场景下配置 error-log-collect 插件。

在路由上收集错误日志​

以下示例演示了如何在路由上启用该插件并查看收集到的日志。

创建一个上游为 httpbin.org 并启用 error-log-collect 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "error-log-collect-route",
    "uri": "/anything",
    "plugins": {
      "error-log-collect": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向该路由发送请求：

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

你应该会收到 HTTP/1.1 200 OK 响应。

在网关日志中，查找带有 [error-log-collect] 前缀的条目，每条均带有请求 ID。该插件会重新输出处理请求过程中产生的内部日志，包括 DNS 解析、上游选择等默认 warn 日志级别通常会忽略的 INFO 级别条目：

2026/06/26 09:21:31 [error] 47#47: 1750901491123#0 [error-log-collect] 2026-06-26 09:21:31 b9f8c1d2e3a4f5061728394a5b6c7d8e parse_domain():118: dns resolve httpbin.org, context: ngx.timer
备注

该插件按 worker 进程将捕获的日志缓存在内存中，最多缓存 buffer_max_size 条。当请求匹配 vars（或未设置 vars 时对每个请求）时，将缓存的日志刷写到 error.log。该缓冲区由同一 worker 处理的所有请求共享，因此一次刷写也可能输出同一 worker 上其他近期请求的缓存日志，有助于捕获匹配事件之前的上下文。

仅收集匹配请求的日志​

要仅收集满足条件的请求的日志，请将 vars 设置为一个或多个 APISIX 表达式。例如，以下配置仅在请求带有 X-Debug: true 请求头时收集日志：

{
  "plugins": {
    "error-log-collect": {
      "vars": [
        ["http_x_debug", "==", "true"]
      ]
    }
  }
}

不匹配条件的请求不会自行将日志刷写到错误日志。在高流量路由上，可以将 sample_ratio 设置为小于 1 的值，仅收集随机抽样的部分请求，以保持日志量可控。