Ctyun Log4j2 Appender概述

Log4j2 是 log4j 的升级版本。它支持将日志输出到各种目标，如文件、控制台等，并允许通过简单的配置文件自定义日志级别、格式和输出目的地。

通过Ctyun Log4j Appender，您可以将生成的日志信息异步发送到ctyun云日志服务，其样式如下：

__user_agent__  : log4j2
level  : INFO
location  : cn.ctyun.example.Log4j2AppenderExample.main(Log4j2AppenderExample.java:10)
message  : log4j2 info log
thread  : main
time  : 2024-06-06T18:03:06+0800
__message__  : 2024-06-06T18:03:06+0800 [main] INFO cn.ctyun.example.Log4j2AppenderExample: log4j2 info log

其中：

• level：日志级别。
• location：日志打印语句的代码位置 。
• message：日志内容。
• throwable：日志异常信息，只有当记录了异常信息，这个字段才会出现。
• thread：线程名称。
• time：日志打印时间（可以通过 timeFormat 或 timeZone 配置 time 字段呈现的格式和时区）。
• ts：日志生成时的时间。
• message ：日志信息。
• user_agent： 日志来源

功能优势

日志实时传输：

• 实时性增强： 日志数据不再依赖传统的磁盘写入，而是实时通过网络通道发送至服务端，确保数据的即时性。

无侵入性集成：

• 无缝对接： 对于已采用log4j2作为日志框架的应用，我们提供了简洁的配置方案，无需对应用代码进行大幅度修改，即可实现日志的采集与传输。

高效异步处理：

• 高并发设计： 系统采用高并发架构，后台异步处理日志发送任务，即使在大量日志数据产生的情况下，也能保证系统的稳定运行和高效处理。

版本支持

• ctyun-lts-java-sdk 1.6.0

使用步骤

源码使用

打开编写好的log4j2源码项目，只需简单修改即可完成使用，方便用户自行扩展修改。log4j2SDK 是依赖于ctyun-lts-java-sdk 的日志上传功能，所以需要先导入ctyun-lts-java-sdk 1.6.0 jar包。

1、maven 工程中引入依赖

在jar包目录执行以下命令，把ctyun-lts-java-sdk 1.6.0 jar包引入本地maven仓库，或者通过其他方式手动导入。

mvn install:install-file -Dfile=ctyun-lts-java-sdk-1.6.0.jar -DgroupId=cn.ctyun.lts -DartifactId=ctyun-lts-java-sdk -Dversion=1.6.0 -Dpackaging=jar

在pom.xml 添加以下依赖

<dependency>
    <groupId>cn.ctyun.lts</groupId>
    <artifactId>ctyun-lts-java-sdk</artifactId>
    <version>1.6.0</version>
</dependency>

2、重命名resources 目录下的log4j2-example.xml 为 log4j2.xml

3、项目中引入CustomerAppender.java

将appender目录整个移动到您当前的项目中，（如果只单独运行log4j2项目，则不需要移动）。

4、修改配置文件

以xml配置文件 log4j2.xml为例（若不存在则在项目根目录创建，一般是src/resources/log4j2.xml），配置自定义的的appender与 Logger，例如：level="INFO",则会接受INFO,WARN,ERROR 级别的日志，DEBUG,TRACE不会被接收打印。

此处需要填入5个必填参数，相关参数获取，详情参考天翼云官网云日志服务-SDK接入概述。

<CustomerAppender name="AppenderCustomer"
        endpoint="lts log service endpoint"
        accessKey="your accessKey"
        secretKey="your secretKey"
        logProject="your log project code"
        logUnit="your log unit code"
        ......

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN"  >
	<Appenders>
        <CustomerAppender name="AppenderCustomer"
                endpoint="lts log service endpoint"
                accessKey="your accessKey"
                secretKey="your secretKey"
                logProject="your log project code"
                logUnit="your log unit code"
                totalSizeInBytes="104857600"
                maxBlockMs="0"
                ioThreadCount="8"
                batchSizeThresholdInBytes="524288"
                batchCountThreshold="4096"
                lingerMs="2000"
                retries="10"
                baseRetryBackoffMs="100"
                maxRetryBackoffMs="100"
                timeFormat="yyyy-MM-dd'T'HH:mm:ssZ"
                timeZone="UTC"
                ignoreExceptions="true">
            <PatternLayout
                pattern="%d{yyyy-MM-dd'T'HH:mm:ssZ} [%t] %-5level %class{36}: %msg%xEx"/>
        </CustomerAppender>
      </Appenders>
      <Loggers>
        <Root level="INFO">
             <AppenderRef ref="AppenderCustomer" level="INFO"/>
        </Root>
    </Loggers>
</Configuration>

5、测试功能是否正常

