一、背景信息
Logback 是 Apache 的一个开源项目。通过使用 Logback，你可以控制日志信息输送的目的地是控制台、文件、GUI 组件，甚至是套接口服务器、NT 的事件记录器、UNIX Syslog 守护进程等。此外，你还可以通过一个 logback 配置文件来灵活地进行配置，而不需要修改应用的代码。
二、功能优势
·日志不落盘：产生数据通过网络发给服务端。
·无需改造：对已使用 Logback 应用，只需简单配置即可采集。
·异步非阻塞：高并发设计，后台异步发送，适合高并发写入。
·资源可控制：可以通过参数控制 producer 用于缓存待发送数据的内存大小，同时还可以配置用于执行数据发送任务的线程数量。
·自动重试： 对可重试的异常，支持配置重试次数。
·优雅关闭： 退出前会将日志全量进行发送。
·感知日志上报结果："运行过程中产生的异常通过 AddError 输出"。
三、maven 工程中引入依赖
<dependency> <groupId>com.tencentcloudapi.cls</groupId> <artifactId>tencentcloud-cls-logback-appender</artifactId> <version>1.0.8</version></dependency>
四、修改 logback 配置文件
<appender name="LoghubAppender" class="com.tencentcloudapi.cls.LoghubAppender"> <!–必选项–> <!–域名配置– 详见https://cloud.tencent.com/document/product/614/18940#.E5.9F.9F.E5.90.8D> <endpoint>${region}.cls.tencentcs.com</endpoint> <!–密钥信息– 前往https://console.cloud.tencent.com/cam/capi获取> <!–请确保密钥关联的账号具有相应的SDK日志上传权限– 查看权限策略前往https://cloud.tencent.com/document/product/614/68374#.E4.BD.BF.E7.94.A8-api-.E4.B8.8A.E4.BC.A0.E6.95.B0.E6.8D.AE > <accessKeyId>${SecretID}</accessKeyId> <accessKeySecret>${SecretKey}</accessKeySecret> <!–日志主题ID–> <topicId>${topicId}</topicId> <!– 可选项 详见 '参数说明'–> <totalSizeInBytes>104857600</totalSizeInBytes> <maxBlockMs>0</maxBlockMs> <sendThreadCount>8</sendThreadCount> <batchSizeThresholdInBytes>524288</batchSizeThresholdInBytes> <batchCountThreshold>4096</batchCountThreshold> <lingerMs>2000</lingerMs> <retries>10</retries> <maxReservedAttempts>11</maxReservedAttempts> <baseRetryBackoffMs>100</baseRetryBackoffMs> <maxRetryBackoffMs>50000</maxRetryBackoffMs> <includeMessage>false</includeMessage> <!– 可选项 设置时间格式 –> <timeFormat>yyyy-MM-dd'T'HH:mm:ssZ</timeFormat> <timeZone>Asia/Shanghai</timeZone> <customFields>{"${自定义key}":"${自定义value}"}</customFields> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger – %msg</pattern> </encoder> <mdcFields>${MDC字段}</mdcFields> </appender>
五、参数说明
| 参数 | 描述 | 示例 |
| totalSizeInBytes | 单个 producer 实例能缓存的日志大小上限，默认为100MB | totalSizeInBytes=104857600 |
| maxBlockMs | 如果 producer 可用空间不足，调用者在 send 方法上的最大阻塞时间，默认为60秒。为了不阻塞打印日志的线程，强烈建议将该值设置成0 | maxBlockMs=0 |
| sendThreadCount | 执行日志发送任务的线程池大小，默认为可用处理器个数 | sendThreadCount=8 |
| batchSizeThresholdInBytes | 当一个 ProducerBatch 中缓存的日志大小大于等于 batchSizeThresholdInBytes 时，该 batch 将被发送，默认为512 KB，最大可设置成5MB | batchSizeThresholdInBytes=524288 |
| batchCountThreshold | 当一个 ProducerBatch 中缓存的日志条数大于等于 batchCountThreshold 时，该 batch 将被发送，默认为4096，最大可设置成40960 | batchCountThreshold=4096 |
| lingerMs | 一个 ProducerBatch 从创建到可发送的逗留时间，默认为2秒，最小可设置成100毫秒 | lingerMs=2000 |
| retries | 如果某个 ProducerBatch 首次发送失败，能够对其重试的次数，默认为10次如果 retries 小于等于0，该 ProducerBatch 首次发送失败后将直接进入失败队列 | retries=10 |
| maxReservedAttempts | 该参数越大能让你追溯更多的信息，但同时也会消耗更多的内存 | maxReservedAttempts=11 |
| baseRetryBackoffMs | 首次重试的退避时间，默认为100毫秒。Producer 采用指数退避算法，第 N 次重试的计划等待时间为 baseRetryBackoffMs * 2^(N-1) | baseRetryBackoffMs=100 |
| maxRetryBackoffMs | 重试的最大退避时间，默认为50秒 | maxRetryBackoffMs=50000 |
| timeFormat | 设置时间格式 | 精确到秒：yyyy-MM-dd'T'HH:mm:ssZ精确到毫秒：yyyy-MM-dd'T'HH:mm:ss.SSSZ注意：仅 Logback 版本为1.0.4及以上支持毫秒时间。 |
| mdcFields | 指定要在 Appender 中包含的 MDC（Mapped Diagnostic Context）字段。这些字段将作为日志的一部分上传至 CLS。 | – |
| customFields | 定义自定义字段，这些字段将作为日志的一部分上传至 CLS | {"app":"my_application"} |
| includeMessage | 当 encoder 不为空时，是否要包含 message 字段，默认为 true | true |