Ctyun Logback Appender概述

Logback是由log4j的创始人设计的一款高性能、灵活配置的Java日志框架。它支持将日志输出到各种目标，如文件、控制台等，并允许通过简单的配置文件自定义日志级别、格式和输出目的地。Logback的特点在于其高效的日志处理能力和强大的配置灵活性，使得开发者能够轻松控制和管理日志，从而更好地监控和调试应用程序。同时，Logback也提供了与多种系统组件的集成支持，为Java应用提供了全面的日志解决方案。

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

__user_agent__  : logback
level  : INFO
location  : cn.ctyun.example.LogbackAppenderExample.main(LogbackAppenderExample.java:22)
message  : info log logback
thread  : main
time  : 2024-06-06T14:33+0800
__message__  : 2024-06-06 14:33:15,203 INFO [main] LogbackAppenderExample: info log logback

其中：

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

功能优势

日志实时传输：

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

无侵入性集成：

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

高效异步处理：

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

版本支持

• logback 1.2.3
• ctyun-lts-java-sdk 1.6.0

使用方式

源码使用

打开编写好的logback源码项目，只需简单修改即可完成使用，方便用户自行扩展修改。

1、maven 工程中引入依赖

在jar包目录执行以下命令，把生成的jar包引入本地maven仓库，或者通过其他方式手动导入。logback SDK 是依赖于ctyun-lts-java-sdk 的日志上传功能，所以需要先导入ctyun-lts-java-sdk 1.6.0 jar包。

mvn install:install-file -Dfile=ctyun-lts-java-sdk-1.6.0.jar -DgroupId=cn.ctyun.lts -DartifactId=ctyun-lts-java-sdk-appender -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 目录下的logback-example.xml 为 logback.xml

3、项目中引入CustomerAppender.java

将appender目录整个移动到您当前的项目中，（如果只单独运行logback项目，则不需要移动），然后logback.xml的appender字段中的 class 指向appednder目录下的CustomerAppender.java类所在位置。

<appender name="AppenderCustomer" class="cn.ctyun.appender.CustomerAppender">

4、 修改配置文件

以xml配置文件 logback.xml为例（若不存在则在项目根目录创建，一般是src/resources/logback.xml），配置自定义的的appender与 Logger，如果您的目录发送改变，class也需改变，指向CustomerAppende.java 类所在位置。此处需要填入5个必填参数，相关参数获取，详情参考天翼云官网云日志服务-SDK接入概述。

  <!-- 此处需要进行用户填写相关配置信息 -->
    <endpoint>your endpoint</endpoint>
    <accessKey>your accessKey</accessKey>
    <secretKey>your secretKey</secretKey>
    <logProject>your log project code</logProject>
    <logUnit>your log unit code</logUnit>

<appender name="AppenderCustomer" class="cn.ctyun.appender.CustomerAppender">
        <!--必填项-->
        <!-- 此处需要进行用户填写相关配置信息 -->
        <endpoint>your endpoint</endpoint>
        <accessKey>your accessKey</accessKey>
        <secretKey>your secretKey</secretKey>
        <logProject>your log project code</logProject>
        <logUnit>your log unit code</logUnit>
        <!-- 可选项 详见 '参数说明'-->
        <totalSizeInBytes>104857600</totalSizeInBytes>
        <maxBlockMs>0</maxBlockMs>
        <ioThreadCount>8</ioThreadCount>
        <batchSizeThresholdInBytes>524288</batchSizeThresholdInBytes>
        <batchCountThreshold>4096</batchCountThreshold>
        <lingerMs>2000</lingerMs>
        <retries>10</retries>
        <baseRetryBackoffMs>100</baseRetryBackoffMs>
        <maxRetryBackoffMs>50000</maxRetryBackoffMs>
        <!-- 可选项 设置时区 -->
        <timeFormat>yyyy-MM-dd'T'HH:mmZ</timeFormat>
        <timeZone>Asia/Shanghai</timeZone>
        <!-- 可选项 通过配置 encoder 的 pattern 自定义 log 的格式 -->
        <encoder>
            <pattern>%d{yyyy-MM-dd'T'HH:mm:ssZ} [%thread] %-5level  %class{36} %x: %msg%n</pattern>
        </encoder>
        <!-- 打印INFO,WARN,ERROR级别的日志,过滤掉INFO 级别以下的日志 -->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>
        <mdcFields>THREAD_ID,MDC_KEY</mdcFields>
    </appender>

5、测试功能是否正常

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

jar包使用

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

1、maven 工程中引入依赖

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

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

在pom.xml 添加以下依赖

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

2、修改配置文件

