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:
- Admin API
- ADC
- Ingress Controller
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
}
}
}'
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
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.