操作场景
本文介绍如何通过 CLS Log 插件，将包含详细请求、响应 Body 报文的日志上报到 CLS Topic 中。
注意：
目前云原生 API 网关已经支持 Access Log 投递到 CLS，并且支持修改 Access Log 的日志格式，可以先评估投递到 CLS 的功能是否满足需求，详细可阅读日志投递至 CLS。再考虑是否用插件方式上报日志到 CLS，使用插件上报到 CLS，可以定制自己的日志上报格式和上报更多的字段。
前置条件
1. 已购买 Kong 网关实例，操作文档。
2. 进入 TSE 控制台，并找到需要的实例。
3. 进入实例详情页后，找到插件管理 > 自定义插件。
操作步骤
1. 下载 CLS Log 插件安装包 cls_log.zip。
2. 参考 插件管理，在网关实例插件配置中，上传安装 CLS Log 插件，并启用。
3. 登录 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 日志长度（单位字节），超出会被截断 |
bacth_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 插件包含通用的基本日志字段，如需自定义日志字段，可以基于该插件二次开发。
