Error Log Collect

The error-log-collect plugin captures the error logs produced while processing selected requests, including lower-severity entries that the configured log level would otherwise discard, and writes them to the gateway error log for targeted debugging.

Enterprise

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

adc.yaml

services:
  - name: error-log-collect-service
    routes:
      - name: error-log-collect-route
        uris:
          - /anything
        plugins:
          error-log-collect: {}
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

error-log-collect.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
    - type: Domain
      name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: error-log-collect-route
spec:
  ingressClassName: apisix
  http:
    - name: anything
      match:
        paths:
          - /anything
      upstreams:
        - name: httpbin-external-domain
      plugins:
        - name: error-log-collect
          config: {}

Apply the configuration to your cluster:

kubectl apply -f error-log-collect.yaml

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

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.