运行example目录中的Log4j2AppenderExample.java内的测试用例，查看发送响应是否返回success，以及日志控制台是否成功上传日志信息。

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
public class Log4j2AppenderExample {
    private static final Logger LOGGER = LogManager.getLogger(Log4j2AppenderExample.class);
    public static void main(String[] args) throws InterruptedException {
        LOGGER.trace("log4j2 trace log");    //不会被上传, level低于xml中的INFO
        LOGGER.debug("log4j2 debug log");    //不会被上传, level低于xml中的INFO
        LOGGER.info("log4j2 info log");
        LOGGER.warn("log4j2 warn log");
        LOGGER.error("log4j2 error log",new RuntimeException("error"));
    }
}

反馈结果

18:03:06.055 [main] INFO  cn.ctyun.example.Log4j2AppenderExample : log4j2 info log
18:03:06.093 [main] WARN  cn.ctyun.example.Log4j2AppenderExample : log4j2 warn log
18:03:06.094 [main] ERROR cn.ctyun.example.Log4j2AppenderExample : log4j2 error log
java.lang.RuntimeException: error
	at cn.ctyun.example.Log4j2AppenderExample.main(Log4j2AppenderExample.java:12) [classes/:?]
response: SUCCESS
response: SUCCESS
response: SUCCESS

jar包使用

直接引入ctyun-lts-java-log4j2-appender-1.6.0.jar包，只需要修改配置文件即可使用

1、maven 工程中引入依赖

在jar包目录执行以下命令，把ctyun-lts-java-log4j2-appender-1.6.0.jar包引入本地maven仓库，或者通过其他方式手动导入。

mvn install:install-file -Dfile=ctyun-lts-java-log4j2-appender-1.6.0.jar -DgroupId=cn.ctyun.appender -DartifactId=ctyun-lts-java-log4j2-appender -Dversion=1.6.0 -Dpackaging=jar

在pom.xml 添加以下依赖

<dependency>
    <groupId>cn.ctyun.appender</groupId>
    <artifactId>ctyun-lts-java-log4j2-appender</artifactId>
    <version>1.6.0</version>
</dependency>

2、修改配置文件

以xml配置文件 log4j2.xml为例（若不存在则在项目根目录创建，一般是src/resources/log4j2.xml），配置自定义的的appender与 Logger。例如：level="INFO",则会接受INFO,WARN,ERROR 级别的日志，DEBUG,TRACE不会被接收打印。

此处需要填入5个必填参数，相关参数获取，详情参考天翼云官网云日志服务-SDK接入概述。

<CustomerAppender name="AppenderCustomer"
        endpoint="lts log service endpoint"
        accessKey="your accessKey"
        secretKey="your secretKey"
        logProject="your log project code"
        logUnit="your log unit code"
        ......

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN"  >
	<Appenders>
        <CustomerAppender name="AppenderCustomer"
                endpoint="lts log service endpoint"
                accessKey="your accessKey"
                secretKey="your secretKey"
                logProject="your log project code"
                logUnit="your log unit code"
                totalSizeInBytes="104857600"
                maxBlockMs="0"
                ioThreadCount="8"
                batchSizeThresholdInBytes="524288"
                batchCountThreshold="4096"
                lingerMs="2000"
                retries="3"
                baseRetryBackoffMs="100"
                maxRetryBackoffMs="100"
                timeFormat="yyyy-MM-dd'T'HH:mm:ssZ"
                timeZone="UTC"
                ignoreExceptions="true">
            <PatternLayout
                    pattern="%d{yyyy-MM-dd'T'HH:mm:ssZ} [%t] %-5level %class{36}: %msg%xEx"/>
        </CustomerAppender>

       <Console name="STDOUT" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %C %x: %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">   <!--全局默认level，会被下面level覆盖-->
            <AppenderRef ref="c" level="INFO"/>    <!--只上传INFO及以上级别日志-->
            <AppenderRef ref="STDOUT"/>
         </Root>
        <!-- ignore package -->
        <Logger name="cn.ctyun.lts" level="OFF" additivity="false">
        </Logger>
    </Loggers>
</Configuration>

3、测试功能是否正常

运行测试用例，查看发送响应是否返回success，以及日志控制台是否成功上传日志信息。

18:03:06.055 [main] INFO  cn.ctyun.example.Log4j2AppenderExample : log4j2 info log
18:03:06.093 [main] WARN  cn.ctyun.example.Log4j2AppenderExample : log4j2 warn log
18:03:06.094 [main] ERROR cn.ctyun.example.Log4j2AppenderExample : log4j2 error log
java.lang.RuntimeException: error
	at cn.ctyun.example.Log4j2AppenderExample.main(Log4j2AppenderExample.java:12) [classes/:?]
response: SUCCESS
response: SUCCESS
response: SUCCESS

回调函数

