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>

智算服务

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

云日志服务

云日志服务

Ctyun Log4j2 Appender概述

功能优势

版本支持

使用步骤

源码使用

1、maven 工程中引入依赖

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

3、项目中引入CustomerAppender.java

4、修改配置文件

5、测试功能是否正常

jar包使用

1、maven 工程中引入依赖

2、修改配置文件

3、测试功能是否正常

回调函数

参数说明

使用示例

常见问题

活动

智算服务

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

云日志服务

云日志服务

Ctyun Log4j2 Appender概述

功能优势

版本支持

使用步骤

源码使用

1、maven 工程中引入依赖

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

3、项目中引入CustomerAppender.java

4、修改配置文件

5、测试功能是否正常

jar包使用

1、maven 工程中引入依赖

2、修改配置文件

3、测试功能是否正常

回调函数

参数说明

使用示例

常见问题