跳到主要内容

error-log-collect

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

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

该插件配置在路由或服务上，首次分别在 API7 企业版 3.9.6 和 3.10.0 中引入。

示例​

前提条件​

  • 对于 Admin API 标签页，请设置 Dashboard 地址和网关组，然后输入 Dashboard Token：

    export API7_ADMIN_URL="https://localhost:7443"
    export API7_GATEWAY_GROUP_ID="default"
    printf "Dashboard Token："
    read -rs API7_ADMIN_KEY && export API7_ADMIN_KEY && echo

    这些示例中的 -k 标志会接受本地 Dashboard 的自签名证书。使用客户端信任的证书时，请移除此标志。

  • 对于 ADC 标签页，请选择 api7ee 后端，并配置相应的 Dashboard 地址、Token 和网关组。

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

在路由上收集错误日志​

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

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

创建一个以 httpbin.org 为上游的服务：

curl -k "${API7_ADMIN_URL}/apisix/admin/services/error-log-collect-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "error-log-collect-service",
    "upstream": {
      "type": "roundrobin",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 1
        }
      ]
    }
  }'

在该服务中创建一条启用了 error-log-collect 插件的路由：

curl -k "${API7_ADMIN_URL}/apisix/admin/routes/error-log-collect-route?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "error-log-collect-route",
    "service_id": "error-log-collect-service",
    "paths": ["/anything"],
    "plugins": {
      "error-log-collect": {}
    }
  }'

向该路由发送请求：

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

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

在网关日志中查找以 [error-log-collect] 为前缀的条目，每个条目都带有请求 ID。插件会重新输出处理请求时生成的内部日志，其中包括 DNS 解析和上游选择等 INFO 级别条目；默认的 warn 日志级别通常会省略这些条目：

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
备注

插件会在每个工作进程的内存中缓冲捕获的日志，最多可保存 buffer_max_size 个条目。当请求匹配 vars 时，插件会将其刷新到 error.log；如果未设置 vars，则会对每个请求执行刷新。缓冲区由同一工作进程处理的所有请求共享，因此刷新时也可能输出该工作进程近期其他请求的缓冲日志。这有助于捕获匹配事件发生前的上下文。

仅收集匹配请求的日志​

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

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

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