Skip to main content
API7.ai Logo

error-log-collect

The error-log-collect plugin captures the error logs that the gateway produces while processing matched requests and writes them to the gateway error log (error.log). The captured entries include lower-severity logs, such as INFO and DEBUG, that the configured error log level would normally discard. This lets you collect detailed, request-scoped diagnostics for a targeted subset of traffic, without lowering the global error log level for all requests.

Each captured entry is written at error level, prefixed with [error-log-collect], and tagged with the request ID, so you can filter and correlate the entries in the gateway log. Use vars to restrict collection to requests that match a condition, and sample_ratio to capture only a fraction of requests on high-traffic routes.

This plugin is configured on routes or services, and is available in API7 Enterprise from version 3.10.0.

Examples​

The examples below demonstrate how you can configure error-log-collect in different scenarios.

Collect Error Logs on a Route​

The following example demonstrates how to enable the plugin on a route and view the collected logs.

Create a route to httpbin.org with the error-log-collect plugin enabled:

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
      }
    }
  }'

Send a request to the route:

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

You should receive an HTTP/1.1 200 OK response.

In the gateway log, look for entries prefixed with [error-log-collect], each tagged with the request ID. The plugin re-emits the internal logs generated while handling the request. These include INFO-level entries, such as DNS resolution and upstream selection, that the default warn log level would normally omit:

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
note

The plugin buffers the captured logs in memory per worker process, up to buffer_max_size entries. It flushes them to error.log when a request matches vars, or on every request when vars is not set. The buffer is shared by all requests that a worker handles, so a flush can also surface buffered logs from other recent requests on the same worker. This helps capture the context leading up to a matched event.

Collect Logs Only for Matching Requests​

To collect logs only for requests that meet a condition, set vars to one or more APISIX expressions. For example, the following configuration collects logs only when the request carries an X-Debug: true header:

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

Requests that do not match the condition are not flushed to the error log on their own. On high-traffic routes, set sample_ratio below 1 to collect logs for a random sample of requests and keep the log volume manageable.