以xml型配置文件 logback.xml为例（若不存在则在项目根目录创建，一般是src/resources/logback.xml），配置自定义的的appender与 Logger。此处需要填入5个必填参数，相关参数获取，详情参考天翼云官网云日志服务-SDK接入概述。

    <!-- 此处需要进行用户填写相关配置信息 -->
    <endpoint>your endpoint</endpoint>
    <accessKey>your accessKey</accessKey>
    <secretKey>your secretKey</secretKey>
    <logProject>your log project code</logProject>
    <logUnit>your log unit code</logUnit>

   <!--为了防止进程退出时，内存中的数据丢失，请加上此选项-->
    <shutdownHook class="ch.qos.logback.core.hook.DelayingShutdownHook"/>
	 
	<!--自定义的 AppenderCustomer 用于采集 info及以上级别的日志-->
    <appender name="AppenderCustomer" class="cn.ctyun.appender.CustomerAppender">
        <!--必选项-->
        <!-- 此处需要进行用户填写相关配置信息 -->
        <endpoint>your endpoint</endpoint>
        <accessKey>your accessKey</accessKey>
        <secretKey>your secretKey</secretKey>
        <logProject>your log project code</logProject>
        <logUnit>your log unit code</logUnit>
        <!-- 可选项 详见 '参数说明'-->
        <totalSizeInBytes>104857600</totalSizeInBytes>
        <maxBlockMs>0</maxBlockMs>
        <ioThreadCount>8</ioThreadCount>
        <batchSizeThresholdInBytes>524288</batchSizeThresholdInBytes>
        <batchCountThreshold>4096</batchCountThreshold>
        <lingerMs>2000</lingerMs>
        <retries>10</retries>
        <baseRetryBackoffMs>100</baseRetryBackoffMs>
        <maxRetryBackoffMs>50000</maxRetryBackoffMs>
        <!-- 可选项 设置时区 -->
        <timeFormat>yyyy-MM-dd'T'HH:mmZ</timeFormat>
        <timeZone>Asia/Shanghai</timeZone>
        <!-- 可选项 通过配置 encoder 的 pattern 自定义 log 的格式 -->
        <encoder>
            <pattern>%d{yyyy-MM-dd'T'HH:mm:ssZ} [%thread] %-5level  %class{36} %x: %msg%n</pattern>
        </encoder>
        <!-- 打印INFO,WARN,ERROR级别的日志,过滤掉INFO级别以下的日志 -->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>

3、测试功能是否正常

运行您的测试用例，查看控制台是否有日志发送信息的反馈

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
public class LogbackAppenderExample {

    private static final Logger LOGGER = LoggerFactory.getLogger(LogbackAppenderExample.class);

    public static void main(String[] args) {
        LOGGER.trace("trace log logback");   //level 低于info,不会被上传
        LOGGER.debug("debug log logback");   //level 低于info,不会被上传
        LOGGER.info("info log logback");
        LOGGER.warn("warn log logback");
        LOGGER.error("error log logback");
    }
}

反馈结果

15:56:33.813 [main] INFO  org.example.Logback - info log logback
15:56:33.858 [main] WARN  org.example.Logback - warn log logback 
15:56:33.858 [main] ERROR org.example.Logback - error log logback
response: SUCCESS  
response: SUCCESS  
response: SUCCESS  

参数说明

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

#日志服务的 HTTPS 地址，必选参数
<endpoint>your endpoint</endpoint>
#用户身份标识，必选参数
<accessKey>your accessKey</accessKey>
<secretKey>your secretKey</secretKey>
#日志服务的日志项目 project 标识，必选参数
<logProject>your log project code</logProject>
#日志服务的日志单元 unit 标识，必选参数
<logUnit>your log unit code</logUnit>

#单个 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 首次发送失败，能够对其重试的次数，默认为 10 次。
#如果 retries 小于等于 0，该 ProducerBatch 首次发送失败后将直接进入失败队列。
retries=10
#该参数越大能让您追溯更多的信息，但同时也会消耗更多的内存。
maxReservedAttempts=11
#首次重试的退避时间，默认为 100 毫秒。
#Producer 采样指数退避算法，第 N 次重试的计划等待时间为 baseRetryBackoffMs * 2^(N-1)。
baseRetryBackoffMs=100
#重试的最大退避时间，默认为 50 秒。
maxRetryBackoffMs=50000

#输出到日志服务的时间的格式，默认是 yyyy-MM-dd'T'HH:mm:ssZ，可选参数
timeFormat = yyyy-MM-dd'T'HH:mm:ssZ

#输出到日志服务的时间的时区，默认是 UTC，可选参数（如果希望 time 字段的时区为东八区，可将该值设定为 Asia/Shanghai）
timeZone = UTC
#是否要记录 Location 字段（日志打印位置），默认为 true，如果希望减少该选项对性能的影响，可以设为 false
includeLocation = true
#当 encoder 不为空时，是否要包含 message 字段，默认为 true
includeMessage = true

注意：

• CustomerAppender在运行过程中产生的异常会被捕获并放入logback的 BasicStatusManager类中，您可以通过配置 OnConsoleStatusListener或其他方式查看出错信息。如果不想打印这些信息，可以配置NopStatusListener。

回调函数

日志发送成功后的回调函数为CustomerAppender.customCallback() ，该回调函数会返回日志上传的结果，如果想配置其他格式的回调方法，或者使用Logger打印，可以自定义修改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;
}

使用示例

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

logback.xml样例说明

• 配置了两个appender：AppenderCustomer、STDOUT。
• AppenderCustomer：将日志输出到云日志服务中，只上传INFO WARN、ERROR等级别的日志。
• STDOUT：将日志输出到控制台。由于没有对日志级别进行过滤，会输出root中配置的日志级（默认INFO）及以上的所有日志。

如果只想要上传WARN级别以上的日志，可以将AppenderCustomer日志级别设置为WARN即可。

        <!-- 打印WARN,ERROR级别的日志,过滤掉warn 级别以下的日志 -->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>WARN</level>    <!--INFO 改为 WARN-->
        </filter>

常见问题

Q：为何在Spring Boot 启动异常退出？

A：将logback.xml 改成 logback-spring.xml

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

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

<logger name="cn.ctyun.appender" level="OFF"/>

Q：应用初始化时出现这样的信息 A number (N) of logging calls during the initialization phase have been intercepted and are now being replayed. These are subject to the filtering rules of the underlying logging system.

A：该信息只会在日志系统初始化阶段产生，并不影响后续日志记录的功能。

当应用首次调用 LoggerFactory.getLogger()方法时，日志系统进入初始化流程。初始化流程还未结束，再次调用 LoggerFactory.getLogger()方法便会出现上述信息。这时，slf4j 会创建替代记录器（substitute loggers）并返回。在完成初始化后，替代记录器（substitute loggers）会将日志记录请求委托给合适的 logger。