日志发送成功后的回调函数为CustomerAppender.customCallback() ，该回调函数会返回日志上传的结果，如果想配置其他格式的回调方法，或者使用Logger打印，可以自定义修改appender目录下CustomerAppender.java 中的customCallback() 类。

private static Callback customCallback() {
    Callback callback = new Callback() {
        @Override
        public void onCompletion(Result result) {
            // 处理回调结果
            if (result.isSuccessful()) {
                System.out.println("response: "+result.getErrorMessage()+ result.getErrorCode());
            } else {
                System.out.println("response: "+result.getErrorMessage()+ result.getErrorCode());
            }
        }
    };
    return callback;
}

参数说明

Log4j2 Appender 可供配置的属性（参数）如下，其中注释为必选参数的是必须填写的，可选参数在不填写的情况下，使用默认值。

#日志服务的endpoint 地址，必填参数
endpoint="lts log service endpoint"
#用户身份标识，必填参数
accessKey="your accessKey"
secretKey="your secretKey"
#日志服务的日志项目 project 标识，必填参数
logProject="your log project code"
#日志服务的日志单元 unit 标识，必填参数
logUnit="your log unit code"

#单个 producer 实例能缓存的日志大小上限，默认为 100MB。
totalSizeInBytes="104857600"
#如果 producer 可用空间不足，调用者在 send 方法上的最大阻塞时间，默认为 60 秒。为了不阻塞打印日志的线程，强烈建议将该值设置成 0。
maxBlockMs="0"
#执行日志发送任务的线程池大小，默认为可用处理器个数。
ioThreadCount="8"
#当一个 ProducerBatch 中缓存的日志大小大于等于 batchSizeThresholdInBytes 时，该 batch 将被发送，默认为 512 KB，最大可设置成 5MB。
batchSizeThresholdInBytes="524288"
#当一个 ProducerBatch 中缓存的日志条数大于等于 batchCountThreshold 时，该 batch 将被发送，默认为 4096，最大可设置成 40960。
batchCountThreshold="4096"
#一个 ProducerBatch 从创建到可发送的逗留时间，默认为 2 秒，最小可设置成 100 毫秒。
lingerMs="2000"
#如果某个 ProducerBatch 首次发送失败，能够对其重试的次数，默认为3次。
#如果 retries 小于等于 0，该 ProducerBatch 首次发送失败后将直接进入失败队列。
retries="3"
#首次重试的退避时间，默认为 100 毫秒。
#Producer 采样指数退避算法，第 N 次重试的计划等待时间为 baseRetryBackoffMs * 2^(N-1)。
baseRetryBackoffMs="100"
#重试的最大退避时间，默认为 100 毫秒。
maxRetryBackoffMs="100"
#输出到日志服务的时间的格式，默认是 yyyy-MM-dd'T'HH:mm:ssZ，可选参数
timeFormat ="yyyy-MM-dd'T'HH:mm:ssZ"
#输出到日志服务的时间的时区，默认是 UTC，可选参数（如果希望 time 字段的时区为东八区，可将该值设定为 Asia/Shanghai）
timeZone ="UTC"

使用示例

项目中提供了一个名为 cn.ctyun.example.Log4j2AppenderExample的实例，它会加载resources目录下的 log4j2.xml文件进行log4j2配置。

log4j2.xml样例说明

• 配置了三个appender：AppenderWarnAbove、 AppenderInfoOnly、STDOUT。
• AppenderWarnAbove：将日志输出到logProject=test-proj，logUnit=test-unit1。只输出WARN及以上级别的日志。
• AppenderInfoOnly：将日志输出到logProject=test-proj，logUnit=test-unit。只输出INFO级别的日志。
• STDOUT：将日志输出到控制台。由于没有对日志级别进行过滤，会输出root中配置的日志级及以上的所有日志。

如果不需要AppenderInfoOnly配置项 ，可以在xml配置文件中将其删除。

如果需要修改日志上传的日志级别，比如上传info级别及以上日志，可以在修改AppenderWarnAbove 的level，如下：

  <Loggers>
      <Root level="INFO">  <!--全局默认level-->
         <AppenderRef ref="AppenderCustomer" level="WARN"/>   <!--只上传WARN及以上级别日志-->
         <AppenderRef ref="STDOUT"/>
      </Root>
  </Loggers>

常见问题

Q：如何关闭某些类输出的日志？

A：通过在 log4j2.xml 文件中添加 <Logger name="packname" level="OFF"/> 可屏蔽相应包下日志的输出。例如，当您在 log4j2.xml 文件中添加如下内容会屏蔽 package 名为 cn.ctyun.lts 下所有类的日志输出。

 <Loggers>
        ...
        <!-- ignore package -->
        <Logger name="cn.ctyun.lts" level="OFF" additivity="false">
        </Logger>
 </Loggers>n.example" level="OFF"/>
</Loggers>