云日志服务LogBack SDK

云日志服务Java SDK提供了与logback适配的扩展插件，可以直接在logback中配置华为云appender，将通过logback产生的日志直接上报至云日志服务。

传输协议

HTTPS

使用前提

参考注册华为账号并开通华为云中操作，完成注册。
确认云日志服务的区域，请用户根据所在区域，选择RegionName。
如何获取访问密钥AK/SK。
获取华为云账号的项目ID（project id），详细步骤请参见API凭证。
获取需要上报到LTS的日志组ID和日志流ID。
已安装Java开发环境。云日志服务Java SDK支持JDK1.8及以上，您可以执行java –version命令检查您已安装的Java版本。如未安装，可以从Java官方网站下载安装包进行安装。
SDK支持跨云/本地上报日志，当前仅支持华北-北京四、华东-上海一、华南-广州、西南-贵阳一。
支持将logback.xml变为logback-spring.xml（SpringBoot），且读取springProfile中的配置。
支持读取logback.xml、logback-spring.xml中的自定义标签。
通过LogBack SDK上报日志到LTS的时间相距当前时间不超过2天，否则上报日志会被LTS删除。
建议设置上报周期小于1分钟（例如50秒）上报一次，设置1分钟或超过1分钟上报一次，可能会出现连接失败，因为SDK连接默认1分钟超时。

安装SDK

在Maven项目中加入依赖项。

使用Maven构建项目时，settings.xml文件的mirrors节点需要增加华为外部开源仓。如下：

<mirror>
    <id>huaweicloud</id>
    <mirrorOf>*</mirrorOf>
    <url>https://repo.huaweicloud.com/repository/maven/</url>
</mirror>

您可以在华为外部开源仓中获取云日志服务LogBack SDK依赖的最新版本。

在Maven工程中使用云日志服务LogBack SDK，只需在pom.xml中加入相应依赖即可，Maven项目管理工具会自动下载相关JAR包。在<dependencies>中加入如下内容：

推荐使用最新版本version：1.1.3，第2步中查看SDK版本。

<dependency> 
     <groupId>io.github.huaweicloud</groupId> 
     <artifactId>lts-sdk-common</artifactId> 
     <version>version</version> 
<exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
        </exclusion>
    </exclusions>
 </dependency> 
 <dependency> 
     <groupId>io.github.huaweicloud</groupId> 
     <artifactId>lts-sdk-logback</artifactId> 
     <version>version</version> 
 </dependency>

示例代码

编写logback.xml、logback-spring.xml中LogbackSDKAppender，示例如下：

<configuration scan="true" debug="false"> 
   <appender name="LogInfoTest" class="com.huaweicloud.lts.appender.LogbackSDKAppender"> 
     <!--  华为云账号的项目ID（project id）  --> 
     <projectId>xxxxxxxxxxxxxxxxxxxxxx</projectId> 
     <!--  华为云日志服务日志组ID  --> 
     <logGroupId>xxxxxxxxxxxxxxxxxxxxxx</logGroupId> 
     <!--  华为云日志服务日志流ID  --> 
     <logStreamId>xxxxxxxxxxxxxxxxxxxxxx</logStreamId> 
     <!--  华为云账号的AK, 认证用的AK硬编码到代码中或者明文存储都有很大的安全风险, 建议密文存放, 使用时解密, 确保安全  --> 
     <accessKeyId>xxxxxxxxxxxxxxxxxxxxxx</accessKeyId> 
     <!--  华为云账号的SK, 认证用的SK硬编码到代码中或者明文存储都有很大的安全风险, 建议密文存放, 使用时解密, 确保安全  --> 
     <accessKeySecret>xxxxxxxxxxxxxxxxxxxxxx</accessKeySecret> 
     <!--  云日志服务的区域  --> 
     <regionName>cn-nxxxxx</regionName> 
     <encoder> 
       <pattern>%d %-5level [%thread] [%customerParam] %logger{0}: %msg</pattern> 
     </encoder> 
     <!--  单个Appender能缓存的日志大小上限  --> 
     <totalSizeInBytes>104857600</totalSizeInBytes> 
     <!--  producer发送日志时阻塞时间  --> 
     <maxBlockMs>0</maxBlockMs> 
     <!--  执行日志发送任务的线程池大小  --> 
     <ioThreadCount>8</ioThreadCount> 
     <!--  producer发送单批日志量上限  --> 
     <batchSizeThresholdInBytes>524288</batchSizeThresholdInBytes> 
     <!--  producer发送单批日志条数上限  --> 
     <batchCountThreshold>4096</batchCountThreshold> 
     <!--  producer发送单批日志等待时间  --> 
     <lingerMs>2000</lingerMs> 
     <!--  producer发送日志失败后重试次数  --> 
     <retries>5</retries> 
     <!--  首次重试的退避时间  --> 
     <baseRetryBackoffMs>500</baseRetryBackoffMs> 
     <!--  重试的最大退避时间  --> 
     <maxRetryBackoffMs>500</maxRetryBackoffMs> 
     <!-- 默认false, true: 可以跨云上报日志, false: 仅能在华为云ecs主机上报日志 -->
     <enableLocalTest>false</enableLocalTest>
     <!-- 超过1M的日志, 拆分后放弃1M以外的 -->         
     <!-- <giveUpExtraLongSingleLog>true</giveUpExtraLongSingleLog>--> 
     <!-- 是否使用日志组/日志流名称上报日志-->  
     <!-- <logGroupStreamByName>false</logGroupStreamByName>-->
   </appender> 
   <logger name="com.huawei.test.logback.info" level="INFO"> 
     <appender-ref ref="LogInfoTest"/> 
   </logger> 
 </configuration>

