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 and control plane components produce separate access and error logs, with destinations that depend on the deployment method.

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:

Log type	Description	Default destination
Error log	Gateway startup events, plugin errors, upstream failures, and core errors.	logs/error.log
Access log	One line per request processed by the gateway.	logs/access.log

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 Data Plane Logging below and Collect Gateway Logs on Kubernetes for the volume, rotation, and collector requirements on Kubernetes.

Control Plane Logs

Dashboard, DP Manager, and Developer Portal produce error and access logs. The official Docker Compose and Helm configurations use the following default destinations:

Log type	Description	Default destination
Error log	Component events, warnings, and errors, including configuration processing, database access, and configuration synchronization issues.	stderr
Access log	HTTP request summaries, including the request path, result, duration, and source.	stdout

In the official Docker Compose and Helm configurations, Dashboard, DP Manager, and Developer Portal write error logs directly to standard error (stderr) and access logs directly to standard output (stdout). These destinations are process output streams, not file paths or symbolic links. Therefore, the default container deployment has no regular access or error log files to tail; collect both streams from its container output instead.

For RPM installations from version 3.10.2, Dashboard writes to /var/log/api7/dashboard.log and /var/log/api7/dashboard-access.log by default, while DP Manager writes to /var/log/api7/dp-manager.log and /var/log/api7/dp-manager-access.log. Both components use warn as the default application log level.

Both destinations are configurable. See Configure Control Plane Logging below.

Use your container runtime to inspect the logs, for example:

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

Requests to /healthz are excluded from access logs.

Access logs include the request path and query string. In versions 3.10.0 through 3.10.8, all query parameter values, including the credential in key_value, are logged unchanged. Starting in 3.10.9, its value is masked as key_value=***. Other query parameters remain unmasked, so avoid including sensitive data in query strings.

The optional File Server and API Usage services also produce error and access logs. In Helm, File Server defaults to warn; in Docker Compose, API Usage defaults to debug. Both write application logs to stderr and access logs to stdout. The configuration examples below focus on Dashboard, DP Manager, and Developer Portal.

Control Plane Log Contents

• Application logs. Entries from the main application logger include a timestamp, level, code location, message, and event-specific fields. Request-scoped entries can include request_id, which can correlate them with the access log for the same request.
• Access logs. Entries begin with [HTTP] and record the timestamp, request ID, method, path and query string, status code, duration, client IP, User-Agent, user ID, request and response body lengths, and any error message attached during request processing. A missing request ID or user ID appears as -. Values such as the path, User-Agent, and error message can contain spaces, so do not parse entries by splitting on spaces. Access logs record body lengths, not complete request or response bodies.

Covered administrative changes are recorded separately in the audit log, which is viewable in the Dashboard. See that page for coverage limitations and sensitive-data handling.

Configure Data Plane Logging

Data plane logging settings control log destinations, error-log verbosity, and access-log format.

Set Log Destinations and Error Log Level

Configure log destinations and error-log verbosity with the following keys in the gateway's config.yaml:

conf/config.yaml

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 "$upstream_scheme://$upstream_host$upstream_uri" "$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:

conf/config.yaml

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.

Configure Control Plane Logging

Dashboard, DP Manager, and Developer Portal use separate configurations with the same log settings. Update each component that you want to change.

Configure Logging in Configuration Files

Edit the log section in the configuration file used by the component, preserving the other settings:

Deployment	Component	Configuration file
Bundled control-plane Docker Compose stack	Dashboard	dashboard_conf/conf.yaml
Bundled control-plane Docker Compose stack	DP Manager	dp_manager_conf/conf.yaml
Bundled control-plane Docker Compose stack	Developer Portal API	developer_portal_conf/conf.yaml
Standalone Developer Portal Docker Compose	Developer Portal API	backend_conf/conf.yaml
RPM, version 3.10.2 or later	Dashboard	/usr/local/api7/dashboard/conf/dashboard.yaml
RPM, version 3.10.2 or later	DP Manager	/usr/local/api7/dp-manager/conf/dp-manager.yaml

The following example matches the logging defaults in the official Docker Compose and Helm configurations for Dashboard, DP Manager, and Developer Portal:

log:
  level: warn
  output: stderr
  access_log: stdout

Setting	Description
log.level	The minimum application log level. Accepted values are debug, info, warn, error, panic, and fatal. At warn, warnings, errors, and more severe events are recorded.
log.output	The application log destination: stderr, stdout, or a file path.
log.access_log	The access log destination: stdout, stderr, or a file path.

Access logs have no separate log level and are not filtered by log.level. Setting log.access_log to an empty string still writes access logs to stdout; it does not disable access logging. Changing log.level neither disables access logging nor adds fields to access log entries.

For file output, create the parent directory in advance and grant the running user write permission. Logs are appended to files. In containers, mount persistent storage for that directory and configure log collection, rotation, and retention.

When log.output is stdout or stderr, application log entries use colored console encoding and can contain ANSI color codes. When log.output is a file, application log entries use JSON, while database (GORM) and etcd-compatibility (kine) entries remain plain text in the same file. Configure the log collector to handle these formats.

Restart the corresponding component after changing its configuration.

Configure Logging with Helm

In your existing values file for the api7/api7ee3 control plane chart, update dashboard_configuration.log, dp_manager_configuration.log, and developer_portal_configuration.log as needed. Preserve the other settings. The following example sets the error log level to warn, sends error logs to stderr, and sends access logs to stdout for all three components:

values.yaml

dashboard_configuration:
  log:
    level: warn
    output: stderr
    access_log: stdout

dp_manager_configuration:
  log:
    level: warn
    output: stderr
    access_log: stdout

developer_portal_configuration:
  log:
    level: warn
    output: stderr
    access_log: stdout

Update the deployment using the currently installed chart version and a values file containing your complete existing configuration:

helm upgrade <release-name> api7/api7ee3 \
  --namespace <namespace> \
  --version <installed-chart-version> \
  -f <values-file>

The chart triggers a rolling update of the corresponding Pods when their configuration changes. After the update completes, check the logs of the new Pods. For more deployment configuration details, see Deploy API7 Enterprise on Kubernetes.

Forward Logs to a Centralized System

You have two complementary options:

• Collect container output or ship configured log files. This applies to both data plane and control plane logs. 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 for the data plane. This works with any backend and decouples log delivery from the request path.
• Stream data plane request 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. These plugins do not forward control plane logs. Available logger plugins include http-logger, kafka-logger, syslog, splunk-hec-logging, google-cloud-logging, elasticsearch-logger, rocketmq-logger, and clickhouse-logger. For a full Splunk HEC walkthrough, see Send Access Logs to Splunk.

For data plane logs on 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 gateway 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.