API 网关基于火山引擎的 [日志服务 TLS](https://www.volcengine.com/docs/6470/73638)，为您提供持久化存储的用户访问日志，便于业务观测客户端、网关、后端服务的行为，满足排障、审计等需求。本文为您介绍如何投递、查询网关日志，以及日志的投递字段。 ## 开启日志投递 API 网关支持将日志投递至日志服务 TLS，以达到持久化存储的目的。 :::warning 2023年12月15日00:00:00 前创建的网关实例不支持自助开启日志投递。如有投递日志需求，请 [提交工单](https://console.volcengine.com/workorder/create?step=3&SubProductID=P00000170&FlowKey=DhvSFwiOSXyEVSlGZJXx) 申请。 ::: ### 前提条件 * 已开通火山引擎日志服务 TLS。使用日志服务会产生费用，详情请参见 [产品计费](https://www.volcengine.com/docs/6470/111805)。 * 已在 TLS 侧创建日志项目，详情请参见 [创建日志项目](https://www.volcengine.com/docs/6470/72005#%E5%88%9B%E5%BB%BA%E6%97%A5%E5%BF%97%E9%A1%B9%E7%9B%AE)。 :::tip API 网关支持自动创建日志主题，也可以使用您自己的日志主题。详情请参见 [创建日志主题](https://www.volcengine.com/docs/6470/72004#%E5%88%9B%E5%BB%BA%E6%97%A5%E5%BF%97%E4%B8%BB%E9%A2%98)。 ::: ### 创建网关实例时配置创建实例时，在 **可观测性** 区域，勾选 **使用日志服务**，将网关的访问日志投递至 TLS。具体操作请参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。 ### 存量网关实例配置 1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)，在顶部导航栏，选择目标地域。 2. 在左侧导航栏选择 **实例管理**，单击目标实例名称，进入实例概览页面。 3. 切换至日志信息页签，单击 **去选择**，选择希望投递的日志项目和日志主题。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0e67bff173ec86f3ea9e1d43af9d8a54.png =922x) |配置项 |说明 | |---|---| |日志项目 |日志项目是日志服务中基础的资源管理单位，用于多用户或多项目、产品之间的日志资源隔离与访问控制。请选择目标日志项目。 | |日志主题 |日志主题是日志服务进行日志管理的基本单位，每个日志主题用于承载同一应用中不同类型或不同分类的日志。|\ | ||\ | |* **默认配置**：选择默认配置，网关将在当前项目下自动生成名称为`网关 id-accessLog`的主题。|\ | |* **使用已有主题**：选择使用已创建的主题。 | 4. 单击 **确定**，完成日志投递配置。 ## 编辑日志配置通过编辑日志配置，可关闭日志投递，或切换使用的日志项目和日志主题。 :::warning 请慎重切换投递的日志项目和日志主题！切换后，将无法在 API 网关侧查询投递至原项目和主题的历史日志。 ::: 1. 在当前网关的日志信息页签，单击日志配置的修改图标。 2. 在弹出的对话框中，根据需要修改开启状态、日志项目、日志主题。 3. 单击 **确定**，完成修改。 ## 查询日志在当前网关实例的日志信息页签，选择目标时间范围，单击 **搜索**，查询日志结果。 :::tip * 日志搜索框默认携带网关 id，方便您查看目标实例的访问日志。 * 关于查询日志的更多高级功能介绍，请参见日志服务 TLS 的 [检索日志](https://www.volcengine.com/docs/6470/107373)。 ::: ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_fc1ab2fabbca72f39635b4d1a198362c.png =979x) ## 日志字段说明网关日志投递涉及到的字段说明如下： |字段名 |字段类型 |字段说明 | |---|---|---| |__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。 | |response_code |long |HTTP 响应的状态码。 | |response_flags |string |响应失败的原因。 | |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。 |