Configure Centralized Logging

API7 Gateway produces several types of logs that are essential for debugging and operating the platform. For production environments, forward these logs to a centralized log management system such as Elasticsearch, Splunk, or AWS CloudWatch.

Log Types and Locations

Data Plane Logs

The data plane produces an error log and an access log. The default configuration uses paths relative to the gateway's installation prefix:

In a non-container installation, these destinations are regular files under the installation prefix. In the official container images, the resolved paths /usr/local/apisix/logs/error.log and /usr/local/apisix/logs/access.log are symbolic links to /dev/stderr and /dev/stdout, respectively. The gateway Helm chart writes to those device paths directly. Therefore, the default container deployment has no regular access or error log files to tail; collect its container output instead.

Both destinations are configurable. See Configure Log Files below and Collect Gateway Logs on Kubernetes for the volume, rotation, and collector requirements on Kubernetes.

Control Plane Logs

The control plane (Dashboard and DP Manager) emits structured logs to standard output of the corresponding container. Use your container runtime to inspect them, for example:

docker logs <api7-ee-dashboard-container>
docker logs <api7-ee-dp-manager-container>

Administrative changes (configuration created/updated/deleted, login activity, role changes) are recorded separately in the audit log, which is viewable in the Dashboard.

Configure Log Files

The following keys in the data plane's config.yaml control where logs are written and how verbose the error log is:

nginx_config:
  error_log: logs/error.log
  error_log_level: warn  # debug, info, notice, warn, error, crit, alert, emerg
  http:
    enable_access_log: true
    access_log: logs/access.log
    access_log_format: '$remote_addr - $remote_user [$time_local] $http_host "$request_line" $status $body_bytes_sent $request_time "$http_referer" "$http_user_agent" $upstream_addr $upstream_status $upstream_response_time "$apisix_request_id"'
    access_log_format_escape: default  # default or json

The example shows the default destinations. Relative paths are resolved against the gateway's installation prefix. To write regular files in an official container image, choose paths outside /usr/local/apisix/logs/, such as /var/log/apisix/access.log and /var/log/apisix/error.log. Create the directory before starting the gateway, grant the gateway process write access, and mount a volume at that path.

After changing any of these values, reload or restart the gateway for the new configuration to take effect.

Use a JSON Access Log Format

For easier parsing by log shippers, set a JSON access log format and switch escaping to json:

nginx_config:
  http:
    access_log_format: '{"time_local":"$time_local","remote_addr":"$remote_addr","status":"$status","request_time":"$request_time","upstream_status":"$upstream_status","request":"$request"}'
    access_log_format_escape: json

To include consumer labels in each access log line, see Include Consumer Labels in Access Logs.

Forward Logs to a Centralized System

You have two complementary options:

• Collect container output or ship configured log files. In container deployments, collect standard output and standard error unless you explicitly configure regular files. For file output, run a log forwarder such as Fluentd, Vector, Filebeat, or Logstash and tail the configured paths, such as /var/log/apisix/access.log and /var/log/apisix/error.log. This works with any backend and decouples log delivery from the request path.
• Stream logs directly from a route. Use one of the gateway's logger plugins to send structured request logs over the network without writing them to disk first. Available logger plugins include http-logger (opens in Plugin Hub docs), kafka-logger (opens in Plugin Hub docs), syslog (opens in Plugin Hub docs), splunk-hec-logging (opens in Plugin Hub docs), google-cloud-logging (opens in Plugin Hub docs), elasticsearch-logger (opens in Plugin Hub docs), rocketmq-logger (opens in Plugin Hub docs), and clickhouse-logger (opens in Plugin Hub docs). For a full Splunk HEC walkthrough, see Send Access Logs to Splunk.

For Kubernetes, see Collect Gateway Logs on Kubernetes to choose between container output and files in the pod, and to configure the OpenTelemetry Collector or Filebeat. For a Splunk-specific error-log workflow, see Send Kubernetes Error Logs to Splunk.

Next Steps

• Include Consumer Labels in Access Logs — include per-consumer metadata in every access log line.
• Collect Gateway Logs on Kubernetes — collect container output or files in the pod with the OpenTelemetry Collector or Filebeat.
• Send Access Logs to Splunk — stream logs to Splunk over HTTP.
• Send Kubernetes Error Logs to Splunk — collect Kubernetes gateway error logs with the Splunk OpenTelemetry Collector.
• Configure Alerts — get notified when error rates breach a threshold.
• Audit Logs — track configuration changes made through the Dashboard or Admin API.