文档中心

API 网关

监控与告警

日志管理

API 网关基于火山引擎的日志服务 TLS，为您提供持久化存储的用户访问日志，便于业务观测客户端、网关、后端服务的行为，满足排障、审计等需求。本文为您介绍如何投递、查询网关日志，以及日志的投递字段。

开启日志投递

API 网关支持将日志投递至日志服务 TLS，以达到持久化存储的目的。

前提条件

已开通火山引擎日志服务 TLS。使用日志服务会产生费用，详情请参见产品计费。

已在 TLS 侧创建日志项目，详情请参见创建日志项目。

已创建网关实例，并升级至 v1.0.0 及以上版本，详情请参见版本管理。

说明

API 网关支持自动创建日志主题，也可以使用您自己的日志主题。详情请参见创建日志主题。

创建网关实例时配置

创建实例时，在可观测性区域，勾选使用日志服务，将网关的访问日志投递至 TLS。具体操作请参见创建实例。

存量网关实例配置

在左侧导航栏选择实例管理，单击目标实例名称，进入实例概览页面。

切换至日志信息页签，单击去选择，选择希望投递的日志项目和日志主题。

配置项	说明
日志项目	日志项目是日志服务中基础的资源管理单位，用于多用户或多项目、产品之间的日志资源隔离与访问控制。请选择目标日志项目。
日志主题	日志主题是日志服务进行日志管理的基本单位，每个日志主题用于承载同一应用中不同类型或不同分类的日志。默认配置：选择默认配置，网关将在当前项目下自动生成名称为网关 id-accessLog的主题。使用已有主题：选择使用已创建的主题。

单击确定，完成日志投递配置。

编辑日志配置

通过编辑日志配置，可关闭日志投递，或切换使用的日志项目和日志主题。

注意

请慎重切换投递的日志项目和日志主题！切换后，将无法在 API 网关侧查询投递至原项目和主题的历史日志。

在当前网关的日志信息页签，单击日志配置的修改图标。

在弹出的对话框中，根据需要修改开启状态、日志项目、日志主题。

单击确定，完成修改。

编辑日志规则

日志规则用于定义访问日志中每一个自定义字段的采集来源与字段名称。编辑日志规则后，网关会按新规则将请求头、响应头、请求 Body、响应 Body 等内容作为独立字段投递至日志服务 TLS，便于业务排障、审计与模型输出追溯。

在当前网关的日志信息页签，单击编辑日志规则。

在编辑日志规则界面，单击添加，配置日志采集规则。

配置项	说明
取值位置	指定字段值的来源类型。支持请求头、请求 Body、响应头、响应 Body、自定义变量类型。说明开启 Body 日志记录可能会将请求或响应中的敏感数据写入日志，生产环境请谨慎开启。请确认已获得业务授权，并按最小必要原则配置需要记录的字段。 Body 体量会影响存储的日志量，使用日志服务会产生费用，请确认后开启。
字段值	字段值的取值表达式，需与所选取值位置一致：取值位置为请求头 / 响应头时，输入 Header 名称，例如 x-request-id。取值位置为请求 Body / 响应 Body 时，输入 request_body 或 response_body。取值位置为自定义变量时，输入网关支持的变量名。
字段别名	字段在日志服务中展示的字段名。

单击确定，完成配置。

查询日志

在当前网关实例的日志信息页签，选择目标时间范围，单击搜索，查询日志结果。

说明

日志搜索框默认携带网关 id，方便您查看目标实例的访问日志。

关于查询日志的更多高级功能介绍，请参见日志服务 TLS 的检索日志。

日志字段说明

网关日志投递涉及到的字段说明如下：

字段名	字段类型	字段说明
__time__	long	日志产生的时间。
gateway_id	string	网关实例 ID。
authority	string	请求报文中的 Host Header。
bytes_received	long	请求的 Body 大小（不包含 Header）。
bytes_sent	long	响应的 Body 大小（不包含 Header）。
downstream_local_address	string	网关 Pod 地址。
downstream_remote_address	string	连接到网关的 Client 端地址。
duration	long	请求整体耗时。单位为毫秒。
method	string	HTTP 方法。
path	string	HTTP 请求中的 Path。
protocol	string	HTTP 的协议版本。
request_id	string	网关会为每次请求产生一个 ID，并放在 Header 的 x-request-id 中，后端可以根据这个字段记录并进行排查。
requested_server_name	string	SSL 连接时使用的 Server Name。
request_duration	long	从开始处理请求，到完整收到请求内容的耗时。
request_tx_duration	long	从开始处理请求，到将完整请求发送给上游服务的耗时，包含请求接收和上游发送阶段。
response_code	long	HTTP 响应的状态码。
response_flags	string	响应失败的原因。
response_duration	long	从开始处理请求，到收到上游响应首字节的耗时，包含请求阶段及等待上游响应的时间。
response_tx_duration	long	从收到上游响应首字节，到将完整响应发送给客户端的耗时，不包含请求阶段。
route_name	string	路由名。
start_time	string	请求开始时间。格式：UTC。
trace_id	string	Trace ID。
upstream_cluster	string	上游集群。
upstream_host	string	上游 IP。
upstream_local_address	string	本地连接上游的地址。
upstream_service_time	long	上游服务处理请求的耗时（毫秒），包括网关访问上游服务的网络耗时和上游服务自身处理耗时两部分。
upstream_transport_failure_reason	string	上游链接失败的原因。
user_agent	string	HTTP Header 中的 UserAgent。
x_forwarded_for	string	HTTP Header中的 x-forwarded-for，通常用来表示 HTTP 请求端真实 IP。

最近更新时间：2026.10.29 15:29:42

这个页面对您有帮助吗？

有用

无用