一、操作场景
注意：目前云原生网关已经支持 Access Log 投递到 CLS，并且支持修改 Access Log 的日志格式，可以先评估投递到 CLS 的功能是否满足需求，详细可阅读 日志投递至 CLS。再考虑是否用插件方式上报日志到 CLS，使用插件上报到 CLS，可以定制自己的日志上报格式和上报更多的字段。
二、前置条件
1. 已创建云原生网关实例，具体操作请参见 新建云原生网关。
2. 进入 TSF 控制台，在云原生智能网关页面，找到需要的实例。
3. 进入实例详情页后，找到插件管理 > 自定义插件。
三、操作步骤
1. 下载 CLS Log 插件安装包 cls_log.zip。
2. 参考 插件管理，在网关实例插件配置中，上传安装 CLS Log 插件后，点击使用此版本启动插件。
3. 登录 Konga 控制台，切换页面到基本信息 > konga 控制台，开启公网访问地址，获取账号和密码后，进入 konga 管理控制台，在 PLUGINS 菜单中添加 CLS Log 插件全局开启，参数配置请参见下文中插件参数部分。
4. 通过网关 IP 发起请求，在 CLS 控制台确认日志正确上报到对应的 CLS Topic 中，日志示例如下：
{ "tries":"[{\\"balancer_latency\\":0,\\"port\\":80,\\"balancer_start\\":1654569xxxxxx,\\"ip\\":\\"172.0.0.2\\"}]", "upstream_uri":"/10k", "querystring":"{}", "req_url":"http://172.0.0.3/test", "latency_kong":"1", "req_method":"GET", "resp_headers":"{\\"x-kong-upstream-latency\\":\\"2\\",\\"date\\":\\"Tue, 07 Jun 2022 02:34:15 GMT\\"}", "req_uri":"/test", "resp_status":"200", "request_time":"3", "req_body":"", "resp_body":"some response body", "latency_proxy":"2", "req_headers":"{\\"host\\":\\"172.16.0.37\\"}", "started_at":"1654569xxxxxx", "client_ip":"127.0.0.1", "upstream_response_time":"2", "resp_size":"10476", "route_id":"cca80823-3189-47fb-8a1f-21ebe7xxxxxx", "route_name": "", "service_id":"17caaef5-dc84-4c93-8148-e63ce1xxxxxx", "service_name": "", "consumer_id":"", "consumer_name": ""}
四、插件参数介绍
| 参数 | 是否必填 | 默认值 | 描述 |
| cls_host | 是 | – | CLS API Host，根据需要选择域名地址，例如：ap-beijing.cls.tencentyun.com。详情请参见 CLS doc |
| cls_topic | 是 | – | 日志上报的目标 CLS Topic |
| secret_id | 是 | – | 腾讯云账户 SecretID |
| secret_key | 是 | – | 腾讯云账户 SecretKey |
| log_req_body | 是 | false | 是否记录请求 Body 日志字段，开启后对网关性能有一定影响 |
| log_resp_body | 是 | false | 是否记录响应 Body 日志字段，开启后对网关性能有一定影响 |
| max_req_body_size | 是 | 10240 | 最大请求 Body 日志长度（单位字节），超出会被截断 |
| max_resp_body_size | 是 | 10240 | 最大响应 Body 日志长度（单位字节），超出会被截断 |
| batch_size | 是 | 100 | 单次上报日志数量，一批日志大小不建议超过 8 MB。 |
| retry_count | 是 | 3 | 最大重试次数。 |
| mode | 否 | memory | memory: 通过 CLS SDK 从内存队列中异步上报日志。access_log: 通过 access_log 模块，配合 loglistener 采集上报，受磁盘性能影响，如需使用请工单联系开通。 |
| fallback_to_access_log | 否 | false | 当使用 memory 模式时，上报队列堆积时是否降级到 access_log 上报模式, 如需使用请工单联系开通。 |
五、注意事项
1. CLS Log 插件中配置的密钥对需拥有 cls:UploadLog 策略权限，详情请参见 CLS 自定义策略示例 中使用 API 上传数据部分。
2. 开启 CLS Log 日志插件会对网关性能有少量影响，影响程度和报文日志大小成正比。
3. CLS Log 插件中实现了缓冲队列、分批上报，失败重试等功能，能够在偶发性上报失败时进行重试，但由于缓冲队列大小有限，长时间上报链路故障时仍然有丢失日志的风险。
4. CLS Log 插件包含通用的基本日志字段，如需自定义日志字段，可以基于该插件二次开发。