云日志服务Java SDK（log4j2插件）

传输协议

HTTPS

使用前提

• 参考注册华为账号并开通华为云中操作，完成注册。
• 确认云日志服务的区域，请用户根据所在区域，选择RegionName。
• 获取华为账号的AK/SK。
• 获取华为云账号的项目ID（project id），详细步骤请参见“我的凭证 > API凭证”。
• 获取需要上报到LTS的日志组ID和日志流ID。
• 已安装Java开发环境。云日志服务Java SDK支持JDK1.8及以上，您可以执行java –version命令检查您已安装的Java版本。如未安装，可以从Java官方网站下载安装包进行安装。

使用说明

• 当用户修改权限后，权限信息在一天后生效。
• SDK支持跨云/本地上报日志，当前仅支持华北-北京四、华东-上海一、华南-广州、西南-贵阳一。使用详情见Appender配置参数说明表中的“enableLocalTest”参数，当该参数为true时，上报日志规格为单个机器200次/秒（即每秒只能发送200次，每次批量发送数量/大小详情见参数“batchSizeThresholdInBytes、batchCountThreshold、lingerMs”）。
• 通过SDK上报日志到LTS的时间相距当前时间不超过2天，否则上报日志会被LTS删除。

安装SDK

您可以通过以下两种方式安装云日志服务log4j2 SDK

方式一：在Maven项目中加入依赖项（推荐方式）。

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

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

2. 您可以在华为外部开源仓中获取云日志服务log4j2 SDK依赖的最新版本。
3. 在Maven工程中使用云日志服务log4j2 SDK，只需在pom.xml中加入相应依赖即可，Maven项目管理工具会自动下载相关JAR包。以1.0.1版本为例，在<dependencies>中加入如下内容：

   <dependency> 
        <groupId>io.github.huaweicloud</groupId> 
        <artifactId>lts-sdk-common</artifactId> 
        <version>1.0.1</version> 
    </dependency> 
    <dependency> 
        <groupId>io.github.huaweicloud</groupId> 
        <artifactId>lts-sdk-log4j2</artifactId> 
        <version>1.0.1</version> 
    </dependency>

方式二：在项目中直接依赖Log4j2 SDK的jar包。

1. 下载lts-sdk-common和lts-sdk-log4j2包。
2. 请确保您的项目中有以下依赖，因为SDK的jar包中需要该依赖。

   <dependency> 
        <groupId>com.alibaba</groupId> 
        <artifactId>fastjson</artifactId> 
        <version>1.2.83</version> 
    </dependency> 
    <dependency> 
        <groupId>joda-time</groupId> 
        <artifactId>joda-time</artifactId> 
        <version>2.10.14</version> 
    </dependency> 
    <dependency> 
        <groupId>org.apache.commons</groupId> 
        <artifactId>commons-lang3</artifactId> 
        <version>3.11</version> 
    </dependency> 
    <dependency> 
        <groupId>org.apache.httpcomponents</groupId> 
        <artifactId>httpclient</artifactId> 
        <version>4.5.13</version> 
    </dependency> 
    <dependency> 
        <groupId>com.google.guava</groupId> 
        <artifactId>guava</artifactId> 
        <version>30.1.1-jre</version> 
    </dependency> 
    <dependency> 
        <groupId>commons-io</groupId> 
        <artifactId>commons-io</artifactId> 
        <version>2.11.0</version> 
    </dependency>
   <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
       <version>2.0.7</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>2.0.7</version>
    </dependency>
    <dependency>
        <groupId>org.apache.logging.log4j</groupId>
        <artifactId>log4j-core</artifactId>
        <version>2.19.0</version>
   </dependency>
   <dependency>
       <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-api</artifactId>
       <version>2.19.0</version>
   </dependency>

3. 以0.6.75版本的IntelliJ IDEA为例：项目中导入JAR包
   • 在IntelliJ IDEA中选择您的工程，选择“File > Project Structure”。
   • 在Project Structure对话框，左侧单击“Modules”。
   • 在Dependencies页签，选择“+ > JARs or directories”。
   • 在Attach Files or Directories对话框中，选中已下载的JAR文件，单击“OK”。

示例代码

