配置集中式日志记录

API7 网关会生成多种日志，用于调试和运维。生产环境建议将日志转发到 Elasticsearch、Splunk 或 AWS CloudWatch 等集中式日志管理系统。

日志类型和位置

数据面和控制面组件各自生成访问日志和错误日志，输出位置取决于部署方式。

数据面日志

数据面会产生错误日志和访问日志。默认配置使用相对于网关安装前缀的路径：

日志类型	说明	默认目标
错误日志	网关启动事件、插件错误、上游故障和核心错误。	logs/error.log
访问日志	网关处理的每个请求一行。	logs/access.log

在非容器部署中，这些目标就是安装前缀下的普通文件。而在官方容器镜像中，解析后的路径 /usr/local/apisix/logs/error.log 和 /usr/local/apisix/logs/access.log 是指向 /dev/stderr 和 /dev/stdout 的符号链接，网关 Helm Chart 也直接写入这两个设备路径。因此默认的容器部署没有可供读取的普通访问日志和错误日志文件，应改为采集容器输出。

两个输出位置均可配置。请参阅配置数据面日志，以及在 Kubernetes 上采集网关日志了解 Kubernetes 上对卷、轮转和采集器的要求。

控制面日志

控制台（Dashboard）、DP Manager 和开发者门户（Developer Portal）均生成错误日志和访问日志。官方 Docker Compose 和 Helm 配置使用以下默认输出位置。

日志类型	说明	默认输出位置
错误日志	组件事件、警告和错误，包括配置处理、数据库访问和配置同步问题。	stderr
访问日志	HTTP 请求摘要，包括请求路径、处理结果、耗时和来源。	stdout

在官方 Docker Compose 和 Helm 配置中，这三个组件将错误日志直接写入标准错误（stderr），将访问日志直接写入标准输出（stdout）。这两个目标都是进程输出流，组件写入时不经过文件路径或符号链接。默认容器部署没有可供 tail 读取的普通访问日志或错误日志文件，请从容器输出采集这两路日志。

从 3.10.2 起，RPM 部署中控制台默认将错误日志和访问日志分别写入 /var/log/api7/dashboard.log 和 /var/log/api7/dashboard-access.log，DP Manager 则分别写入 /var/log/api7/dp-manager.log 和 /var/log/api7/dp-manager-access.log。两个组件的默认应用日志级别均为 warn。

两个输出位置均可调整，参见配置控制面日志。

可通过容器运行时查看日志。例如，使用 Docker 时运行以下命令。

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

访问日志会跳过对 /healthz 的请求。

访问日志包含请求路径和查询字符串。3.10.0 至 3.10.8 会原样记录所有查询参数值，包括 key_value 中的凭据。从 3.10.9 起，该值以 key_value=*** 记录。其他查询参数值仍会原样记录，请避免在查询字符串中传递敏感数据。

可选组件 File Server 和 API Usage 也会生成错误日志和访问日志。在 Helm 部署中，File Server 的默认应用日志级别为 warn。在 Docker Compose 部署中，API Usage 的默认应用日志级别为 debug。两个组件都将应用日志写入 stderr，将访问日志写入 stdout。下文的配置示例适用于控制台、DP Manager 和开发者门户。

控制面日志内容

• 应用日志。组件主日志记录器输出的日志包括时间戳、级别、代码位置、消息和事件相关字段。处理请求时生成的日志可包含 request_id，可用它关联同一请求的访问日志。
• 访问日志。每条记录以 [HTTP] 开头，包含时间戳、请求 ID、请求方法、请求路径和查询字符串、状态码、耗时、客户端 IP、User-Agent、用户 ID、请求体和响应体长度，以及请求处理过程中附加的错误信息。缺少请求 ID 或用户 ID 时显示 -。路径、User-Agent 和错误信息可能含有空格，请勿按空格拆分日志条目。访问日志记录请求体和响应体的长度，不保存完整的请求体或响应体。

受审计覆盖的管理变更会单独记录在审计日志中，可在控制台查看。审计范围和敏感数据的处理方式见该文档。

配置数据面日志

数据面日志配置控制输出位置、错误日志的详细程度和访问日志格式。

设置日志输出位置和错误日志级别

在网关的 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 或 json

上例展示的是默认目标。相对路径以网关安装前缀为基准解析。若要在官方容器镜像中写入普通文件，请选择 /usr/local/apisix/logs/ 以外的路径，例如 /var/log/apisix/access.log 和 /var/log/apisix/error.log；启动网关前需要先创建该目录、授予网关进程写权限，并在该路径挂载卷。

修改后请重新加载或重启网关。

使用 JSON 访问日志格式

为了便于日志采集器解析，可以使用 JSON 格式并将转义方式设为 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