编写代码中产生日志，示例如下：

package com.huawei.test.logback.info; 
  
 import org.slf4j.Logger; 
 import org.slf4j.LoggerFactory; 
  
 public class TestLogBackAppenderInfo { 
  
     private static final Logger LOGGER = LoggerFactory.getLogger(TestLogBackAppenderInfo.class); 
  
     public void run() throws InterruptedException { 
         LOGGER.info("test~logback~~~info"); 
     } 
  
 }

producer性能基线

上报日志时，请参考如下参数的测试性能基线，若超出基线值，可能会导致日志上报异常。

ECS虚拟机配置：

实例规格：通用计算增强型 c7.xlarge.2
CPU：4 vCPU
内存：8 GB
基准带宽：100 Mbit/s
OS：Huawei Cloud EulerOS release 2.0
JVM：OpenJDK 64-Bit Server VM (build 17.0.7+7, mixed mode)

测试程序说明（单个producer）：

totalSizeInBytes: 104857600
maxBlockMs：0
batchSizeThresholdInBytes: 1048576
batchCountThreshold：40960
lingerMs：2000
ioThreadCount：具体用例中调整

JVM 初始堆/最大堆大小：1GB
发送日志总条数：100,000,000
发送日志总大小：约50GB

按照参数基线值设置后，使用华为云ECS机器作为日志上报环境，通过华为云内网服务入口进行上报。

SDK上报性能基线测试结果参考：

上报日志：测试中使用的单条日志大小约为550字节。为了模拟数据的随机性，测试使用的数据为随机字符串。

性能基线如下：

表1 性能基线
IO 线程数量	数据吞吐量	数据吞吐速率	CPU 使用率
2	8.4MB/S	1.7W条/s	15%
4	15.3MB/S	3W条/s	29%
6	21.5MB/S	4.2W条/s	36%

总结如下：

CPU时间主要花费在对象的序列化和压缩上，在吞吐量较高的情况下CPU使用率比较高。但在日常环境中，单机数据流量均值为100KB/S，因此造成的CPU消耗几乎可以忽略不计。
增加IO线程数量可以显著提高吞吐量，尤其是当IO线程数量少于可用处理器个数时。
调整totalSizeInBytes对吞吐量影响不够显著，增加totalSizeInBytes会造成更多的CPU消耗，建议使用默认值。
当日志上报量超过单个producer时：
1. 建议拆分日志流，使用多个producer上报日志，分摊流量，以保障SDK处于正常上报状态。
2. 如果maxBlockMs为0时，SDK处于非阻塞状态，会触发保护机制自动降级，可能会对部分日志做丢弃处理。
3. 如果maxBlockMs大于0时，SDK处于阻塞状态，阻塞时间为maxBlockMs，可能会造成SDK发送日志处于阻塞状态。

配置参数说明

Appender配置参数说明。