1. log4j2.xml示例如下：

   <?xml version="1.0" encoding="UTF-8"?> 
    <Configuration status="WARN"> 
     
        <Appenders> 
            <!-- projectId：华为云账号的项目ID--> 
            <!-- logGroupId：华为云日志服务日志组ID--> 
            <!-- logStreamId：华为云日志服务日志流ID--> 
            <!-- accessKeyId：华为云账号的AK, 认证用的AK硬编码到代码中或者明文存储都有很大的安全风险, 建议密文存放, 使用时解密, 确保安全--> 
            <!-- accessKeySecret：华为云账号的SK, 认证用的SK硬编码到代码中或者明文存储都有很大的安全风险, 建议密文存放, 使用时解密, 确保安全--> 
            <!-- regionName：云日志服务的区域：单个Appender能缓存的日志大小上限--> 
            <!-- maxBlockMs：producer发送日志时阻塞时间--> 
            <!-- ioThreadCount：执行日志发送任务的线程池大小--> 
            <!-- batchSizeThresholdInBytes：producer发送单批日志量上限--> 
            <!-- batchCountThreshold：producer发送单批日志条数上限--> 
            <!-- lingerMs：producer发送单批日志等待时间--> 
            <!-- retries：producer发送日志失败后重试次数--> 
            <!-- baseRetryBackoffMs：首次重试的退避时间--> 
            <!-- maxRetryBackoffMs：重试的最大退避时间--> 
            <!-- giveUpExtraLongSingleLog：过1M的日志, 拆分后放弃1M以外的--> 
            <!-- enableLocalTest：默认false, true: 可以跨云上报日志, false: 仅能在华为云ecs主机上报日志-->
            <ltsLog name="log4j2sdkappender" 
                    projectId="xxx" 
                    logGroupId="xxx" 
                    logStreamId="xxx" 
                    accessKeyId="xxx" 
                    accessKeySecret="xxx" 
                    regionName="xxx" 
                    totalSizeInBytes="104857600" 
                    maxBlockMs="0" 
                    ioThreadCount="8" 
                    batchSizeThresholdInBytes="524288" 
                    batchCountThreshold="4096" 
                    lingerMs="2000" 
                    retries="5" 
                    baseRetryBackoffMs="500" 
                    maxRetryBackoffMs="500" 
                    giveUpExtraLongSingleLog="true"
                    enableLocalTest="false">
                <PatternLayout pattern="%d %-5level [%thread] %logger{0}: %msg"/> 
            </ltsLog> 
        </Appenders> 
     
        <Loggers> 
            <Root level="WARN"> 
                <AppenderRef ref="log4j2sdkappender"/> 
            </Root> 
        </Loggers> 
     
    </Configuration>

2. 编写代码产生的日志如下：

   package com.huawei.log; 
    
   import org.apache.logging.log4j.LogManager; 
   import org.apache.logging.log4j.Logger; 
    
   public class TestLog4j2AppenderInfo { 
    
       private static final Logger LOGGER = LogManager.getLogger(TestLog4j2AppenderInfo.class); 
    
       public static void main(String[] args) { 
           LOGGER.info("test~log4j2~~~info"); 
       } 
    
   }

单个producer性能基线

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

• totalSizeInBytes：524288000
• ioThreadCount：8
• maxBlockMs：0
• batchSizeThresholdInBytes：524288
• batchCountThreshold：4096
• lingerMs：2000

按照参数基线值设置后，使用8U16GB的机器规格测试，上报单条日志大小为1KB。

测试结果：SDK上报日志的数据量为10MB/s，速率为1.2w条/s。

当日志上报量超过单个producer时：

• 建议拆分日志流，使用多个producer上报日志，分摊流量，以保障SDK处于正常上报状态。
• 如果maxBlockMs为0时，SDK处于非阻塞状态，会触发保护机制自动降级，可能会对部分日志做丢弃处理。
• 如果maxBlockMs大于0时，SDK处于阻塞状态，阻塞时间为maxBlockMs，可能会造成SDK发送日志处于阻塞状态。

配置参数说明

• Appender配置参数说明。

  表1 Appender配置参数说明

  参数名称	描述	类型	是否需要填写	默认值
  projectId	华为云账号的项目ID（project id）。	String	必填	-
  accessKeyId	华为云账号的AK。认证用的AK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。	String	必填	-
  accessKeySecret	华为云账号的SK。认证用的SK硬编码到代码中或者明文存储都有很大的安全风险，建议密文存放，使用时解密，确保安全。	String	必填	-
  regionName	云日志服务的区域。	String	必填	-
  logGroupId	LTS的日志组ID。	String	必填	-
  logStreamId	LTS的日志流ID。	String	必填	-
  totalSizeInBytes	单个producer实例能缓存的日志大小上限。	int	选填	100M（100 * 1024 * 1024）
  maxBlockMs	如果 producer 可用空间不足，调用者在 send 方法上的最大阻塞时间，单位为毫秒。默认为 60 秒（60000毫秒），建议为0秒。 当maxBlockMs值>=0时，则阻塞到设置的时间，如果到达阻塞时间，还是不能获取到内存，即报错且丢弃日志。 当maxBlockMs值=-1时，则一直阻塞到发送成功，且不会丢弃日志。	long	选填	60秒（60000毫秒）
  ioThreadCount	执行日志发送任务的线程池大小。	int	选填	客户机器空闲CPU数量，但一定大于1
  batchSizeThresholdInBytes	当一个 ProducerBatch 中缓存的日志大小大于等于 batchSizeThresholdInBytes 时，该 batch 将被发送。	int	选填	0.5M（512 * 1024）
  batchCountThreshold	当一个 ProducerBatch 中缓存的日志条数大于等于 batchCountThreshold 时，该 batch 将被发送。	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

参数获取方法

• 区域表

  表2 区域表

  区域名称	RegionName
  华北-北京二	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

• 日志组ID：在云日志服务控制台，选择“日志管理”，鼠标悬浮在日志组名称上，可查看日志组名称和日志组ID。
• 日志流ID：单击日志组名称对应的按钮，鼠标悬浮在日志流名称上，可查看日志流名称和日志流ID。