如需在每行访问日志中包含消费者标签，请参阅在访问日志中包含消费者标签。

配置控制面日志

控制台、DP Manager 和开发者门户各自使用独立配置，log 配置项相同。请分别更新需要调整的组件。

修改配置文件

在相应组件的配置文件中修改 log 配置块，保留其他配置。

部署方式	组件	配置文件
官方控制面 Docker Compose 包	控制台	dashboard_conf/conf.yaml
官方控制面 Docker Compose 包	DP Manager	dp_manager_conf/conf.yaml
官方控制面 Docker Compose 包	开发者门户 API	developer_portal_conf/conf.yaml
独立开发者门户 Docker Compose	开发者门户 API	backend_conf/conf.yaml
RPM（3.10.2 及以上）	控制台	/usr/local/api7/dashboard/conf/dashboard.yaml
RPM（3.10.2 及以上）	DP Manager	/usr/local/api7/dp-manager/conf/dp-manager.yaml

以下示例采用这三个组件在官方 Docker Compose 和 Helm 配置中的默认日志设置。

log:
  level: warn
  output: stderr
  access_log: stdout

配置项	说明
log.level	应用日志的最低输出级别。可选值为 debug、info、warn、error、panic 和 fatal。设为 warn 时记录警告、错误和更严重的事件。
log.output	应用日志的输出位置，可设为 stderr、stdout 或文件路径。
log.access_log	访问日志的输出位置，可设为 stdout、stderr 或文件路径。

访问日志没有独立的日志级别，也不受 log.level 过滤。将 log.access_log 设为空字符串时，访问日志仍会写入 stdout。调整 log.level 不会关闭访问日志，也不会增加访问日志的字段。

输出到文件时，请提前创建上级目录，并为运行用户授予写权限。组件会向文件追加日志。在容器部署中，请为该目录挂载持久化存储，并配置日志采集、轮转和保留策略。

log.output 为 stdout 或 stderr 时，应用日志使用带颜色的控制台格式，可能包含 ANSI 颜色控制码。输出到文件时，应用日志采用 JSON 格式，数据库（GORM）和 etcd 兼容层（kine）日志仍以纯文本写入同一文件。请让日志采集器分别处理这些格式。

修改配置后，重启对应组件。

通过 Helm 配置日志

在 api7/api7ee3 控制面 Chart 的现有 values 文件中，按需更新 dashboard_configuration.log、dp_manager_configuration.log 和 developer_portal_configuration.log，并保留其他配置。以下示例为三个组件将错误日志级别设为 warn，将错误日志写入 stderr，将访问日志写入 stdout。

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

使用当前安装的 Chart 版本和包含完整现有配置的 values 文件更新部署。

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

Chart 会在组件配置变化时触发对应 Pod 的滚动更新。更新完成后，检查新 Pod 的日志。更多部署配置说明见在 Kubernetes 上部署 API7 企业版。

将日志转发到集中式系统

有两种互补方式：

• 采集容器输出或转发日志文件。此方式适用于数据面和控制面。容器部署中，除非显式配置了普通日志文件，否则请采集标准输出和标准错误。使用文件输出时，可通过 Fluentd、Vector、Filebeat 或 Logstash 等日志转发器持续读取所配置的文件，例如数据面的 /var/log/apisix/access.log 和 /var/log/apisix/error.log。此方式适用于任意后端，日志转发独立于请求处理。
• 从路由直接发送数据面请求日志。网关日志插件可以通过网络直接发送结构化请求日志，无需先写入磁盘。这些插件仅转发数据面请求日志。可用插件包括 http-logger、kafka-logger、syslog、splunk-hec-logging、google-cloud-logging、elasticsearch-logger、rocketmq-logger 和 clickhouse-logger。完整的 Splunk HEC 流程见将访问日志发送到 Splunk。

如需在 Kubernetes 上采集数据面日志，请参阅在 Kubernetes 上采集网关日志，选择采集容器输出或 Pod 内文件，并配置 OpenTelemetry Collector 或 Filebeat。如需使用 Splunk 采集网关错误日志，请参阅将 Kubernetes 错误日志发送到 Splunk。

后续步骤

• 在访问日志中包含消费者标签：在每行访问日志中包含消费者级元数据。
• 在 Kubernetes 上采集网关日志：使用 OpenTelemetry Collector 或 Filebeat 采集容器输出或 Pod 内的文件。
• 将访问日志发送到 Splunk：通过 HTTP 将日志传输到 Splunk。
• 将 Kubernetes 错误日志发送到 Splunk：使用 Splunk OpenTelemetry Collector 收集 Kubernetes 网关错误日志。
• 配置告警：在错误率超过阈值时接收通知。
• 审计日志：跟踪通过控制台或 Admin API 进行的配置更改。