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​

Prerequisites​

  • For the Admin API tabs, set the Dashboard address and gateway group, then enter a 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

    The -k flag in these examples accepts the local Dashboard's self-signed certificate. Remove it when using a certificate trusted by the client.

  • For the ADC tabs, select the api7ee backend and configure the corresponding Dashboard address, token, and gateway group.

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:

Create a service with httpbin.org as its upstream:

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

Create a route in the service with the error-log-collect plugin enabled:

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": {}
    }
  }'

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.