表2 Appender配置参数说明表
参数名称	描述	类型	是否需要填写	默认值
projectId	华为云账号的项目ID（project id）。	String	必填	-
accessKeyId	华为云账号的AK。认证用的AK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。	String	必填	-
accessKeySecret	华为云账号的SK。认证用的SK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。	String	必填	-
regionName	云日志服务的区域。	String	必填	-
logGroupId	LTS的日志组ID。	String	必填	-
logStreamId	LTS的日志流ID。	String	必填	-
appName	日志标签appName字段。	String	选填	-
pathFile	日志标签pathFile字段。	String	选填	-
totalSizeInBytes	单个producer实例能缓存的日志大小上限。	int	选填	104857600（即100MB）
maxBlockMs	如果producer可用空间不足，调用者在send方法上的最大阻塞时间，单位为毫秒。默认60000毫秒，建议0毫秒。当maxBlockMs值>=0时，则阻塞到设置的时间，如果到达阻塞时间，还是不能获取到内存，即报错且丢弃日志。当maxBlockMs值=-1时，则一直阻塞到发送成功，且不会丢弃日志。	long	选填	60000毫秒
ioThreadCount	执行日志发送任务的线程池大小。	int	选填	客户机器空闲CPU数量，但一定大于1
batchSizeThresholdInBytes	当一个ProducerBatch中缓存的日志大小大于等于batchSizeThresholdInBytes 时，该ProducerBatch缓存的日志将被发送到LTS。	int	选填	524288（即0.5MB）
batchCountThreshold	当一个ProducerBatch中缓存的日志条数大于等于batchCountThreshold时，该 ProducerBatch缓存的日志将被发送到LTS。	int	选填	4096
lingerMs	一个ProducerBatch从创建到可发送的逗留时间。	int	选填	2s
retries	如果某个ProducerBatch首次发送失败，能够对其重试的次数，建议为5次。如果 retries小于等于0，该ProducerBatch首次发送失败后将直接进入失败队列。	int	选填	10
baseRetryBackoffMs	首次重试的退避时间。	long	选填	0.1s
maxRetryBackoffMs	重试的最大退避时间。	long	选填	50s
giveUpExtraLongSingleLog	超过1M的日志, 拆分后丢弃大于1M的数据。	boolean	选填	false
enableLocalTest	是否开启跨云上报日志。（此功能仅适用于开发调测，对于上报性能不做保障）选true时，开启跨云后用户能通过公网（仅支持华北-北京四、华东-上海一、华南-广州、西南-贵阳一）访问。选false时，关闭跨云后用户是通过华为云当前区域主机访问。	boolean	选填	false
logGroupStreamByName	是否使用日志组/日志流名称上报日志（SDK版本最低必须为1.1.0支持此功能）。如果为true，表明使用名称上报，则logGroupId、logStreamId参数值分别填入日志组、日志流名称即可。	boolean	选填	false
proxyIp	使用自定义ip端口上报日志。	String	选填	-

如果是SpringBoot项目，则可以将logback.xml替换为logback-spring.xml，且支持读取springProfile中的配置，可以自由切换开发、测试等环境的日志采集环境。
使用说明如下：
1. 在SpringBoot项目中的application.properties可以自由指定使用的配置项。
2. logback-spring.xml中配置
```
    <springProfile name="dev">
        <root level="INFO">
            <appender-ref ref="customerAppender"/>
        </root>
    </springProfile>
```

如果需要logback.xml、logback-spring.xml支持自定义标签，且将标签中的value打印到日志中。执行以下步骤：

需要继承ClassicConverter类，重写convert方法，返回值为自定义标签的value。

public class CustomerParam extends ClassicConverter {
    @Override
    public String convert(ILoggingEvent iLoggingEvent) {
        return "自定义标签value";
    }
}

在logback.xml或者logback-spring.xml中引用ClassicConverter类，使用%自定义标签的名称，然后就可以使用该标签了。

<conversionRule conversionWord="customerParam" converterClass="com.huawei.test.logback.CustomerParam"/>
 
    <appender name="customer" class="com.huawei.appender.LogbackSDKAppender">
        <encoder>
            <pattern>%d %-5level [%thread] [%customerParam] %logger{0}: %msg</pattern>
        </encoder>
    </appender>

参数获取方法

区域表

表3 区域表
区域名称	区域
华北-北京二	cn-north-2
华北-北京四	cn-north-4
华北-北京一	cn-north-1
华东-上海二	cn-east-2
华东-上海一	cn-east-3
华南-广州	cn-south-1
华南-深圳	cn-south-2
西南-贵阳一	cn-southwest-2
亚太-新加坡	ap-southeast-3